PowerShell Studio Projects: Module Project

PowerShell modules are an important part of PowerShell scripting as they provide a means to reuse and share code. The next part in our PowerShell Studio Project series is about the basics of working with module projects in PowerShell Studio.

When creating a module project, there are four options to choose from:

Besides a new module project, you can create a module project from the following:

  • An existing module
  • Help file
  • Functions

Create Module from Existing Module

When selected, you will be prompted to find and select an existing PSD1 or PSM1 file. Once selected, a dialog will prompt asking for additional information.

Module Name

Enter the name you wish to give your new module.

Location

Specify the folder where the module will be saved. The default is PowerShell Studio’s project directory if you select Copy the module to a separate project directory. This option allows you to Create project folder, which creates a folder using the module’s name and places all the generated files within that folder. This folder is created in the folder specified by the Location field.

If you Create the project in the module’s directory, then a folder is created in the same folder as the selected PSM1 or PSD1 file. As a result, you will not be able to specify a location or create a project folder.

Include Git ignore file for temporary project files

Creates a .gitignore file that tells Git which files or folders to ignore in a project. This file is placed in the root folder of a project.

When created, you will have a new module project that includes the help, PSM1, and PSD1 files of the original module. This serves as a good starting point if you are trying to build upon the functionality of an existing module.

Create Module From Help

The Module From Help project allows you to start with an outline for a new script module based on a module help XML file. When selected, you will be prompted to find and select an existing module help XML file. Once selected, a dialog will prompt asking for additional information:

Module Name

Enter the name you wish to give your new module.

Location

Specify the folder where the module will be saved. The default is PowerShell Studio’s project directory.

Create Module Folder

This option creates a folder using the module’s name and places all the generated files within that folder. This folder will be created in the folder specified by the Location field.

Include Git ignore file for temporary project files

Creates a .gitignore file that tells Git which files or folders to ignore in a project. This file is placed in the root folder of a project.

When created, you will have a new module containing the help file and the skeleton functions defined in the help file:

If you aren’t familiar with PowerShell HelpWriter, it is a tool that lets you create external PowerShell help files for existing modules or from scratch. PowerShell HelpWriter is a useful design tool for creating modules by allowing you to plan out your module’s cmdlets and its parameter sets before writing a single line of PowerShell code.

This write-help-first design approach is much easier with PowerShell Studio’s Create Module from Help File project.

Create Module From Functions

Sometimes, you may find that you reuse various functions and constantly copy them into new scripts, or that different variations of the same function are located in different scripts. You may conclude that those functions would better serve you in the form of a module—where all of your scripts can reference the functions in a centralized location. This is where the Module From Functions project comes in handy.

The Module From Functions project allows you to import functions from various PS1 scripts and merge them into a new script module. When you select this project from the menu, it will ask you to select a file (if one is not already open) and present you with the following dialog:

Module Name

Enter the name you wish to give your new module.

Location

Specify the folder where the module will be saved. The default is PowerShell Studio’s project directory.

Create Module Folder

This option creates a folder using the module’s name and places all the generated files within that folder. This folder will be created in the folder specified by the Location field.

Create External XML help file

Creates an XML help file from the selected functions.

Include Git ignore file for temporary project files

Creates a .gitignore file that tells Git which files or folders to ignore in a project. This file is placed in the root folder of a project.

Source Files

Contains the list of files from which the selected functions with be extracted.

Add File

Add ps1 scripts to the Source Files to extract their functions.

Remove File

Removes unnecessary files from the Source Files list, which can help declutter the Functions list.

Functions

The Functions section contains a node for each file and its respective list of functions that are declared in said file.

Use this list to check the functions you wish to import into the new module. If a function references another function, it will have a Referenced Functions folder icon below that contains a list of all the referenced functions:

When you check a function in the list that has references, it will also automatically check all of the referenced functions.

You can check and uncheck the functions in the file by checking/unchecking the file’s node.

This is where you can remove any function you do not wish to be exported by the module.

It is important to note that you may, in some instances, have a duplicate function defined in multiple files. PowerShell Studio will compare these functions; if they are identical, it will only insert the function once. If the functions are different, PowerShell Studio will automatically rename the duplicate. A warning will be displayed in the Output panel when this occurs:

