Building a PowerShell cmdlet using C# - Part 4: Packaging the Cmdlet
This is the fourth and last article of the series on how to build a PowerShell cmdlet. On the previous articles we created a simple cmdlet, troubleshooted the code and took a quick tour on the output streams.
Although you can import the dll built by Visual Studio directly as a module, this is not the best approach, since you won't be able to publish it, provide help for your cmdlets and many other features provided by PowerShell modules.
To create a module we'll start by creating a folder with the same name of the module. This is the folder that is going to hold all the module files. We'll call this module DemoCmdlet, since this is the name of the Visual Studio project and the dll produced.
All modules require a module manifest so let's create one with the New-ModuleManifest cmdlet:
The "Path" parameter is the minimum required to run this command. Make sure that you name the manifest file after your module, adding the ".psd1" extension.
Open the manifest with your prefered editor and make any changes necessary on the fields that have been populated by the cmdlet. I usually update the Author and Company properties and convert the version of the module to a four number format.
The next step is to include our cmdlet to the module. Copy the dll file in the module directory and add it to the NestedModules property of the manifest as shown below:
Depending on your PowerShell version, you'll probably have to add the names of the cmdlets in the dll to the "cmdletsToExport" property of the manifest. On Powershell 5, this list is emtpy by default.
The module is now ready to be imported. Move the directory to a PowerShell module file location on your computer such as the WindowsPowerShell\Modules folder in your Documents and the cmdlets inside should be available.
The only thing missing from your module would be the help for the cmdlets inside. Since those are in a dll file, we have to create a help file and copy it to the module folder. These files are pretty complicated and that's why I've been using a program called PowerShell Cmdlet Help Editor.
Fire up the editor and create a new project. If your module is in a predefined module location, it should be able to pick it up:
Double click the module to load it. You should now be able to see the available cmdlets and functions on the left. Clicking on a function or cmdlet will allow you to start adding information about it, such as a description, notes, parameter information, examples, etc.
When you're all done with the cmdlets and their help, export the information to an xml file using the "Publish XML help to file" tool in the "Actions" menu. Now the tricky part. This file has to be saved in a directory named with the proper language code - such as en-us - in the root folder of your module. It should also have a specific name constructed by the name of your module followed by the "-Help" and the .xml extension - in our case "DemoCmdlet-Help.xml".
The structure of the module folder should now be similar to:
If you import the module on a fresh PowerShell host, help should be available for the Get-Demo cmdlet:
Don't forget to save the project on the editor, you don't want to start all over the next time you update your module!
Note here that you can use the help files for script functions as well. It will give you the ability to keep the help for your module organized without updating the script files.
Have fun!
Although you can import the dll built by Visual Studio directly as a module, this is not the best approach, since you won't be able to publish it, provide help for your cmdlets and many other features provided by PowerShell modules.
To create a module we'll start by creating a folder with the same name of the module. This is the folder that is going to hold all the module files. We'll call this module DemoCmdlet, since this is the name of the Visual Studio project and the dll produced.
All modules require a module manifest so let's create one with the New-ModuleManifest cmdlet:
PS C:\DemoCmdlet> New-ModuleManifest -Path DemoCmdlet.psd1
PS C:\DemoCmdlet> ls
Directory: C:\Users\cpolydorou\OneDrive\tmp\Blog\DemoCmdlet
Mode LastWriteTime Length Name
PS C:\DemoCmdlet> ls
Directory: C:\Users\cpolydorou\OneDrive\tmp\Blog\DemoCmdlet
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 11/12/2018 3:38 μμ 7742 DemoCmdlet.psd1
PS C:\DemoCmdlet>
-a--- 11/12/2018 3:38 μμ 7742 DemoCmdlet.psd1
PS C:\DemoCmdlet>
The "Path" parameter is the minimum required to run this command. Make sure that you name the manifest file after your module, adding the ".psd1" extension.
Open the manifest with your prefered editor and make any changes necessary on the fields that have been populated by the cmdlet. I usually update the Author and Company properties and convert the version of the module to a four number format.
The next step is to include our cmdlet to the module. Copy the dll file in the module directory and add it to the NestedModules property of the manifest as shown below:
Depending on your PowerShell version, you'll probably have to add the names of the cmdlets in the dll to the "cmdletsToExport" property of the manifest. On Powershell 5, this list is emtpy by default.
The module is now ready to be imported. Move the directory to a PowerShell module file location on your computer such as the WindowsPowerShell\Modules folder in your Documents and the cmdlets inside should be available.
The only thing missing from your module would be the help for the cmdlets inside. Since those are in a dll file, we have to create a help file and copy it to the module folder. These files are pretty complicated and that's why I've been using a program called PowerShell Cmdlet Help Editor.
Fire up the editor and create a new project. If your module is in a predefined module location, it should be able to pick it up:
Double click the module to load it. You should now be able to see the available cmdlets and functions on the left. Clicking on a function or cmdlet will allow you to start adding information about it, such as a description, notes, parameter information, examples, etc.
When you're all done with the cmdlets and their help, export the information to an xml file using the "Publish XML help to file" tool in the "Actions" menu. Now the tricky part. This file has to be saved in a directory named with the proper language code - such as en-us - in the root folder of your module. It should also have a specific name constructed by the name of your module followed by the "-Help" and the .xml extension - in our case "DemoCmdlet-Help.xml".
The structure of the module folder should now be similar to:
If you import the module on a fresh PowerShell host, help should be available for the Get-Demo cmdlet:
Don't forget to save the project on the editor, you don't want to start all over the next time you update your module!
Note here that you can use the help files for script functions as well. It will give you the ability to keep the help for your module organized without updating the script files.
Have fun!
