Build scripts

PowerShell Build Scripts

PowerShell is used to provide all of the build scripting and automation. This keeps the GH Action YAML files as limited as possible and focuses the overall flow/logic of a build in an easy-to-follow imperative language.

Modules

The build makes use of a common folder structure and patterns for the Ubiquity.NET family of repositories. This involves use of several PowerShell modules and common usage pattern script commands.

CommonBuild

The CommonBuild PowerShell Module is intended to contain all of the repository neutral common re-usable scripting in support of the Ubiquity.NET family of projects.

RepoBuild

This module contains repo-specific support used by the command scripts

Command Scripts

Common command scripts (and parameters) are used to simplify moving between repositories in the Ubiquity.NET family of projects.

Building the Source

The build uses a common PowerShell module pattern for Ubiquity.NET projects. To build the sources use the Build-All.ps1 script. You can also open the src/Ubiquity.NET.Versioning.slnx in any editor/IDE that has support for the slnx solution format. (Visual Studio 2022 is used but other options may work, though they are not supported. If you have experience with other IDEs, then PRs are welcome for additional support - but such PRs MUST NOT break the VS support, and you must be willing to maintain such support going forward.)

Important

It is important to note that IDE builds of a clean repo get will FAIL! This is due to the mechanisms used to eliminate circular dependencies while still supporting automated versioning of the projects themselves. To resolve this, you must run the .\New-GeneratedVersionProps.ps1 at least once to create the imported generatedversion.props file. This is also generated by the Build-All.ps1 script, which is the recommended means of generating the required file. This is only needed the first time (or any time the buildversion.xml changes)

Building the Docs

The documentation is generated from ad-hoc articles, and the XML doc comments in the source code. via a DocFX tool. To build them you can use the .\Build-Docs.ps script. This script has an additional optional switch -ShowDocs that can host the documentation and launch the default browser to allow viewing the generated documents. This functionality is provided by an additional script called .\Show-Docs.s1 this by default will show the locally built documentation. However, if given a path it can use that as the root of the docs to show. This allows for downloading or sharing of the docs that were not build locally for review.