Creating a PowerShell module is an easy way to create scripts you can use over and over again. If you Google this you’ll find that to create a module is as simple as creating a PowerShell Script with the psm1 extension. However, that won’t work for Azure. Azure loads modules automatically, so you need to write your module to load automatically as well. To ensure a module loads correctly, you’ll need to create a module manifest file.
Here’s how you do it.
Step1. Decide on a name.
You can name your modules whatever you want. However, you cannot have the same module loaded twice. Similarly, should you want to list your module in the module gallery, you’ll need to ensure the name is unique. What convention you use, is up to you, but I typically use the company domain name backwards and add the purpose of the module. So, here I am creating a module called au.com.kloud.demo.
Step 2. Create the necessary files
Following my example, I create a folder called au.com.kloud.demo, and inside I need two files: the module and the manifest: au.com.kloud.demo.psm1, and au.com.kloud.demo.psd1.
The easiest way to create the manifest is to run the following command in powershell: new-modulemanifest -path .\au.com.kloud.demo.psd1
Step 3. Update the manifest
The new-modulemanifest command always creates the same file with a unique GUID so you’ll need to edit it before you can use it.
The first thing you need to do with the manifest is adjust the content for your module. Specifically do the following:
- uncomment RootModule and change it to RootModule = ‘au.com.kloud.demo.psm1’
- Change FunctionsToExport to FunctionsToExport = ‘*’
- update the version number
All three steps are important, without the first, no module will actually be loaded, the second step makes sure the actual functions from the module are available and the last is to ensure that you actually track when the module has been updated.
Here is an example of a module manifest.
When creating a module in PowerShell you specify the functions to include using the FunctionsToExport statement. The CmdletsToExport statement is what you would use for binary modules created in C#. As you can see, there is a section for ‘RequiredAssemblies’. You can use that to load dlls that you use in your script and is one way of getting around some of the limitations using assemblies in Azure Automation.
Step 4. Create the module
Now, a module is a basic Powershell script written as a function. Here is an absurdly (and badly written) module:
Step 5. Test
Following tests must be successful, or your module is not going to work when uploading to Azure:
- from PowerShell run test-modulemanifest au.com.kloud.demo\au.com.kloud.demo.psd1 (the command in the module should be listed.)
- copy the au.com.kloud.demo folder with the 2 files into the modules folder of PowerShell. There are several locations such as C:\Windows\System32\WindowsPowerShell\v1.0\Modules. Now close all PowerShell shells, and if you re-open PowerShell, the module should be loaded automatically which you can confirm by trying to run new-compliment -name “something”.
If the above doesn’t work, then the module won’t work in Azure either.
Step 6. Upload
- increment the version number!
- select the au.com.kloud.demo folder, and compress it to au.com.kloud.demo.zip.
- In the automation account, go to modules, click add new module and point to the zip file.
- click OK etc, and after a couple of minutes the module should be available and if you click it, you should see the command you’ve made available.
The module itself is pretty rubbish. We all love cheap flattery, but writing a good PowerShell module requires more than that. See, my step 2 on how make a better module.
Nice one.