substrate

Warning

During pre-1.0 development (0.x), this project will regularly introduce breaking changes without a major version bump. Public APIs, file layouts, and command-line interfaces may change between releases. Pin a release for reproducible builds and review its release notes before updating. Stable compatibility guarantees will begin with version 1.0.0.

substrate is an open-source MIT-licensed library of reusable C# APIs, maintained by the Ad Noctem Collective, for Windows administration, configuration management, and automation. Applications can use the domain libraries without loading PowerShell.

The PowerShell adapter, AdNoctem.Substrate.PowerShell, supports Windows PowerShell 5.1 and PowerShell 7 on x64 Windows. The module and all twelve domain libraries are published and available to use as 0.x releases. Their APIs are still evolving; stable compatibility guarantees begin at 1.0.0. The predecessor, PSFoundation 1.8.7, remains available for existing scripts. Document generation is a PowerShell 7 (Core) capability: the Documents domain and its Open XML dependency are staged only in that edition. Windows PowerShell 5.1 keeps the existing command surface but cannot load the document-generation types.

PSGallery distributes the complete module as AdNoctem.Substrate.PowerShell. NuGet distributes twelve separate domain packages: AdNoctem.Substrate.Core, .Diagnostics, .Documents, .IO, .Interop, .Networking, .Office, .Packages, .Policies, .Registry, .Security, and .Windows (each with the AdNoctem.Substrate prefix). There is no umbrella AdNoctem.Substrate package; reference the domains you use. All packages share the same release version.

The implementation consists of reusable C# domain libraries and a PowerShell adapter. The adapter retains the original 188 commands and four aliases and adds new commands as the libraries evolve, using compiled cmdlets and a small compatibility script. Comparison tests retrieve the frozen PSFoundation v1 scripts from Git history.

See the documentation sources, architecture, migration history, and contributor guide. Build the searchable .NET and PowerShell reference with the Docs target; open build/docs/site/index.html.

Installation

Install the published PowerShell module from PSGallery. Pin a reviewed release for reproducible automation; this example uses 0.2.1:

Install-Module -Name AdNoctem.Substrate.PowerShell -RequiredVersion 0.2.1 -Repository PSGallery -Scope CurrentUser
Import-Module AdNoctem.Substrate.PowerShell -RequiredVersion 0.2.1

For .NET applications, reference the domain packages you need from NuGet; see Using the .NET libraries. Review the release notes before changing a pinned version. Published packages do not require building this repository.

Development

# Restore pinned tools and dependencies.
dotnet msbuild tools/tasks.proj -t:Restore

# Format, validate, test both PowerShell hosts, document, and package.
dotnet msbuild tools/tasks.proj -t:Format
dotnet msbuild tools/tasks.proj -t:Verify

# Import the staged package in a fresh PowerShell process.
Import-Module ./build/module/AdNoctem.Substrate.PowerShell/AdNoctem.Substrate.PowerShell.psd1

# Check the same hooks used in CI.
pre-commit run --all-files

The SDK is selected by global.json. Developer tasks use PowerShell 7 and Bun; packaged commands support Windows PowerShell 5.1 and PowerShell 7 on x64 Windows. Build output stays under build/, archives under dist/. Publishing remains separately gated.

Contributing

Contributions are welcome via GitHub's Pull Requests. Fork the repository and implement your changes within the forked repository, after that you may submit a Pull Request. Refer to our documentation for contributors for contributing guidelines, commit message formats and versioning tips.

Maintainers

This project is owned and maintained by Ad Noctem Collective refer to the AUTHORS or CODEOWNERS for more information. You may also use the linked contact details to reach out directly.

Copyright

Assets provided by: Microsoft Corporation