|
| 1 | +# PowerShell Module |
| 2 | + |
| 3 | +This dotnet template will create a new PowerShell module with boilerplate setup for the module and data files. Please make sure to fill in the data file fields and attributes for `Author`, `Description`, `Tags`, and any other relevant fields. Additionally, stubs for a class, public, and private functions as well as Pester tests have been created to get you up and running quickly. |
| 4 | + |
| 5 | +## Getting Started |
| 6 | + |
| 7 | +The following guide will get you started using the template, how to run Pester tests, and how to add classes and functions. |
| 8 | + |
| 9 | +### dotnet new |
| 10 | + |
| 11 | +To set up a new PowerShell module using the dotnet template run the following command |
| 12 | + |
| 13 | +`dotnet new powershell --moduleName <name>` |
| 14 | + |
| 15 | +### Quickstart |
| 16 | + |
| 17 | +example: |
| 18 | + |
| 19 | +```powershell |
| 20 | +dotnet new powershell --moduleName Book |
| 21 | +Import-Module -Name 'Pester' # Make sure you are using the latest version of Pester (eg >= 5.7), see: https://pester.dev/docs/introduction/installation |
| 22 | +Invoke-Pester -Path './Book' |
| 23 | +Import-Module -Name './Book' |
| 24 | +$books = @( |
| 25 | + [Book]::new('Book 1', @{ powershell = 'module' }) |
| 26 | + [Book]::new('Book 2', @{ powershell = 'module' }) |
| 27 | +) |
| 28 | +$books[1].Name |
| 29 | +$books | Find-Book -Name 'Book 1' |
| 30 | +``` |
| 31 | + |
| 32 | +### Adding Classes |
| 33 | + |
| 34 | +Add new classes in the `Classes` folder. Once a new class has been added and you want it to be available when a user imports the module make sure to add it to the `$ExportableTypes` variable in the module file. |
| 35 | + |
| 36 | +### Adding Functions |
| 37 | + |
| 38 | +Public functions should be added in the `Public` folder. New functions also need to be added to the `FunctionsToExport` field in the data file. Private functions should be added in the `Private` folder and will only be accessible from within the module itself. |
| 39 | + |
| 40 | +### Testing |
| 41 | + |
| 42 | +This template comes with boilerplate tests using Pester for the built in files which tests both a function and a method of the class. Make sure you are using the latest version of Pester (`>= 5.7`) - Pester comes pre-installed on Windows 10/Windows Server 2016 with an older version by default and newer versions can be installed side-by-side, see [https://pester.dev/docs/introduction/installation](https://pester.dev/docs/introduction/installation) for installation details. |
| 43 | + |
| 44 | +## Documentation |
| 45 | + |
| 46 | +For PowerShell documentation see, [https://learn.microsoft.com/en-us/powershell/scripting/how-to-use-docs?view=powershell-7.5](https://learn.microsoft.com/en-us/powershell/scripting/how-to-use-docs?view=powershell-7.5). |
| 47 | + |
| 48 | +See [https://learn.microsoft.com/en-us/powershell/scripting/developer/module/how-to-write-a-powershell-module-manifest?view=powershell-7.5](https://learn.microsoft.com/en-us/powershell/scripting/developer/module/how-to-write-a-powershell-module-manifest?view=powershell-7.5) for details on writing a PowerShell module manifest. |
| 49 | + |
| 50 | +For more information about using type accelerators to export classes see, [https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-7.5#exporting-classes-with-type-accelerators](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-7.5#exporting-classes-with-type-accelerators). |
| 51 | + |
| 52 | +For details about PowerShell classes see, [https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-7.5](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-7.5). |
| 53 | + |
| 54 | +For comment based help see, [https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5). |
| 55 | + |
| 56 | +For documentation and information about PowerShell Pester testing see, [https://pester.dev/](https://pester.dev/) and for more details about creatig unit tests within modules see, [https://pester.dev/docs/usage/modules](https://pester.dev/docs/usage/modules). |
0 commit comments