Once finished, the module project will include all the selected functions in the PSM1 file.

Project Files

A new module project will contain three files:

Module Name.psd1 – Contains the module’s manifest.

Module Name.psm1 – Contains all the module’s functions, if any were imported.

Test-Module.ps1 – The file used to test the module. This file will not be included when the module is built.

If the Module project was built from functions or help, there will be an additional file named like this: Module Name.Help.xml. This file contains the PowerShell Xml Help file for the module, generated when the module is created from functions or copied if the module is created from help.

You can have multiple PSD1 and PSM1 files in a module project as long as they are located in a sub-directory and not in the root of the project folder.

Project Settings

These are settings unique to Module projects:

Export to Local Machine

If the application is running as Administrator and this is set to True, the module will be exported to the AllUsers path instead of the CurrentUser path.

Staging Folder Name

When building an MSI installer with our SAPIEN Script Packager, the module will be built in the folder named from the Staging Folder Name property. The files in this folder will be referenced in the Files and Folders tab:

All content in this folder will be filtered from the module project. The default folder name is bin.

Startup Script

This is the script used for testing the module project. The default is Test-Module.ps1, a file generated when the module project is created.

Auto Export Function

This handles function exports automatically.

If set to True, on build, the module project will update the manifest’s FunctionsToExport field with a list of exported functions. To determine which functions are exported, the module project files have an Export Functions property that determines if functions defined in the file are exported:

If a project file’s Export Functions property is set to True, PowerShell Studio will use the functions defined in the file to update the manifest’s FunctionsToExport value:

This property allows you to organize your functions into public (exported) and private (not exported) files. Once configured, you do not need to manually update the manifest when adding, removing, or renaming a function.

Auto Export PS1XML Files

Handles ps1xml exports automatically. If set to True, on build, the module project will update the manifest’s TypesToProcess and FormatsToProcess fields with the list of ps1xml files contained within the project.

Depending on the file’s name, PowerShell Studio will determine which field to use:

FilenameManifest Field
*.Type.ps1xmlTypesToProcess
*.Format.ps1xmlFormatsToProcess

The ps1xml file must be part of the project, and its Build property must be set to Content for it to be included in the manifest.

When you Build the module project, the manifest will update automatically, thus alleviating the previous requirement to update the manifest manually.

For more information on the other general project settings, please refer to our previous article: PowerShell Studio Projects: Introduction – SAPIEN Blog.

Building and Running/Debugging

Running and Debugging

PowerShell Studio will use the Startup Script as an entry point to run or debug the module project. Therefore, it is important that you explicitly import the module in the script. For the generated Test-Module.ps1, this has been done for you:

From this script, you use your module’s functionality to verify that it works as expected.

When running or debugging, the module project will be exported. This is because the exported module is what is being loaded when you are running or debugging. This ensures that the files you see as you debug are the same that PowerShell is using. You can change how the module is imported in the test file to specify the module project.

Building

When you build a module project, it is exported to a PowerShell folder under the environmental variable $PSModulePath. The PowerShell folder will change depending on if you have Windows PowerShell or PowerShell 7 selected and if you are trying to build to the AllUsers path on your machine.

When a module project is open in the Project panel, there are additional buttons included:

From left to right, the buttons are:

  • Open Module Folder opens the module’s exported folder.
  • Clean Module Folder removes all files from the exported PowerShell folder.
  • Build Module builds and exports the module files to the determined PowerShell folder.

Upon building your module project, the Tools Output panel will report information as the project is building:

The output will vary depending on the build settings of your module project. After the module has been exported, the 32 and 64-bit cache that is used for PowerShell Studio’s PrimalSense and module help information will be updated. If you do not wish to have the cache updated on export, there is a setting to turn this off (Options > PowerShell tab):

Feedback

All information provided in this article is based on the functionality available in PowerShell Studio 2022 build 5.8.203.

As always, any feedback is appreciated. If you have a particular type of blog article or product feature request you would like to see, please submit your suggestions on the Wish List and Feature Requests forum or the new Feature Requests page.