Introduction
It is often easier to develop PowerShell scripts that are intended to run in Azure by first running and debugging them on a local desktop computer. This is how the existing Speakeasy scripts have been developed. To do this, a few steps need to be performed to make sure that all the appropriate software is configured on that computer. This document aims to highlight the requirements to ensure successful execution of the scripts on a local computer.
Requirements
PowerShell
The Azure Powershell scripts use two different PowerShell versions. At the time of writing, Speakeasy report generation would not work with V7.1 due to issues with the PDF component, so V5.1 was used. The following link shows the various versions used:
Speakeasy Automation Runbooks in Azure
Install V5.1 and V7.1 of PowerShell – it is recommended this is done using the latest .MSI files
PowerShell Script Locations
All the Powershell scripts are now under git source control. These git repositiories are located in Azure DevOps and can be accessed via the
Azure DevOps Repositories link.
Click on a repo, then click on repos…files. There should be a “clone” link – click this and use the information provided to clone a repositiory to a local folder on your computer – support is provided for the repository to be cloned via Visual Studio code.
Other Scripts
All of the PowerShell scripts have been modified to make use of some common functions, which are all collected together in a PowerShell module called SpeakeasyPSModule. As a consequence, errors may be encountered until the module is installed. Typically, the error that will be displayed will be something similar to that shown below:
The script ‘{script name will be here}.ps1’ cannot be run because the following modules that are specified by the “#requires” statements of the script are
missing: SpeakeasyPSModule.
+ CategoryInfo : ResourceUnavailable: (CompareBankAndX…ionBalances.ps1:String) [], ParentContainsErrorRecordException
+ FullyQualifiedErrorId : ScriptRequiresMissingModules
To install the module, simply open the Start-ModuleBuild.ps1 script in Visual Studio or the Powershell ISE editor, then run it. The module can be found in the SpeakeasyPowershellModule repository, which can be accessed as described in the “Powershell Script Locations” section described above. Once installed, the other scripts that depend upon it can be executed via the same Visual Studio Code or PowerShell ISE session. Note: the Start-ModuleBuild.ps1 script will need to be installed each time Visual Studio Code or PowerShell ISE is restarted, or the above error will re-appear.
Visual Studio Code
For PowerShell 5.1, PowerShell ISE can be used to develop and debug scripts. However, this is being phased out so it is recommended that Visual Studio Code be used. When trying to run PowerShell scripts for the first time in Visual Studio code, the user will be prompted to install additional addins to support PowerShell – when prompted, say yes to install them. The components below can then be installed by executing the stated commands from inside the Visual Studio Code – Terminal window
Note: since this guide was written, a new extension has been added to Visual Studio Code which enable Azure runbooks to be executed directly on the local computer (currently, when developing locally, a copy of the script is made, which is not ideal). Once the extension has been tried, some of the requirements listed below may need to be changed. However, for now, follow these as listed.
Azure Connectivity
Install the modules that are used to establish a connection to Azure:
Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force -AllowClobber
Sharepoint Connectivity
Install the modules that are used to establish a connection to Sharepoint:
Install-Module -Name “PnP.PowerShell”
Exchange Connectivity
Install the modules that are used to establish a connection to Exchange:
Install-Module -Name ExchangeOnlineManagement
Digital Certificate
Many of the Speakeasy PowerShell scripts contain code to make connections to Sharepoint and Exchange. The connection makes use of a digital certificate. The certificate is loaded into Azure for use by scripts which execute as Azure PowerShell runbooks. For scripts that run on a local desktop computer, the certificate must be loaded into a local certificate store. To achieve all of this, there is a PowerShell script, CreatePowershellAppInAzure.ps1, that simplifies this process. This script can be found in the PowerShellAzureResources folder under the PowerShell Scripts repository, accessible via the following link:
Azure DevOps Repositories.
If connectoin issues start to be encountered by PowerShell runbook scripts, check whether the certificate may have expired. The certificate expiry date can be viewed in Azure. Navigate to the
Azure Home Page, then select SpeakeasyAutomation…Certificates. The current certificate expiry can be seen as the first item in the list of certificates. Details of old and expired certificates may also be listed.
Renewing an expired certificate
Launch the CreatePowershellAppInAzure.ps1 and specify the menu option “Create New Azure Automation digital certificate (e.g. if old one has expired)”. The script will then prompt for the certificate name – the default name of “SpeakeasyAppForAzureRunbooks” should suffice, unless multiple certificates are in use.
Specify the number of years before the certificate should expire (one year is recommended as this keeps connectivity less vulnerable to hacking).
The script will then create a new certificate with the configured expiry period, then upload it to Azure for use by Azure PowerShell RunBooks. The certificate will also be loaded into the user’s local certificate store for use in PowerShell scripts that are executed on that user’s desktop computer. See the previous section of this document for details on how to view the current certificate expiry date.
More information on the CreatePowershellAppInAzure.ps1 script can be found here:
Creating a PowerShell App in Azure, which explains how scripts have been configured to access Sharepoint and Azure resources without having to prompt for any security credentials.
Digital Certificate Password
When executing any of the PowerShell scripts for loading or saving digital certificates, use the password which is stored in BitWarden for the entry called “Azure Digital Certificate Password”
Note: If using Visual Studio code to edit/run PowerShell scripts that involve Exchange/Sharepoint/Azure connectivity, it is recommended that Visual Studio code is restarted after the above have been installed, as the environment may not be fully configured without the restart/
Making changes and saving them back to Azure DevOps using git
As mentioned earlier in this guide, scripts are under git version control. To commit changes back to the repository, use the git gui tool and perform the commit and push operations. AnAzureDevops pipeline has been configured so that all successfully pushed changes are automatically copied to the Azure Powershell Runbooks – to view the configuration, navigate to the Azure Home Page, then select “Account Settings”…”Source Control”
Two tabs should appear in the right-hand side of the screen, “Source controls” and “Sync jobs”
Click on “Source controls”…”SpeakeasyAzureRunbooks2” to see the configuration of the repository that handles the update of changes to Azure PowerShell Runbook scripts.
Click on the “Sync jobs” and one of the entries listed to see details of the last set of changes that were updated to the Azure PowerShell Runbook section.