Help Center
Introduction
Speakeasy use an Azure Automation runbook to automatically generate periodic finance reports and create a PDF document. To create PDF documents, the script needs access to iText7, which is a set of .Net DLLs. To make it easier for iText7 to be accessed from PowerShell, a PowerShell module has been written. The PowerShell module has been uploaded to PowerShell Gallery, an online collection of useful PowerShell modules. When the module is installed from the gallery to either a user’s local interactive PowerShell ISE environment or to Azure, it makes sure that all appropriate iText7 DLLs are installed and iText7 can be used within local scripts or other Azure Automation runbooks.
Instructions
Registration with Powershell Gallery
Paul Cashmore’s Speakeasy email address was first registered as a user in the PowerShell Gallery, so that new powershell modules can be registered (e.g. the iText7 module)
Create a new API key in PowerShell gallery. The key is needed when uploading new modules or updating an existing one to a new version. Click the Copy button to copy it.
The Key is stored in unencrypted form in the Azure Automation variable SpeakeasyNuGetAPIKey. It is stored unencrypted so that it can be accessed using interactive PowerShell scripts, i.e. not executed via an Azure Automation runbook (encrypted Azure Automation variable values can’t be accessed from a script running on a desktop computer). This can probably change once the new Visual Studio code extension is installed, enabling runbooks to be run directly from a user’s desktop computer.
The clientId token will expire after a year so can be regenerated by clicking the Regenerate button under the “API keys – Manage” section. The Azure Automation variable SpeakeasyNuGetAPIKey will need to be updated with this new value.
From a Powershell ISE session, installed the PSScriptAnalyzer using the following command:
Install-Module -Name PSScriptAnalyzer
This module can be used to check scripts for compliance with Powershell good practice – always run before uploading any modules or new module versions to the Powershell gallery. See PS Script Analyzer for more information.
The powershellget-module-master code from github was initially downloaded- it provides a simple example script of how to create and register a simple PowerShell module to a local repository or to the PowerShell gallery repository. A flag in the CreatePSModule.ps1 controls which repository is used. Note: CreatePSModule.ps1 did have a number of bugs and restrictions so it has been extensively modified.
Creating the Module
To create the iText7 Powershell module, the PSWritePDF module was downloaded from the PowerShell gallery and all references to PSWritePDF were changed to IText7. The PSWritePDF module was used as a basis for the iText7 module as PSWritePDF was already configured to load the iText7 DLLs – it provided a wrapper around iText7 but it was found easier to just use the raw .Net libraries given the Speakeasy PDF report is not that complex and a wealth of iText7 examples already exist, albeit in .Net or Java rather than in PowerShell. It is relatively easy to translate .Net calls to PowerShell equivalents.
For very simple modules that don’t require additional DLLs, the powershellget-module code from github (https://github.com/anpur/powershellget-module) can be downloaded- it provides a simple example script Demo.ps1 of how to create and register a simple PowerShell module to a local repository or to the PowerShell gallery repository.
The Demo.ps1 script was heavily modified and renamed to CreatePSModule.ps1 for publishing of the iText7 module. The resulting code can be found here: iText7 PowerShell Module. The script makes reference to the Azure Automation variable SpeakeasyNuGetAPIKey so that it can successfully upload the module to PowerShell gallery.
Note: for the CreatePSModule.ps1 script to work correctly, the following additional modules first need to be installed in PowerShell ISE:
- Install-Module -Name PowerShellGet -Force
- Install-Module NuGet
It is also recommended that the following module be installed:
- Install-Module -Name PSScriptAnalyzer
The PSScriptAnalyzer module can be used to check scripts for compliance with Powershell good practice – always run before uploading any modules or new module versions to the Powershell gallery. See PS Script Analyzer for more information.
Publishing a Module to PowerShell Gallery
Note: to successfully upload modules to the PowerShell Gallery, TLS 2 encryption needs to be enabled in the local PowerShell environment. The following command can be used at the PowerShell ISE command prompt:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Also, the following Windows registry settings need to be configured:
Guidance is to set the following registry values:
Guidance is to set the following registry values:
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
“SchUseStrongCrypto”=dword:00000001
“SchUseStrongCrypto”=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319]
“SchUseStrongCrypto”=dword:00000001
“SchUseStrongCrypto”=dword:00000001
If the following error appears when attempting to publish, first make sure the appropriate NuGet and PowerShellGet modules have been installed – see the previous section above.
Publish-PSArtifactUtility : Failed to publish module ‘CashypModule’: ‘Failed to process request. ‘A client version ‘4.1.0’ or higher is required to
be able to publish packages. Install the latest version of NuGet client or install the latest version of PowerShellGet module using the instructions
provided at https://aka.ms/installing-powershellget. Please contact cgadmin@microsoft.com to get more details.’
be able to publish packages. Install the latest version of NuGet client or install the latest version of PowerShellGet module using the instructions
provided at https://aka.ms/installing-powershellget. Please contact cgadmin@microsoft.com to get more details.’
Installing the PowerShell Module for use with PowerShell scripts
To have access to the iTextModule via a user’s desktop, it needs to be installed using the command
Install-Module -Name IText7Module
To have access to the iTextModule via an Azure Automation runbook, it needs to be installed as follows:
- Either login to PowerShell Gallery, then click on your user name at the top right-hand side and select “Manage Packages”. Select the appropriate package (e.g. iText7Module – although once installed it should need to be done again) and click the Azure Automation tab. from which a “Deploy to Azure Automation” option should appear. Click this to deploy. The user will be prompted to specify an automation account and a resource group, which is a bit clunkier than the second option below.
- (Preferred option) Navigate to Speakeasy Automation…Modules, then click the “Add a Module” option. Specify “Browse from gallery” and click the link to browse the gallery – this will browse the PowerShell module gallery, where the module has been uploaded to. To narrow the search, specify some text in the search box, then click “Select”. Specify 5.1 as the runtime version – some components don’t yet work with 7.1. The module will then be uploaded and hopefully will install correctly. Once installed, the module can be used in an Azure Automation runbook. Just use the InitialiseIText7 command in a PowerShell script to initialise the iText7 DLls. See the Speakeasy-ReportGenerator script for an example