Description

New-ModuleProject.ps1 is a script for easily get started with a new Powershell module project. The script takes care of creating a folder structure, installing the most relevant Powershell modules and even downloads a build script to start building and publishing your module

The script will create a folder structure based on best practices for Powershell module development. But the power of the script is the default build script which will be downloaded to your new Module folder. The build script makes it extremely easy with a simple command to either make a debug compile of your Powershell module for easy testing without messing with your existing .psm1 file, or a complete build of your module, with help documents creation, updated psd1, psm1 files, exporting of both Public and Private functions, and it can even with just setting a parameter to publish your module to PowerShell Gallery.

Example

This script will create a new folder structure in the path: “.”
It will create the following folder structure: MyTestModule

|_Docs
|_Output
|_Source
|      |_Public
|      |_Private
|      |_MyTestModule.psd1
|_Tests
|_build.ps1

It will then make sure you have to following modules installed:

– PowerSehllGet (For publishing modules)
– PlatyPS (For managing Help documentation)
– Pester (For Unit Testing)
– PSScriptAnalyzer (For Lint analyzing scripts)
– InvokeBuild (For building the module) It will then download the build.ps1 script from the GitHub repository

https://raw.githubusercontent.com/ScriptingChris/New-ModuleProject/main/Source/build.ps1 The build script will be used for testing, building, and publishing the module.
Help to use the build script can be found here: https://scriptingchris.tech/new-moduleproject_ps1/

Parameters

Provide the Path to where the module should be placed (without the module name itself

Type:String
Required:true
Aliases:n/a
Position:1
Default value:n/a
Accept pipeline input:false
Accept wildcard chars:false

Provide the name of the Module. Your Module project folder and Module manifest will be named so.

Type:String
Required:true
Aliases:n/a
Position:2
Default value:n/a
Accept pipeline input:false
Accept wildcard chars:false

Switch to tricker if the following modules should be installed on your system: PowerShellGet, Pester, PSScriptAnalyzer, InvokeBuild, and platyPS. The modules are required to be able to use the build.ps1 script for building your module. The parameter is not required, because the first time you try to run the build.ps1 script with Invoke-Build the build.ps1 script will install the dependent modules.

Type:SwitchParameter
Required:false
Aliases:n/a
Position:named
Default value:n/a
Accept pipeline input:false
Accept wildcard chars:false

Switch to tricker if the folder structure should be deployed according to the Path you provided

Type:SwitchParameter
Required:true
Aliases:n/a
Position:named
Default value:n/a
Accept pipeline input:false
Accept wildcard chars:false

Switch to tricker if the build.ps1 should be downloaded to the Module projects folder. The build.ps1 script will be download from the following url: https://raw.githubusercontent.com/ScriptingChris/New-ModuleProject/main/Source/build.ps1

you can also check all the code from the build.ps1 script in the GitHub Repo: https://github.com/ScriptingChris/New-ModuleProject/blob/main/Source/build.ps1

Type:SwitchParameter
Required:false
Aliases:n/a
Position:named
Default value:n/a
Accept pipeline input:false
Accept wildcard chars:false

Documentation

Installing the New-ModuleProject Script:

The script is publicly available on Powershell Gallery or on GitHub for free of use.

Powershell Gallery:

GitHub:

To install it through Powershell run the following command:

You can now run the script by just calling the script from any directory in your Powershell terminal

Creating your first Module Project

To create your first module project run the following command in your Powershell terminal:

This will create a Root folder named: MyTestModule. Inside the root folder, you will see a Docs, Output, Source, and Tests folder. You will also see a build.ps1 script.

  • If your use the build script on your module it will create markdown help files of all your commandlets and place them here. The build script will also use this folder to compile all help files located in it to a single XML help file for the entire module.
  • This folder is where all your builds will be placed. You can use th build.ps1 script to either create a “DebugBuild” which create a temp folder inside the Output folder and places your module inside it. You can also create a “Release” build which creates a folder named as your Module, which will contain all the compiled module files.
  • The source folder contains a Public, a Private folder and your Module manifest. The Manifest is where you will controll all your module informations and control the version of your module. ie if you set version 1.0.1 in your Module manifest, the module will be build as version 1.0.1. The Private folder is for all functions that you commandlets might use but the user cannot call them. The Public folder is for all the commandlets which should be exported in the module for the user to use them.
  • The Tests folder is where you can place all your pester tests. The build.ps1 script will look at all the tests you placed in the folder and run through them to test your code. Remember all tests should be named: <generic_name>.Tests.ps1
  • This script can be used if you want to run the build process on your module

How to use the build.ps1 script

The build.ps1 script can be used as a module builder. It is build to work with the module: InvokeBuild. If you don’t have it installed or didn’t select the switch -Prerequisites when you ran the New-ModuleProject.ps1 script, you will need to install it yourself before you can run the build.ps1 script.

To install InvokeBuild run the following command:

Once you have the module: InvokeBuild installed you are ready to use the script.

The build.ps1 script is configured to run two different kinds of builds. The first build is a “debug” build. This build will output the compiled module to the folder: Outputtemp<ModuleName><version>

This build will not run any cleaning tasks and it will not run any Release/Publishing tasks. The use case of the debug build is when you are developing your module and need to test the imported commandlets. Then you can run a debug build, import the module from the temp folder and then do your tests.

The second build is a “Release” build. This build will output the compiled module to the folder: Output<ModuleName><version>

This build will run the cleaning task which will remove everything from the . Outputtemp folder. It will also if you have provided a NugetAPIKey as a parameter publish the module to Powershell Gallery.

To run a debug build run the following command:

To run a release build run the following command:

You can at any time run the Invoke-Build command with -Verbose to get an verbose output of the build process

To Export function Alias’s you can run the following parameter to the Invoke-Build Command.

-ExportAlias

License

MIT License

Copyright (c) 2021 ScriptingChrisPermission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

This website uses cookies. By continuing to use this site, you accept our use of cookies.