https://github.com/claudiospizzi/PSInvokeBuildHelper
Common build tasks for the Invoke-Build PowerShell module.
https://github.com/claudiospizzi/PSInvokeBuildHelper
Last synced: 3 months ago
JSON representation
Common build tasks for the Invoke-Build PowerShell module.
- Host: GitHub
- URL: https://github.com/claudiospizzi/PSInvokeBuildHelper
- Owner: claudiospizzi
- License: mit
- Created: 2019-09-18T19:14:33.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-02-06T14:15:07.000Z (about 2 years ago)
- Last Synced: 2024-08-13T07:05:30.437Z (6 months ago)
- Language: PowerShell
- Size: 172 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - claudiospizzi/PSInvokeBuildHelper - Common build tasks for the Invoke-Build PowerShell module. (PowerShell)
README
[](https://www.powershellgallery.com/packages/InvokeBuildHelper)
[](https://www.powershellgallery.com/packages/InvokeBuildHelper)
[](https://github.com/claudiospizzi/PSInvokeBuildHelper/releases)
[](https://github.com/claudiospizzi/PSInvokeBuildHelper/actions/workflows/ci.yml)
# InvokeBuildHelper PowerShell Module
Common build tasks for the [Invoke-Build](https://github.com/nightroman/Invoke-Build) PowerShell module.
## Introduction
This module includes a script with common build tasks for a PowerShell module. A manifest module using script files is the main target. The module can include some C# .NET based libraries, they will be build with Release options before the build script runs. The core build script with all tasks can be found here:
* [InvokeBuildHelper/Scripts/InvokeBuildHelperTasks.ps1](https://github.com/claudiospizzi/PSInvokeBuildHelper/blob/master/InvokeBuildHelper/Scripts/InvokeBuildHelperTasks.ps1)
## Features
### Build Script
Even the module exports multiple command with the *IBH* prefix, only the build
script should be used. The following example of a `.build.ps1` script can be
used, if the repository is hosted on GitHub and the module is published to the
official PowerShell Gallery:
```powershell
# Import build tasks
. InvokeBuildHelperTasks
# Build configuration
$IBHConfig.VerifyTask.Enabled = $false
$IBHConfig.RepositoryTask.Token = Use-VaultSecureString -TargetName 'GitHub Token'
$IBHConfig.GalleryTask.Token = Use-VaultSecureString -TargetName 'PowerShell Gallery Key'
```
### Build Tasks
* **Default (.)**
The default task will verify, build and test the module. This task is intended to be used during the development of the target module.
* **Release**
Release the module to the repository and the gallery. This task is used to publish a new module version.
* **Verify**
Verify the build system itself, like the InvokeBuild and InvokeBuildHelper module version.
* **Build**
Build the C# solutions, if any exists. This includes clean, compile and deploy.
* **Test**
Test the module with pester and script analyzer. This includes schema tests, module unit tests and script analyzer rules.
* **Clean**
Task for C# solution clean.
* **Compile**
Task for C# solution compile.
* **Deploy**
Task for C# solution deploy.
* **UnitTest**
Run all pester unit tests for the PowerShell module.
* **IntegrationTest**
Run all pester integration tests for the PowerShell module.
* **SchemaTest**
Test the PowerShell module schema.
* **AnalyzerTest**
Invoke the script analyzer for the PowerShell module.
* **Approve**
Verify if the module is ready to be released.
* **Repository**
Release the module to the source code repository.
* **Gallery**
Release the module to the PowerShell Gallery.
* **Deploy**
Deploy a beta version as revision to the local module repository.
### Commands
* **Invoke-BuildIsolated**
Invoke a build by calling the Invoke-Build in an isolated process.
### Configuration
The following configuration is set by default or generated on the fly for the
build system. An demo value is shown in this example for generated properties.
Every configuration can be overwritten after importing the build script
`InvokeBuildHelperTasks` in the `.build.ps1` scripts.
```powershell
# Path to the module root folder (auto generated)
$IBHConfig.BuildRoot = 'C:\GitHub\InvokeBuildHelper'
# Name of the module to build (auto generated)
$IBHConfig.ModuleName = 'InvokeBuildHelper'
# Verify Task: Option to enable or disable the verification tests (default)
$IBHConfig.VerifyTask.Enabled = $true
# Verify Task: Minimum version of the InvokeBuild module (default)
$IBHConfig.VerifyTask.InvokeBuildVersion = '5.5.5'
# Verify Task: Url to the PowerShell Gallery to get the latest InvokeBuildHelper version (default)
$IBHConfig.VerifyTask.ModulePackageUrl = "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='InvokeBuildHelper'"
# Schema Task: List of text file extension (default)
$IBHConfig.SchemaTask.TextFileExtension = '.gitignore', '.gitattributes', '.ps1', '.psm1', '.psd1', '.ps1xml', '.txt', '.xml', '.cmd', '.json', '.md'
# Schema Task: Exclude files from the schema test by using wildcard filters (default)
$IBHConfig.SchemaTask.ExcludePath = @()
# Analyze Task: Rules to process by the PowerShell Script Analyzer (default)
$IBHConfig.AnalyzerTestTask.ScriptAnalyzerRules = Get-ScriptAnalyzerRule
# Analyze Task: Exclude files from the test by using wildcard filters (default)
$IBHConfig.AnalyzerTestTask.ExcludePath = @()
# Approve Task: Option to enable or disable the release approval tests (default)
$IBHConfig.ApproveTask.Enabled = $true
# Approve Task: Target branch for the release (default)
$IBHConfig.ApproveTask.BranchName = 'master'
# Repository Task: Option to enable or disable the release to the repository (default)
$IBHConfig.RepositoryTask.Enabled = $true
# Repository Task: By default, the repository is a GitHub repo (default)
$IBHConfig.RepositoryTask.Type = 'GitHub'
# Repository Task: The name of the user (auto generated)
$IBHConfig.RepositoryTask.User = 'claudiospizzi'
# Repository Task: The name of the repository (auto generated)
$IBHConfig.RepositoryTask.Name = 'InvokeBuildHelper'
# Repository Task: The secret token to access the GitHub api (default)
$IBHConfig.RepositoryTask.Token = Use-VaultSecureString -TargetName 'Repository Token'
# Repository Task: The secret token callback to access the GitHub api (default)
$IBHConfig.RepositoryTask.TokenCallback = { Get-VaultSecureString -TargetName 'Repository Token' }
# Gallery Task: Option to enable or disable the release to the gallery (default)
$IBHConfig.GalleryTask.Enabled = $true
# Gallery Task: Name of the PowerShell Gallery user, assume it's the same as GitHub (auto generated)
$IBHConfig.GalleryTask.User = 'claudiospizzi'
# Gallery Task: Name of the PowerShell Gallery repository (default)
$IBHConfig.GalleryTask.Name = 'PSGallery'
# Gallery Task: The secret token to access the PowerShell Gallery (default)
$IBHConfig.GalleryTask.Token = Use-VaultSecureString -TargetName 'Gallery Token'
# Gallery Task: The secret token callback to access the PowerShell Gallery (default)
$IBHConfig.GalleryTask.TokenCallback = { Get-VaultSecureString -TargetName 'Gallery Token' }
# Deploy Task: The module path where the beta revision is deployed (auto generated)
$IBHConfig.DeployTask.ModulePaths = @('C:\Users\ClaudioSpizzi\Documents\WindowsPowerShell\Modules')
```
### C# Libraries
The InvokeBuildHelper module supports building C# .NET class library. It's
recommended to use the target framework .NET Standard 2.1. Normally, only one
class library is used with the `.Library` suffix. The following example shows
how to create a new class library project:
```cmd
dotnet new classlib -f netstandard2.1 -o InvokeBuildHelper.Library
```
## Versions
Please find all versions in the [GitHub Releases] section and the release notes
in the [CHANGELOG.md] file.
## Installation
Use the following command to install the module from the [PowerShell Gallery],
if the PackageManagement and PowerShellGet modules are available:
```powershell
# Download and install the module
Install-Module -Name 'InvokeBuildHelper'
```
Alternatively, download the latest release from GitHub and install the module
manually on your local system:
1. Download the latest release from GitHub as a ZIP file: [GitHub Releases]
2. Extract the module and install it: [Installing a PowerShell Module]
## Requirements
The following minimum requirements are necessary to use this module, or in other
words are used to test this module:
* Windows PowerShell 5.1
* Windows 10 (for the File Explorer Namespace functions)
## Contribute
Please feel free to contribute by opening new issues or providing pull requests.
For the best development experience, open this project as a folder in Visual
Studio Code and ensure that the PowerShell extension is installed.
* [Visual Studio Code] with the [PowerShell Extension]
* [Pester], [PSScriptAnalyzer], [InvokeBuild] and [InvokeBuildHelper] modules
[PowerShell Gallery]: https://www.powershellgallery.com/packages/InvokeBuildHelper
[GitHub Releases]: https://github.com/claudiospizzi/PSInvokeBuildHelper/releases
[Installing a PowerShell Module]: https://msdn.microsoft.com/en-us/library/dd878350
[CHANGELOG.md]: CHANGELOG.md
[Visual Studio Code]: https://code.visualstudio.com/
[PowerShell Extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell
[Pester]: https://www.powershellgallery.com/packages/Pester
[PSScriptAnalyzer]: https://www.powershellgallery.com/packages/PSScriptAnalyzer
[InvokeBuild]: https://www.powershellgallery.com/packages/InvokeBuild
[InvokeBuildHelper]: https://www.powershellgallery.com/packages/InvokeBuildHelper