feat: Provide script to upsert an app setting within an Azure App Ser…

…vice (#268)

Co-authored-by: Stijn Moreels <[email protected]>
Co-authored-by: Pim Simons <[email protected]>

docs/preview/01-index.md

@@ -19,6 +19,7 @@ For more granular packages we recommend reading the documentation.
 # Features
 
 * Automate Azure API Management tasks ([powershell](features/powershell/azure-api-management))
+* Automate Azure App Service tasks ([powershell](features/powershell/azure-app-service))
 * Automate Azure Data Factory tasks ([powershell](features/powershell/azure-data-factory))
 * Automate Azure DevOps tasks ([powershell](features/powershell/azure-devops))
 * Automate Azure Integration Account tasks ([powershell](features/powershell/azure-integration-account))

docs/preview/02-Features/powershell/azure-app-service.md

@@ -0,0 +1,41 @@
+---
+title: "Azure App Service"
+layout: default
+---
+
+# Azure App Service
+
+This module provides the following capabilities:
+- [Set an app setting within an Azure App Service](#set-an-app-setting-within-an-azure-app-service)
+
+## Installation
+
+To have access to the following features, you have to import the module:
+
+```powershell
+PS> Install-Module -Name Arcus.Scripting.AppService
+```
+
+## Set an app setting within an Azure App Service
+
+Create/update a single application setting within an Azure App Service.
+
+| Parameter                     | Mandatory   | Description                                                                                           |
+| ----------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| `ResourceGroupName`           | yes         | The name of the Azure resource group where the Azure Integration Account is located.                  |
+| `AppServiceName`              | yes         | The name of the Azure App Service where the application setting will be created/updated.              |
+| `AppServiceSettingName`       | yes         | The name of the application setting that will be created/updated.                                     |
+| `AppServiceSettingValue`      | yes         | The value of the application setting that will be created/updated.                                    |
+| `PrintSettingValuesIfVerbose` | no          | Indicator (switch) whether the values of the application settings will be written to the verbose log. |
+
+**Example**  
+
+Setting an application setting within an Azure App Service.  
+```powershell
+PS> Set-AzAppServiceSetting -ResourceGroupName 'my-resource-group' -AppServiceName 'my-app-service' -AppServiceSettingName 'my-app-setting' -AppServiceSettingValue 'my-value'
+# Checking if the App Service with name 'my-app-service' can be found in the resource group 'my-resource-group'
+# App service has been found
+# Extracting the existing application settings
+# Setting the application setting 'my-app-setting'
+# Successfully set the application setting 'my-app-setting' of the App Service 'my-app-service' within resource group 'my-resource-group'
+```

src/Arcus.Scripting.AppService/Arcus.Scripting.AppService.psd1

@@ -0,0 +1,127 @@
+#
+# Module manifest for module 'module'
+#
+# Generated by: Arcus
+#
+# Generated on: 5/29/2020 10:12:26 AM
+#
+
+@{
+
+# Script module or binary module file associated with this manifest.
+RootModule = 'Arcus.Scripting.AppService.psm1'
+
+# Version number of this module.
+ModuleVersion = '#{Package.Version}#'
+
+# ID used to uniquely identify this module
+GUID = 'ef97d51b-87bb-4daa-b97c-b59f08da8009'
+
+# Author of this module
+Author = 'Arcus'
+
+# Company or vendor of this module
+CompanyName = ''
+
+# Copyright statement for this module
+Copyright = '(c) 2020 Arcus. All rights reserved.'
+
+# Description of the functionality provided by this module
+Description = 'Scripts related to Azure App Service'
+
+# Minimum version of the Windows PowerShell engine required by this module
+PowerShellVersion = '5.1'
+
+# Name of the Windows PowerShell host required by this module
+# PowerShellHostName = ''
+
+# Minimum version of the Windows PowerShell host required by this module
+# PowerShellHostVersion = ''
+
+# Minimum version of Microsoft .NET Framework required by this module
+# DotNetFrameworkVersion = ''
+
+# Minimum version of the common language runtime (CLR) required by this module
+# CLRVersion = ''
+
+# Processor architecture (None, X86, Amd64) required by this module
+# ProcessorArchitecture = ''
+
+# Modules that must be imported into the global environment prior to importing this module
+RequiredModules = @(@{ModuleName='Az.Websites'; ModuleVersion='2.9.0'})
+
+# Assemblies that must be loaded prior to importing this module
+# RequiredAssemblies = @()
+
+# Script files (.ps1) that are run in the caller's environment prior to importing this module.
+# ScriptsToProcess = @()
+
+# Type files (.ps1xml) to be loaded when importing this module
+# TypesToProcess = @()
+
+# Format files (.ps1xml) to be loaded when importing this module
+# FormatsToProcess = @()
+
+# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
+# NestedModules = @()
+
+# Functions to export from this module
+FunctionsToExport = @(
+    'Set-AzAppServiceSetting')
+
+# Cmdlets to export from this module
+CmdletsToExport = '*'
+
+# Variables to export from this module
+VariablesToExport = '*'
+
+# Aliases to export from this module
+AliasesToExport = '*'
+
+# List of all modules packaged with this module
+# ModuleList = @()
+
+# List of all files packaged with this module
+# FileList = @()
+
+# Private data to pass to the module specified in RootModule/ModuleToProcess
+PrivateData = @{
+
+    PSData = @{
+
+        # Tags applied to this module. These help with module discovery in online galleries.
+        Tags = 'Azure','AppService', 'Arcus'
+
+        # A URL to the license for this module.
+        LicenseUri = 'https://github.com/arcus-azure/arcus.scripting/blob/master/LICENSE'
+
+        # A URL to the main website for this project.
+        ProjectUri = 'https://github.com/arcus-azure/arcus.scripting'
+
+        # A URL to an icon representing this module.
+        IconUri = 'https://raw.githubusercontent.com/arcus-azure/arcus/master/media/arcus.png'
+
+        # ReleaseNotes of this module
+        ReleaseNotes = 'https://github.com/arcus-azure/arcus.scripting/releases/tag/v#{Package.Version}#'
+
+        # Prerelease string of this module
+        # Prerelease = ''
+
+        # Flag to indicate whether the module requires explicit user acceptance for install/update/save
+        # RequireLicenseAcceptance = $false
+
+        # External dependent modules of this module
+        # ExternalModuleDependencies = @()
+
+    } # End of PSData hashtable
+
+ } # End of PrivateData hashtable
+
+
+# HelpInfo URI of this module
+# HelpInfoURI = ''
+
+# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
+# DefaultCommandPrefix = ''
+
+}

src/Arcus.Scripting.AppService/Arcus.Scripting.AppService.psm1

@@ -0,0 +1,40 @@
+<#
+ .Synopsis
+  Sets the value of an application setting within an Azure App Service.
+
+ .Description
+  The Set-AzAppServiceSetting cmdlet sets the value of an application setting within an Azure App Service.
+
+ .Parameter ResourceGroupName
+  The name of the of resource group under which the App Service exists.
+
+ .Parameter AppServiceName
+  The name of the App Service.
+
+ .Parameter AppServiceSettingName
+  The name of the application setting.
+
+ .Parameter AppServiceSettingValue
+  The value to be used for the application setting.
+
+ .Parameter PrintSettingValuesIfVerbose
+  Indicate whether or not to print the values of the current application settings in the verbose logging.
+#>
+function Set-AzAppServiceSetting {
+    param(
+        [Parameter(Mandatory = $true)][string] $ResourceGroupName = $(throw "Resource group name is required"),
+        [Parameter(Mandatory = $true)][string] $AppServiceName = $(throw = "App Service name is required"),
+        [Parameter(Mandatory = $true)][string] $AppServiceSettingName = $(throw "App Service setting name is required"),
+        [Parameter(Mandatory = $true)][string] $AppServiceSettingValue = $(throw "App Service value is required"),
+        [Parameter(Mandatory = $false)][switch] $PrintSettingValuesIfVerbose = $false
+    )
+
+    if($PrintSettingValuesIfVerbose) {
+        . $PSScriptRoot\Scripts\Set-AzAppServiceSetting.ps1 -ResourceGroupName $ResourceGroupName -AppServiceName $AppServiceName -AppServiceSettingName $AppServiceSettingName -AppServiceSettingValue $AppServiceSettingValue -PrintSettingValuesIfVerbose
+    } else {
+        . $PSScriptRoot\Scripts\Set-AzAppServiceSetting.ps1 -ResourceGroupName $ResourceGroupName -AppServiceName $AppServiceName -AppServiceSettingName $AppServiceSettingName -AppServiceSettingValue $AppServiceSettingValue
+    }
+
+}
+
+Export-ModuleMember -Function Set-AzAppServiceSetting

src/Arcus.Scripting.AppService/Arcus.Scripting.AppService.pssproj

@@ -0,0 +1,39 @@
+<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectGuid>{342747e9-6406-4da8-b238-37335adba79c}</ProjectGuid>
+    <OutputType>Exe</OutputType>
+    <RootNamespace> Arcus.Scripting.AppService</RootNamespace>
+    <AssemblyName> Arcus.Scripting.AppService</AssemblyName>
+    <Name>Arcus.Scripting.AppService</Name>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>full</DebugType>
+    <Optimize>false</Optimize>
+    <OutputPath>bin\Debug\</OutputPath>
+    <DefineConstants>DEBUG;TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
+    <DebugType>pdbonly</DebugType>
+    <Optimize>true</Optimize>
+    <OutputPath>bin\Release\</OutputPath>
+    <DefineConstants>TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+  </PropertyGroup>
+  <ItemGroup>
+    <Folder Include="Scripts\" />
+  </ItemGroup>
+  <ItemGroup>
+    <Compile Include="Arcus.Scripting.AppService.psd1" />
+    <Compile Include="Arcus.Scripting.AppService.psm1" />
+    <Compile Include="Scripts\Set-AzAppServiceSetting.ps1" />
+  </ItemGroup>
+  <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
+  <Target Name="Build" />
+  <Import Project="$(MSBuildExtensionsPath)\PowerShell Tools for Visual Studio\PowerShellTools.targets" Condition="Exists('$(MSBuildExtensionsPath)\PowerShell Tools for Visual Studio\PowerShellTools.targets')" />
+</Project>

src/Arcus.Scripting.AppService/Scripts/Set-AzAppServiceSetting.ps1

@@ -0,0 +1,50 @@
+param(
+    [Parameter(Mandatory = $true)][string] $ResourceGroupName = $(throw "Resource group name is required"),
+    [Parameter(Mandatory = $true)][string] $AppServiceName = $(throw "App Service name is required"),
+    [Parameter(Mandatory = $true)][string] $AppServiceSettingName = $(throw "App Service setting name is required"),
+    [Parameter(Mandatory = $true)][string] $AppServiceSettingValue = $(throw "App Service value is required"),
+    [Parameter(Mandatory = $false)][switch] $PrintSettingValuesIfVerbose = $false
+)
+
+Write-Host "Checking if the App Service with name '$AppServiceName' can be found in the resource group '$ResourceGroupName'"
+$appService = Get-AzWebApp -ResourceGroupName $ResourceGroupName -Name $AppServiceName -ErrorAction Ignore
+
+if ($appService -eq $null) {
+    throw "No App Service with name '$AppServiceName' could be found in the resource group '$ResourceGroupName'"
+}
+
+Write-Host "Azure App service has been found for name '$AppServiceName' in the resource group '$ResourceGroupName'"
+Write-Host "Extracting the existing application settings from Azure App Service"
+$appServiceSettings = $appService.SiteConfig.AppSettings
+
+$existingSettings = @{ }
+Write-Verbose "Existing Azure App Service application settings:"
+foreach ($setting in $appServiceSettings) {
+    $existingSettings[$setting.Name] = $setting.value
+    if ($PrintSettingValuesIfVerbose) {
+        Write-Verbose "$($setting.Name): $($setting.Value)"
+    } else {
+        Write-Verbose "$($setting.Name)"
+    }
+}
+
+$existingSettings[$AppServiceSettingName] = $AppServiceSettingValue
+
+Write-Host "Setting the application setting '$AppServiceSettingName'"
+try 
+{
+    $updatedAppService = Set-AzWebApp -ResourceGroupName $ResourceGroupName -Name $appServiceName -AppSettings $existingSettings
+
+    Write-Verbose "Updated Azure App Service settings:"
+    foreach ($setting in $updatedAppService.SiteConfig.AppSettings) {
+        if ($PrintSettingValuesIfVerbose) {
+            Write-Verbose "$($setting.Name): $($setting.Value)"
+        } else {
+            Write-Verbose "$($setting.Name)"
+        }
+    }
+} catch {
+    throw "The Azure App Service settings could not be updated. Details: $($_.Exception.Message)"
+}
+
+Write-Host "Successfully set the application setting '$AppServiceSettingName' of the Azure App Service '$AppServiceName' within Azure resource group '$ResourceGroupName'"

src/Arcus.Scripting.Tests.Integration/Arcus.Scripting.AppService.tests.ps1

@@ -0,0 +1,79 @@
+Import-Module -Name $PSScriptRoot\..\Arcus.Scripting.AppService -ErrorAction Stop
+
+InModuleScope Arcus.Scripting.AppService {
+    Describe "Arcus Azure App Service integration tests" {
+        BeforeEach {
+            $config = & $PSScriptRoot\Load-JsonAppsettings.ps1 -fileName "appsettings.json"
+            & $PSScriptRoot\Connect-AzAccountFromConfig.ps1 -config $config
+        }
+        Context "Setting an Azure App Service application setting" {
+            It "Try to set an application setting to unexisting App Service fails" {
+                # Arrange
+                $ResourceGroupName = $config.Arcus.ResourceGroupName
+                $AppServiceName = "unexisting-appservice"
+                $AppServiceSettingName = "somesetting"
+                $AppServiceSettingValue = "somevalue"
+
+                # Act
+                { Set-AzAppServiceSetting -ResourceGroupName $ResourceGroupName -AppServiceName $AppServiceName -AppServiceSettingName $AppServiceSettingName -AppServiceSettingValue $AppServiceSettingValue -ErrorAction Stop } | 
+                    Should -Throw
+            }
+            It "Creating a new application setting and setting its value succeeds" {
+                # Arrange
+                $ResourceGroupName = $config.Arcus.ResourceGroupName
+                $AppServiceName = $config.Arcus.AppService.Name
+                $AppServiceSettingName = "setting-$([System.Guid]::NewGuid())"
+                $AppServiceSettingValue = [guid]::NewGuid()
+
+                try {
+                    # Act
+                    Set-AzAppServiceSetting -ResourceGroupName $ResourceGroupName -AppServiceName $AppServiceName -AppServiceSettingName $AppServiceSettingName -AppServiceSettingValue $AppServiceSettingValue
+
+                    # Assert
+                    $actual = Get-AzWebApp -ResourceGroupName $ResourceGroupName -Name $AppServiceName
+                    $actual | Should -Not -BeNullOrEmpty 
+
+                    $settings = @{ }
+                    foreach ($setting in $actual.SiteConfig.AppSettings) {
+                        $settings[$setting.Name] = $setting.value
+                    }    
+
+                    $settings[$AppServiceSettingName] | Should -BeExactly $AppServiceSettingValue
+                } finally {
+                    $appService = Get-AzWebApp -ResourceGroupName $ResourceGroupName -Name $AppServiceName
+                    $appServiceSettings = $appService.SiteConfig.AppSettings
+
+                    $settingsWithoutTestSetting = @{ }
+                    foreach ($setting in $appServiceSettings) {
+                        if ($setting.Name -ne $AppServiceSettingName) {
+                            $settingsWithoutTestSetting[$setting.Name] = $setting.value
+                        }
+                    }
+
+                    Set-AzWebApp -ResourceGroupName $ResourceGroupName -Name $appServiceName -AppSettings $settingsWithoutTestSetting
+                }
+            }
+            It "Update an existing application setting and setting its value succeeds" {
+                # Arrange
+                $ResourceGroupName = $config.Arcus.ResourceGroupName
+                $AppServiceName = $config.Arcus.AppService.Name
+                $AppServiceSettingName = "existing-setting"
+                $AppServiceSettingValue = [guid]::NewGuid()
+
+                # Act
+                Set-AzAppServiceSetting -ResourceGroupName $ResourceGroupName -AppServiceName $AppServiceName -AppServiceSettingName $AppServiceSettingName -AppServiceSettingValue $AppServiceSettingValue
+
+                # Assert
+                $actual = Get-AzWebApp -ResourceGroupName $ResourceGroupName -Name $AppServiceName
+                $actual | Should -Not -BeNullOrEmpty 
+
+                $settings = @{ }
+                foreach ($setting in $actual.SiteConfig.AppSettings) {
+                    $settings[$setting.Name] = $setting.value
+                }    
+
+                $settings[$AppServiceSettingName] | Should -BeExactly $AppServiceSettingValue
+            }
+        }
+    }
+}