DOCSEARCHbyAlgolia
Submit Docs

ModuleBuilder Documentation

repository·main·Indexed 19 days ago

https://github.com/poshcode/modulebuilder

A PowerShell tool for authoring modules using a multi-file structure that compiles into a single, high-performance .psm1 file. It simplifies the development lifecycle by providing tools for module creation, version management, signing, packaging, and publishing. Key features include the Build-Module command, script generators for Aspect-Oriented Programming (AOP), and utilities for translating line numbers and breakpoints between source files and the compiled output.

Tokens
3.6K
Snippets
9
Records
23
Agent score
68%

What's inside ModuleBuilder

  1. Overview of ModuleBuilder

    main
    ModuleBuilder is a PowerShell module designed to simplify the entire lifecycle of PowerShell script module development. It provides tools to help scripters write, version, sign, package, and publish their modules with increased ease and consistency. The module aims to provide a structured project format that facilitates both individual development and community contributions.

  2. Overview of Module Builder

    main

    Module Builder is a tool designed to simplify the authoring of PowerShell script modules. It allows developers to organize their source code into multiple files (one per function) for better maintainability, while ultimately compiling them into a single .psm1 file.

    Shipping as a single file is recommended for:

    • Performance: Faster loading and execution.
    • Compatibility: Full support for PowerShell classes and using statements.
    • Security: Easier code-signing, as only one file's signature needs to be checked.
    • State Management: Enables the use of module-scope variables to share state between functions.

  3. How Merge-ScriptBlock generator works

    main

    The Merge-ScriptBlock generator is used for Aspect-Oriented Programming (AOP). It wraps the content of the begin, process, or end script blocks of functions with provided boilerplate code.

    You can use wildcard patterns to specify which functions should have this boilerplate injected. This is ideal for adding cross-cutting concerns like logging, timing, or error handling to all functions in a module without duplicating the code in every function.

  4. ModuleBuilder Feature Capabilities

    main

    ModuleBuilder provides a suite of features categorized into the following lifecycle stages:

    Module Creation

    • Generates build folders, .psd1 (module manifests), and .psm1 (script module) files.
    • Facilitates GitHub repository creation and linking.
    • Automates GitHub setup, including building Wiki pages, GitHub Pages sites, and generating README.md files with guided checklists.
    • Provides a wizard-driven UI to run cmdlets.

    Module Management

    • Handles version management.
    • Manages help file creation and publication (e.g., converting comment-based help to XML/language-based help).
    • Automatically adds functions and files to .psd1 and .psm1 files based on naming conventions.

    File Tools

    • Cleans files (expanding aliases, formatting, etc.).
    • Runs files against PSAnalyzer.
    • Includes a GUI-based Function Builder to create function shells, parameters, and XML-based help files.

    Testing, Signing, and Packaging

    • Testing: Helps build test suites, inserts test folders, and provides AppVeyor setup (.yml).
    • Signing: Automatically signs scripts during the release process.
    • Packaging: Creates packages for OneGet, NuGet, or other formats.
    • Release: Publishes modules to GitHub Releases, Chocolatey, or the PowerShell Gallery.

  5. How ConvertTo-Script generator works

    main
    The ConvertTo-Script generator is a packaging tool. It takes a complete module (including its assemblies) and the name of a specific function. It then outputs a standalone .ps1 script file named after that function. This script contains the entire module embedded within it, allowing the single script to be distributed and run (e.g., from a network share) without requiring the module to be formally installed.

  6. How Move-UsingStatement generator works

    main
    The Move-UsingStatement generator manages using statements. It comments out using statements found within individual source files, sorts them, and moves a single unique copy of each statement to the very top of the final, built module file. This allows you to keep using statements near the functions they serve in your source files while maintaining a clean, consolidated header in the output.

  7. How Add-Parameter generator works

    main
    The Add-Parameter generator works in conjunction with Merge-ScriptBlock. It allows you to copy parameter sets from one script function to another. This enables developers to define common parameter sets once and apply them across multiple functions, while encapsulating implementation details within the injected script blocks.

  8. How Update-AliasesToExport generator works

    main
    The Update-AliasesToExport generator modifies the module manifest rather than the source code. It scans for [Alias()] attributes, New-Alias, Set-Alias, and Remove-Alias commands to automatically update the list of exported aliases in the final module manifest, ensuring all declared aliases are properly exported.

  9. Organize your PowerShell module repository for ModuleBuilder

    main

    ModuleBuilder is an opinionated tool that expects a specific directory structure to automate compiling your module into a single .psm1 file, running Pester tests, and reporting accurate code coverage.

    To use ModuleBuilder, organize your repository following these conventions:

    1. Source Folder: Create a Source folder at the root of your repository.
    2. Build Configuration: Place a build.psd1 file inside the Source folder.
    3. Module Manifest: Place your module manifest (e.g., MyModule.psd1) inside the Source folder.
    4. Function Organization:
      • Create a Private folder inside Source for internal functions.
      • Create a Public folder inside Source for exported functions.
      • File Naming: Create one .ps1 file per function. Files in the Public folder must use the Verb-Noun format (e.g., Get-Data.ps1) as these will be exported without the extension.
    5. Tests: Create a Tests folder at the root to house your Pester tests (organized into Private and Public subfolders to match your source).

    Recommended Directory Structure

    MyModule
├───Source
│   │   build.psd1
│   │   MyModule.psd1
│   │   ...
│   ├───Private
│   │       Internal-Function.ps1
│   └───Public
│           │       Public-Function.ps1
└───Tests
    ├───Private
    └───Public

  10. Create a custom dotnet template alias for ModuleBuilder

    main

    To speed up your workflow, you can create a custom alias for the PSModuleBuilder template. This allows you to pre-define common values like --author and --company so you only need to provide unique details (like the module name or description) when generating new modules.

    # Create an alias named 'psmo' with default author and company
dotnet new -a psmo psmodulebuilder --author Jaykul --company PoshCode.org

# Use the alias to quickly create a new module
dotnet new psmo -o MyNewModule --description "My Brand New Module"

  12. Build ModuleBuilder from source

    main

    You can build the ModuleBuilder project itself using one of two methods:

    Method 1: Using Earthbuild (Recommended)

    This is the fastest method and uses containers to manage dependencies and parallelize steps. Requires WSL2, Docker Desktop, and the Earthbuild CLI.

    git clone https://github.com/PoshCode/ModuleBuilder.git
cd ModuleBuilder
earth +test

    Method 2: Manual Build (Without Earthbuild)

    Requires the .NET SDK to be installed manually. You must also clone the Tasks repository as a sibling to the ModuleBuilder folder.

    git clone https://github.com/PoshCode/ModuleBuilder.git
git clone https://github.com/PoshCode/Tasks.git

cd ModuleBuilder
./build.build.ps1