Need help with ModuleBuilder?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

PoshCode
255 Stars 44 Forks MIT License 257 Commits 6 Opened issues

Description

A PowerShell Module to help scripters write, version, sign, package, and publish.

Services available

!
?

Need anything else?

Contributors list

The Module Builder Project

This project is an attempt by a group of PowerShell MVPs and module authors to:

  1. Build a common set of tools for module authoring
  2. Encourage a common pattern for organizing PowerShell module projects
  3. Promote best practices for authoring functions and modules

In short, we want to make it easier for people to write great code and produce great modules.

In service of this goal, we intend to produce:

  1. Guidance on using the best of the existing tools: dotnet, Pester, PSDepends, etc.
  2. Module templates demonstrating best practices for organization
  3. Function templates demonstrating best practices for common parameters and error handling
  4. ModuleBuilder module - a set of tools for building modules following these best practices

The ModuleBuilder module

This module is the first concrete step in the project (although it currently consists of only two commands). It represents the collaboration of several MVPs and module authors who had each written their own version of these tools for themselves, and have now decided to collaborate on creating a shared toolset. We are each using the patterns and tools that are represented here, and are committed to helping others to succeed at doing so.

Building from source

Build Status

1. Get the source, obviously

git clone https://github.com/PoshCode/ModuleBuilder.git
cd Modulebuilder

2. Install dependencies

We have a few modules which are required for building. They're listed in

RequiredModules.psd1
-- the
Install-RequiredModule
script installs them (it defaults to CurrentUser scope, but has a
-Scope
parameter if you're running elevated and want to install them for the
AllUsers
). They only change rarely, so you shouldn't need to run this repeatedly, but it does import the modules too, so if you need to use newer versions of these modules (like Pester 5), you can use this to import the ones we need:
./Install-RequiredModule.ps1

3. Run the
build.ps1
script.

By default, the build script uses gitversion to calculate the version of the build automatically, and will put the build in a folder like "ModuleBuilder\2.0.0" where 2.0.0 is the current version number.

./build.ps1

If you don't have

gitversion
handy, you can just specify a version for the
-Semver
parameter:
./build.ps1 -Semver 2.1.0-beta

4. Run tests with Pester

The

test.ps1
script runs Pester and ScriptAnalyzer. It finds the build output from our
build.ps1
script in the default build output location -- that is, right next to these scripts in the root of the repository. It actually removes the
ModuleBuilder
module and re-imports the highest version in that root:
./test.ps1

If you want to test against a different version, you can import it manually and

Invoke-Pester
yourself.
You have a lot of other options here ...

You could import the module explicitly from the output path:

./build.ps1 | Split-Path | Import-Module -Force

You could build into your personal Modules directory, instead:

./build -Output ($Profile | Split-Path | Join-Path -ChildPath Modules)

What's in the module, so far:

Build-Module

Builds a script module from a source project containing one file per function in

Public
and
Private
folders.

The

Build-Module
command is a build task for PowerShell script modules that supports incremental builds.

Convert-CodeCoverage

Takes the output from

Invoke-Pester -Passthru
run against the build output, and converts the code coverage report to the source lines.

A note on build tools

There are several PowerShell build frameworks available. The build task in ModuleBuilder doesn't particularly endorse or interoperate with any of them, but it does accomplish a particular task that is needed by all of them.

A good build framework needs to support incremental builds and have a way to define build targets which have dependencies on other targets, such that it can infer the target build order.

A good build framework should also include pre-defined tasks for most common build targets, including restoring dependencies, cleaning old output, building and assembling a module from source, testing that module, and publishing the module for public consumption. Our

Build-Module
command, for instance, is just one task of several which would be needed for a build target for a PowerShell script module.

Organizing Your Module

For best results, you need to organize your module project similarly to how this project is organized. It doesn't have to be exact, because nearly all of our conventions can be overriden, but the module is opinionated, so if you follow the conventions, it should feel wonderfully automatic.

  1. Create a
    source
    folder with a
    build.psd1
    file and your module manifest in it
  2. In the
    build.psd1
    specify the relative Path to your module's manifest, e.g.
    @{ Path = "ModuleBuilder.psd1" }
  3. In your manifest, make sure a few values are not commented out. You can leave them empty, because they'll be overwritten:
    • FunctionsToExport
      will be updated with the file names that match the
      PublicFilter
    • AliasesToExport
      will be updated with the values from
      [Alias()]
      attributes on commands
    • Prerelease
      and
      ReleaseNotes
      in the
      PSData
      hashtable in
      PrivateData

Once you start working on the module, you'll create sub-folders in source, and put script files in them with only one function in each file. You should name the files with the same name as the function that's in them -- especially in the public folder, where we use the file name (without the extension) to determine the exported functions.

  1. By convention, use folders named "Classes" (and/or "Enum"), "Private", and "Public"
  2. By convention, the functions in "Public" will be exported from the module (you can override the
    PublicFilter
    )
  3. To force classes to be in a certain order, you can prefix their file names with numbers, like
    01-User.ps1

There are a lot of conventions in

Build-Module
, expressed as default values for its parameters. These defaults are documented in the help for Build-Module. You can override any parameter to
Build-Module
by passing it, or by adding keys to the
build.psd1
file with your preferences.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.