{"id":18148477,"url":"https://github.com/gaelcolas/sampler","last_synced_at":"2026-01-30T17:03:35.401Z","repository":{"id":35685152,"uuid":"194898818","full_name":"gaelcolas/Sampler","owner":"gaelcolas","description":"Module template with build pipeline and examples, including DSC elements.","archived":false,"fork":false,"pushed_at":"2025-09-06T16:13:29.000Z","size":28242,"stargazers_count":204,"open_issues_count":68,"forks_count":46,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-09-06T18:16:55.938Z","etag":null,"topics":["automation","continuous-delivery","powershell"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gaelcolas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-07-02T16:28:05.000Z","updated_at":"2025-09-06T16:04:29.000Z","dependencies_parsed_at":"2023-09-24T22:19:14.152Z","dependency_job_id":"602f2d2f-94b3-4004-9655-7f0ec185a779","html_url":"https://github.com/gaelcolas/Sampler","commit_stats":{"total_commits":597,"total_committers":22,"mean_commits":"27.136363636363637","dds":0.6180904522613065,"last_synced_commit":"b2fc9fb6841108304ca16b80c57f6f51535defc8"},"previous_names":[],"tags_count":292,"template":false,"template_full_name":null,"purl":"pkg:github/gaelcolas/Sampler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelcolas%2FSampler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelcolas%2FSampler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelcolas%2FSampler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelcolas%2FSampler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gaelcolas","download_url":"https://codeload.github.com/gaelcolas/Sampler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelcolas%2FSampler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28915942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T16:37:38.804Z","status":"ssl_error","status_checked_at":"2026-01-30T16:37:37.878Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","continuous-delivery","powershell"],"created_at":"2024-11-01T23:08:56.562Z","updated_at":"2026-01-30T17:03:35.379Z","avatar_url":"https://github.com/gaelcolas.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sampler Module [![Azure DevOps builds](https://img.shields.io/azure-devops/build/Synedgy/524b41a5-5330-4967-b2de-bed8fd44da08/1)](https://synedgy.visualstudio.com/Sampler/_build?definitionId=1\u0026_a=summary)\r\n\r\n[![PowerShell Gallery (with prereleases)](https://img.shields.io/powershellgallery/vpre/Sampler?label=Sampler%20Preview)](https://www.powershellgallery.com/packages/Sampler/)\r\n[![PowerShell Gallery](https://img.shields.io/powershellgallery/v/Sampler?label=Sampler)](https://www.powershellgallery.com/packages/Sampler/)\r\n[![Azure DevOps tests](https://img.shields.io/azure-devops/tests/SynEdgy/Sampler/1)](https://synedgy.visualstudio.com/Sampler/_test/analytics?definitionId=1\u0026contextType=build)\r\n![Azure DevOps coverage](https://img.shields.io/azure-devops/coverage/Synedgy/Sampler/1)\r\n![PowerShell Gallery](https://img.shields.io/powershellgallery/p/Sampler)\r\n\r\nThis project is used to scaffold a PowerShell module project, complete with\r\nPowerShell build and deploy pipeline automation.\r\n\r\nThe Sampler module in itself serves several purposes:\r\n\r\n- Quickly scaffold a PowerShell module project that can build and enforce some good practices.\r\n- Provide a minimum set of [InvokeBuild](https://github.com/nightroman/Invoke-Build)\r\ntasks that help you build, test, pack and publish your module.\r\n- Help building your module by adding elaborate sample elements like classes,\r\n  MOF-based DSC resources, class-based DSC resources, helper modules, embedded helper\r\n  modules, and more.\r\n- Avoid the \"it works on my machine\" and remove the dependence on specific tools\r\n  (such as a CI tool).\r\n- Ensures the build process can be run anywhere the same way (whether behind a\r\n  firewall, on a developers workstation, or in a build agent).\r\n- Assume nothing is set up, and you don't have local administrator rights.\r\n- Works on Windows, Linux and MacOS.\r\n\r\nCheck the video for a quick intro:\r\n\r\n\u003e _Note: The video was made when Sampler was in early stages. Since that time_\r\n\u003e _there have been a lot of improvements and changes, so please read the_\r\n\u003e _documentation below._\r\n\r\n[![Sampler demo video](https://img.youtube.com/vi/bbpFBsl8K9k/0.jpg)](https://www.youtube.com/watch?v=bbpFBsl8K9k\u0026ab_channel=DSCCommunity)\r\n\r\n## Prerequisites\r\n\r\n### Resolving dependencies\r\n\r\nThe Sampler templates is configured to use PSResourceGet as the method of\r\nresolving dependencies. The property `UsePSResourceGet` is default configured\r\nto `$true` in the file Resolve-Dependency.psd1. If that configuration is\r\nremoved or disabled (set to `$false`) then resolving dependencies will\r\nrevert to PowerShellGet \u0026 PSDepend.\r\n\r\nThe specification syntax of the file RequiredModules.psd1 works with all\r\nthree methods of resolving dependencies.\r\n\r\n```powershell\r\n@{\r\n   # Gives latest release\r\n   Pester = 'latest'\r\n\r\n   # Gives specific release (also known as pinning version)\r\n   Pester = '4.10.1'\r\n\r\n   # Gives latest preview release\r\n   'ComputerManagementDsc' = @{\r\n      Version    = 'latest'\r\n      Parameters = @{\r\n         AllowPrerelease = $true\r\n      }\r\n   }\r\n\r\n   # Gives specific preview release (also known as pinning version)\r\n   'ComputerManagementDsc' = @{\r\n      Version    = '9.1.0-preview0002'\r\n      Parameters = @{\r\n         AllowPrerelease = $true\r\n      }\r\n   }\r\n}\r\n```\r\n\r\nWhen using the method _PowerShellGet \u0026 PSDepend_ this configuration should\r\nalso be added to the file RequiredModules.psd1 to control the behavior\r\nof PSDepend. This is only required if you need to use _PowerShellGet \u0026 PSDepend_.\r\nIt is not required for PSResourceGet or ModuleFast.\r\n\r\n```powershell\r\n@{\r\n   PSDependOptions = @{\r\n      AddToPath  = $true\r\n      Target     = 'output\\RequiredModules'\r\n      Parameters = @{\r\n         Repository = 'PSGallery'\r\n      }\r\n   }\r\n```\r\n\r\n#### PSResourceGet\r\n\r\nIt is possible to use [PSResourceGet](https://github.com/PowerShell/PSResourceGet)\r\nto resolve dependencies. PSResourceGet works with Windows PowerShell and\r\nPowerShell (some restrictions on versions exist). To use PSResourceGet as\r\na replacement for PowerShellGet it is possible to enable it in the configuration\r\nfile `Resolve-Dependency.psd1`. It is also possible to allow the repository\r\nto use PowerShellGet as the default and choose to use PSResourceGet from the\r\ncommand line by passing the parameter `UsePSResourceGet` to the build script\r\n`build.ps1`, e.g. `.\\build.ps1 -ResolveDependency -Tasks noop -UsePSResourceGet`\r\n\r\nIf both PSResourceGet and ModuleFast is enabled then PSResource will be\r\npreferred on Windows PowerShell and PowerShell 7.1 or lower. ModuleFast\r\nwill be preferred on PowerShell 7.2 or higher.\r\n\r\n#### ModuleFast\r\n\r\nIt is possible to use [ModuleFast](https://github.com/JustinGrote/ModuleFast)\r\nto resolve dependencies. ModuleFast only works with PowerShell 7.2 or higher.\r\nTo use ModuleFast as a replacement for PowerShellGet it is possible to\r\nenable it in the configuration file `Resolve-Dependency.psd1`.\r\nIt is also possible to allow the repository to use PowerShellGet as the\r\ndefault and choose to use ModuleFast from the command line by passing\r\nthe parameter `UseModuleFast` to the build script `build.ps1`, e.g.\r\n`.\\build.ps1 -ResolveDependency -Tasks noop -UseModuleFast`.\r\n\r\nIf both PSResourceGet and ModuleFast is enabled then ModuleFast will be\r\npreferred on PowerShell 7.2 or higher. PSResource will be preferred\r\non Windows PowerShell and PowerShell 7.1 or lower.\r\n\r\nWhen using ModuleFast as the only method there is more options to specify\r\nmodules in the file RequiredModules.psd1. This syntax will limit resolving\r\ndependencies to just ModuleFast (and PowerShell 7.2 or higher) as they are\r\nnot supported by the other methods. See the comment-based help of the command\r\n[`Install-ModuleFast`](https://github.com/JustinGrote/ModuleFast/blob/main/ModuleFast.psm1)\r\nfor more information of the available syntax.\r\n\r\n```powershell\r\n@{\r\n   # Gives the latest release\r\n   'ComputerManagementDsc' =  'latest'\r\n\r\n   # Gives the specific release\r\n   'ComputerManagementDsc' =  '9.0.0'\r\n   \r\n   # Gives the latest patch release for v9.0\r\n   'ComputerManagementDsc' =  ':9.0.*'\r\n\r\n   # Gives the latest preview release\r\n   'ComputerManagementDsc' =  '!'\r\n\r\n   # Gives the latest release (including previews) that is higher that v9.0.0\r\n   'ComputerManagementDsc' =  '!\u003e9.0.0'\r\n\r\n   # Must be exactly 9.1.0-preview0002\r\n   'ComputerManagementDsc' =  '9.1.0-preview0002'\r\n   'ComputerManagementDsc' =  '@9.1.0-preview0002'\r\n   'ComputerManagementDsc' =  ':9.1.0-preview0002'\r\n   'ComputerManagementDsc' =  ':[9.1.0-preview0002]'\r\n\r\n   # Must be a higher version than 9.1.0-preview0002\r\n   'ComputerManagementDsc' =  '\u003e9.1.0-preview0002'\r\n\r\n   # Must be a lower version than 9.1.0-preview0002\r\n   'ComputerManagementDsc' =  '\u003c9.1.0-preview0002'\r\n\r\n   # Must be a lower version than or equal to 9.1.0-preview0002\r\n   'ComputerManagementDsc' =  '\u003c=9.1.0-preview0002'\r\n\r\n   # Must be a higher version than or equal to 9.1.0-preview0002\r\n   'ComputerManagementDsc' =  '\u003e=9.1.0-preview0002'\r\n\r\n   # Exact range, exclusive. Must be lower version than 9.2.0. 9.2.0 is not allowed.\r\n   'ComputerManagementDsc' =  ':(,9.2.0)'\r\n\r\n   # Exact range, exclusive. Must be higher version than 9.0.0. 9.0.0 is not allowed.\r\n   'ComputerManagementDsc' =  ':(9.0.0,)'\r\n\r\n   # Exact range, inclusive. Must be version than 9.0.0 or higher up to or equal to 9.2.0.\r\n   'ComputerManagementDsc' =  ':[9.0.0,9.2.0]'\r\n}\r\n\r\n```\r\n\r\n#### PowerShellGet \u0026 PSDepend\r\n\r\nBecause we resolve dependencies from a nuget feed, whether the public\r\nPowerShell Gallery or your private repository, a working version of PowerShellGet\r\nis required. Using PowerShellGet is the default if no other configuration\r\nis done. We recommend the latest version of PowerShellGet v2.\r\n\r\n### Managing the Module versions (optional)\r\n\r\nManaging the versions of your module is tedious, and is hard to maintain\r\nconsistency over time. The usual tricks like checking what the latest version on\r\nPowerShell Gallery is, or use the `BuildNumber` to increment a `0.0.x` version\r\nworks but isn't ideal, especially if we want to stick to [semver](https://semver.org/).\r\n\r\nWhile you can manage the version by updating the module manifest manually or by\r\nletting your CI tool update the `ModuleVersion` environment variable, we think\r\nthe best method is to rely on the cross-platform tool [`GitVersion`](https://gitversion.net/docs/).\r\n\r\n[`GitVersion`](https://gitversion.net/docs/) will generate the version based on\r\nthe git history. You control what version to deploy using [git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging).\r\n\r\nGenerally, GitVersion will look at the latest version tag, the branch names, commit\r\nmessages, to try to determine the Major/Minor/Patch (semantic versioning) based\r\non detected change (configurable in the file [`GitVersion.yml`](https://gitversion.net/docs/reference/configuration)\r\nthat is part of your project).\r\n\r\nTherefore, it is recommended that you install `GitVersion` on your development environment\r\nand on your CI environment build agents.\r\n\r\nThere are various ways to [install GitVersion](https://gitversion.net/docs/usage/cli/installation)\r\non your development environment. If you use Chocolatey (install and upgrade):\r\n\r\n```PowerShell\r\nC:\\\u003e choco upgrade gitversion.portable\r\n```\r\n\r\nIf you use HomeBrew (install and upgrade):\r\n```PowerShell\r\nPS \u003e brew upgrade gitversion\r\n```\r\n\r\n\r\nThis describes how to [install GitVersion in your CI environment build agents](https://gitversion.net/docs/usage/ci)\r\nif you plan to use the deploy pipelines in the CI.\r\n\r\n## Usage\r\n\r\n### How to create a new project\r\n\r\nTo create a new project the command `New-SampleModule` should be used. Depending\r\non the template used with the command the content in project will contain\r\ndifferent sample content while some also adds additional pipeline jobs. But all\r\ntemplates (except one) will have the basic tasks to have a working pipeline including\r\nbuild, test and deploy stages.\r\n\r\nThe sections below show how to use each template. The templates are:\r\n\r\n- `SimpleModule` - Creates a module with minimal structure and pipeline automation.\r\n- `SimpleModule_NoBuild` - Creates a simple module without the build automation.\r\n- `CompleteSample` - Creates a module with complete structure and example files.\r\n- `dsccommunity` - Creates a DSC module according to the DSC Community baseline\r\n   with a pipeline for build, test, and release automation.\r\n- `CustomModule` - Will prompt you for more details as to what you'd like to scaffold.\r\n- `GCPackage` - Creates a module that can be deployed to be used with _Azure Policy_\r\n  _Guest Configuration_.\r\n\r\nAs per the video above, you can create a new module project with all files and\r\npipeline scripts. Once the project is created, the `build.ps1` inside the new\r\nproject folder is how you interact with the built-in pipeline automation, and\r\nthe file `build.yaml` is where you configure and customize it.\r\n\r\n#### `SimpleModule`\r\n\r\nCreates a module with minimal structure and pipeline automation.\r\n\u003e[!NOTE]\r\n\u003eChange the `DestinationPath` to the location where the module should be created depending on you platform and workflow.\r\n\r\n```powershell\r\nInstall-Module -Name 'Sampler' -Scope 'CurrentUser'\r\n\r\n$newSampleModuleParameters = @{\r\n    DestinationPath   = 'C:\\source'\r\n    ModuleType        = 'SimpleModule'\r\n    ModuleName        = 'MySimpleModule'\r\n    ModuleAuthor      = 'My Name'\r\n    ModuleDescription = 'MySimpleModule Description'\r\n}\r\n\r\nNew-SampleModule @newSampleModuleParameters\r\n```\r\n\r\n#### `SimpleModule_NoBuild`\r\n\r\nCreates a simple module without the build automation.\r\n\r\n```powershell\r\nInstall-Module -Name 'Sampler' -Scope 'CurrentUser'\r\n\r\n$newSampleModuleParameters = @{\r\n    DestinationPath   = 'C:\\source'\r\n    ModuleType        = 'SimpleModule_NoBuild'\r\n    ModuleName        = 'MySimpleModuleNoBuild'\r\n    ModuleAuthor      = 'My Name'\r\n    ModuleDescription = 'MySimpleModuleNoBuild Description'\r\n}\r\n\r\nNew-SampleModule @newSampleModuleParameters\r\n```\r\n\r\n#### `CompleteSample`\r\n\r\nCreates a module with complete structure and example files.\r\n\r\n```powershell\r\nInstall-Module -Name 'Sampler' -Scope 'CurrentUser'\r\n\r\n$newSampleModuleParameters = @{\r\n    DestinationPath   = 'C:\\source'\r\n    ModuleType        = 'CompleteSample'\r\n    ModuleName        = 'MyCompleteSample'\r\n    ModuleAuthor      = 'My Name'\r\n    ModuleDescription = 'MyCompleteSample Description'\r\n}\r\n\r\nNew-SampleModule @newSampleModuleParameters\r\n```\r\n\r\n#### `dsccommunity`\r\n\r\nCreates a DSC module according to the DSC Community baseline with a pipeline\r\nfor build, test, and release automation.\r\n\r\n```powershell\r\nInstall-Module -Name 'Sampler' -Scope 'CurrentUser'\r\n\r\n$newSampleModuleParameters = @{\r\n    DestinationPath   = 'C:\\source'\r\n    ModuleType        = 'dsccommunity'\r\n    ModuleName        = 'MyDscModule'\r\n    ModuleAuthor      = 'My Name'\r\n    ModuleDescription = 'MyDscModule Description'\r\n}\r\n\r\nNew-SampleModule @newSampleModuleParameters\r\n```\r\n\r\n#### `CustomModule`\r\n\r\nWill prompt you for more details as to what you'd like to scaffold.\r\n\r\n```powershell\r\nInstall-Module -Name 'Sampler' -Scope 'CurrentUser'\r\n\r\n$samplerModule = Import-Module -Name Sampler -PassThru\r\n\r\n$invokePlasterParameters = @{\r\n   TemplatePath    = Join-Path -Path $samplerModule.ModuleBase -ChildPath 'Templates/Sampler'\r\n   DestinationPath   = 'C:\\source'\r\n   ModuleType        = 'CustomModule'\r\n   ModuleName        = 'MyCustomModule'\r\n   ModuleAuthor      = 'My Name'\r\n   ModuleDescription = 'MyCustomModule Description'\r\n}\r\n\r\nInvoke-Plaster @invokePlasterParameters\r\n```\r\n\r\n#### `GCPackage`\r\n\r\n\u003e**Note:** The `GCPackage` template is not yet available, but can be created using\r\n\u003ethe `dsccommunity` template with modifications, see the section [GCPackage scaffolding](#gcpackage-scaffolding).\r\n\r\n### How to work with the multi-module repository\r\n\r\nTypically, such as with a community-driven module, you would have a single\r\ngit repository dedicated to each module. However, there are situations where\r\nyou might opt for a single git repository to encompass multiple modules. If\r\nyou intend to establish a multi-module repository, ensure that each module\r\nis housed within its own folder. Each module's folder structure should be\r\ndistinct and should not overlap with the folder structure of other modules.\r\n\r\n\u003e [!TIP]\r\n\u003e Right folder structure\r\n\r\n```bash\r\nGitRootFolder\r\n├───Module1\r\n├───Module2\r\n├───SomeModuleGroup #Not a module\r\n│   ├───GroupModule1\r\n│   └───GroupModule2\r\n└───Module3\r\n```\r\n\r\n\u003e [!CAUTION]\r\n\u003e Wrong folder structure\r\n\r\n```bash\r\nGitRootFolder\r\n├───Module1\r\n├───Module2\r\n├───Module3\r\n│   ├───SubModule1\r\n│   └───SubModule2\r\n└───Module3\r\n```\r\n\r\n\u003e[!NOTE]\r\n\u003eYou can utilize the gitversion tag-prefix to differentiate tags for each module\r\n\u003eseparately. [gitVersion configuration](https://gitversion.net/docs/reference/configuration)\r\n\r\n### How to download dependencies for the project\r\n\r\nTo be able to build the project, all the dependencies listed in the file\r\n`RequiredModules.psd1` must first be available. This is the beginning of\r\nthe build process so that anyone doing a git clone can 're-hydrate' the\r\nproject and start testing and producing the build artefact locally with\r\nminimal environmental dependencies.\r\n\r\n\u003e[!NOTE]\r\n\u003eTry to avoid mixing these different methods in the same session. When\r\n\u003eswitching to use a different method, open a new PowerShell session so\r\n\u003enone of the modules dependencies are loaded into the session.\r\n\r\n```mermaid\r\ngraph LR\r\n\r\nRD[Resolve dependencies] --\u003e Method{Method?}\r\nMethod{Method?} --\u003e|\"(Legacy, to use,\r\ndisable other\r\nmethods)\"| PowerShellGet([\"PowerShellGet\"])\r\nMethod --\u003e|\"parameter\r\n-UseModuleFast\"| ModuleFast([\"ModuleFast\"])\r\nMethod --\u003e|\"(Default),\r\nparameter\r\n-UsePSResourceGet\"| PSResourceGet([\"PSResourceGet\"])\r\nPowerShellGet --\u003e|\"Invoke-PSDepend\"| InvokeRD\r\nModuleFast --\u003e|\"Install-ModuleFast\"| InvokeRD\r\nPSResourceGet --\u003e|\"Save-PSResource\"| InvokeRD\r\nInvokeRD[Use preferred method]  \u003c--\u003e PSGallery[\"PowerShell Gallery\"]\r\nInvokeRD ---\u003e Save[[\"Save to RequiredModules\"]]\r\n```\r\n\r\nThe following command will resolve dependencies using PSResourceGet:\r\n\r\n```powershell\r\ncd C:\\source\\MySimpleModule\r\n\r\n./build.ps1 -ResolveDependency -Tasks noop\r\n```\r\n\r\nThe following command will resolve dependencies using [ModuleFast](https://github.com/JustinGrote/ModuleFast):\r\n\r\n```powershell\r\ncd C:\\source\\MySimpleModule\r\n\r\n./build.ps1 -ResolveDependency -Tasks noop -UseModuleFast\r\n```\r\n\r\nThe following command will resolve dependencies using [PSResourceGet](https://github.com/PowerShell/PSResourceGet):\r\n\r\n```powershell\r\ncd C:\\source\\MySimpleModule\r\n\r\n./build.ps1 -ResolveDependency -Tasks noop -UsePSResourceGet\r\n```\r\n\r\nThe dependencies will be downloaded (or updated) from the PowerShell Gallery (unless\r\nanother repository is specified) and saved in the project folder under\r\n`./output/RequiredModules`.\r\n\r\n\u003e By default, each repository should not rely on your personal development\r\n\u003e environment, so that it's easier to repeat on any machine or build agent.\r\n\r\nNormally this command only needs to be run once, but the command can be run\r\nanytime to update to a newer version of a required module (if one is available),\r\nor if the required modules have changed in the file `RequiredModules.psd1`.\r\n\r\n\u003e **Note:** If a required module is removed in the file `RequiredModules.psd1`\r\n\u003e that module will not be automatically removed from the folder\r\n\u003e `./output/RequiredModules`.\r\n\r\n### How to build the project\r\n\r\nThe following command will build the project:\r\n\r\n```powershell\r\ncd C:\\source\\MySimpleModule\r\n\r\n./build.ps1 -Tasks build\r\n```\r\n\r\nIt is also possible to resolve dependencies and build the project\r\nat the same time using the command:\r\n\r\n```powershell\r\n./build.ps1 -ResolveDependency -Tasks build\r\n```\r\n\r\nIf there are any errors during build they will be shown in the output and the\r\nbuild will stop. If it is successful the output should end with:\r\n\r\n```plaintext\r\nBuild succeeded. 7 tasks, 0 errors, 0 warnings 00:00:06.1049394\r\n```\r\n\r\n\u003e **NOTE:** The number of tasks can differ depending on which template that\r\n\u003e was used to create the project.\r\n\r\n### How to set up the build environment in the current PowerShell session\r\n\r\nIf you only want to make sure the environment is configured, or you only want\r\nto resolve the dependencies, you can call the built-in task `noop` (\"no operation\")\r\nwhich won't do anything other than a quick way to run the bootstrap script (there\r\nis no code that executes in the `noop` task).\r\n\r\n```powershell\r\n./build.ps1 -Tasks noop\r\n```\r\n\r\n\u003e**Note:** For the built-in `noop` task to work, the dependencies must first\r\n\u003ehave been resolved.\r\n\r\n### How to run tests\r\n\r\n\u003c!-- markdownlint-disable MD028 - empty line in block quote --\u003e\r\n\u003e [!NOTE]\r\n\u003e Which tests are run is determined by the paths configured\r\n\u003e by a key in the _Pester_ configuration in the file `build.yml`. The key\r\n\u003e differs depending on the version of _Pester_ being used. The key is `Script`\r\n\u003e when using _Pester v4_, and `Path` when using _Pester v5_.\r\n\r\n\u003e [!IMPORTANT]\r\n\u003eIf running (or debugging) tests in Visual Studio Code you should first make sure\r\n\u003ethe session environment is set correctly. This is normally done when you build\r\n\u003ethe project. But if there is no need to rebuild the project it is faster to run\r\n\u003ethe [built-in task `noop`](#how-to-set-up-the-build-environment-in-the-current-powershell-session)\r\n\u003ein the _PowerShell Integrated Console_.\r\n\u003c!-- markdownlint-enable MD028 - empty line in block quote --\u003e\r\n\r\nRunning all the unit tests, the quality tests and show code coverage can\r\nbe achieved by running the command:\r\n\r\n```powershell\r\n`./build.ps1 -Tasks test`\r\n```\r\n\r\nIntegration tests are not run by default when using the build task `test`.\r\nTo run the integration test use the following command:\r\n\r\n```powershell\r\n`./build.ps1 -Tasks test -PesterPath 'tests/Integration' -CodeCoverageThreshold 0`\r\n```\r\n\r\nTo run all tests in a specific folder use the parameter `PesterPath` and\r\noptionally `CodeCoverageThreshold` set to `0` to turn off code coverage.\r\nThis runs all the quality tests:\r\n\r\n```powershell\r\n`./build.ps1 -Tasks test -PesterPath 'tests/QA' -CodeCoverageThreshold 0`\r\n```\r\n\r\nTo run a specific test file, again use the parameter `PesterPath` and\r\noptionally `CodeCoverageThreshold` set to `0` to turn off code coverage.\r\nThis runs just the specific test file `New-SamplerXmlJaCoCoCounter.tests.ps1`:\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\n./build.ps1 -Tasks test -PesterPath ./tests/Unit/Private/New-SamplerXmlJaCoCoCounter.tests.ps1 -CodeCoverageThreshold 0\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n### How to run the default workflow\r\n\r\nIt is possible to do all of the above (resolve dependencies, build, and run tests)\r\nin just one line by running the following:\r\n\r\n```powershell\r\n./build -ResolveDependency\r\n```\r\n\r\nThe parameter `Task` is not used which means this will run the default workflow\r\n(`.`). The tasks for the default workflow are configured in the file `build.yml`.\r\nNormally the default workflow builds the project and runs all the configured test.\r\n\r\nThis means by running this it will build and run all configured tests:\r\n\r\n```powershell\r\n./build.ps1\r\n```\r\n\r\n### How to list all available tasks\r\n\r\nBecause the build tasks are `InvokeBuild` tasks, we can discover them using\r\nthe `?` task. So to list the available tasks in a project, run the following\r\ncommand:\r\n\r\n```powershell\r\n./build.ps1 -Tasks ?\r\n```\r\n\r\n\u003e **NOTE:** If it is not already done, first make sure to resolve dependencies.\r\n\u003e Dependencies can also hold tasks that are used in the pipeline.\r\n\r\n## About the bootstrap process (`build.ps1`)\r\n\r\nThe `build.ps1` is the _entry point_ to invoke any task, or a list of build\r\ntasks (workflow), leveraging the [`Invoke-Build`](https://www.powershellgallery.com/packages/InvokeBuild)\r\ntask runner.\r\n\r\nThe script does not assume your environment has the required PowerShell modules,\r\nso the bootstrap is done by the project's script file `build.ps1`, and can\r\nresolve the dependencies listed in the project's file `RequiredModules.psd1`\r\nusing [`PSDepend`](https://www.powershellgallery.com/packages/PSDepend).\r\n\r\nInvoking `build.ps1` with the `-ResolveDependency` parameter will prepare your\r\nenvironment like so:\r\n\r\n1. Updates the session environment variable (`$env:PSModulePath`) to resolve\r\n   the built module (`.\\output`) and the modules in the folder `./output/RequiredModules`\r\n   by prepending those paths to `$env:PSModulePath`. By prepending the paths\r\n   to the session `$env:PSModulePath` the build process will make those\r\n   dependencies available in your session for module discovery and auto-loading,\r\n   and also make it possible to use one or more of those modules as part of your built\r\n   module.\r\n1. (Optional) Making sure you have a compatible version of the modules _PowerShellGet_ and\r\n   _PackageManagement_ (`version -gt 1.6`). If not, these will be installed from the\r\n   configured repository. Only required if you plan to use legacy PowerShellGet, default\r\n   PSResourceGet is used.\r\n1. Download or install the `PowerShell-yaml` and `PSDepend` modules needed\r\n   for further dependency management.\r\n1. Read the `build.yaml` configuration.\r\n1. If the Nuget package provider is not present, install and import Nuget PackageProvider\r\n   (proxy enabled).\r\n1. Invoke [PSDepend](https://www.powershellgallery.com/packages/PSDepend) on\r\n   the file `RequiredModules.psd1`. It will not install required modules to\r\n   your environment, it will save them to your project's folder `./output/RequiredModules`.\r\n1. Hand over the task execution to `Invoke-Build` to run the configured\r\n   workflow.\r\n\r\n## About Sampler build workflow\r\n\r\nLet's look at the pipeline of the `Sampler` module itself to better understand\r\nhow the pipeline automation is configured for a project created using a\r\ntemplate from the Sampler module.\r\n\r\n\u003e **NOTE:** Depending on the Sampler template used when creating a new project\r\n\u003e there can be additional configuration options - but they can all be added\r\n\u003e manually when those options are needed. The Sampler project itself does not use\r\n\u003e all features available (an example is DSC resources documentation generation).\r\n\r\n### Default Workflow Currently configured\r\n\r\nAs seen in the bootstrap process above, the different workflows can be configured\r\nby editing the `build.psd1`: new tasks can be loaded, and the sequence can be\r\nadded under the `BuildWorkflow` key by listing the names.\r\n\r\nIn our case, the [build.yaml](build.yaml) defines several workflows (`.`,\r\n`build`, `pack`, `hqrmtest`, `test`, and `publish`) that can be called by using:\r\n\r\n```PowerShell\r\n .\\build.ps1 -Tasks \u003cWorkflow_or_task_Name\u003e\r\n```\r\n\r\nThe detail of the **default workflow** is as follow (InvokeBuild defaults to\r\nthe workflow named '.' when no tasks is specified):\r\n\r\n```yml\r\nBuildWorkflow:\r\n  '.':\r\n    - build\r\n    - test\r\n```\r\n\r\nThe tasks `build` and `tests` are meta-tasks or workflow calling other tasks:\r\n\r\n```yml\r\n  build:\r\n    - Clean\r\n    - Build_Module_ModuleBuilder\r\n    - Build_NestedModules_ModuleBuilder\r\n    - Create_changelog_release_output\r\n  test:\r\n    - Pester_Tests_Stop_On_Fail\r\n    - Pester_if_Code_Coverage_Under_Threshold\r\n    - hqrmtest\r\n```\r\n\r\nThose tasks are imported from a module, in this case from\r\nthe `.build/` folder, from this `Sampler` module,\r\nbut for another module you would use this line in your `build.yml` config:\r\n\r\n```yaml\r\nModuleBuildTasks:\r\n  Sampler:\r\n    - '*.build.Sampler.ib.tasks' # this means: import (dot source) all aliases ending with .ib.tasks exported by 'Sampler' module\r\n```\r\n\r\nYou can edit your `build.yml` to change the workflow, add a custom task,\r\ncreate repository-specific task in a `.build/` folder named `*.build.ps1`.\r\n\r\n```yml\r\n  MyTask: {\r\n    # do something with some PowerShellCode\r\n    Write-Host \"Doing something in a task\"\r\n  }\r\n\r\n  build:\r\n    - Clean\r\n    - MyTask\r\n    - call_another_task\r\n```\r\n\r\n## GCPackage scaffolding\r\n\r\nCreates a module that can be deployed to be used with _Azure Policy_\r\n_Guest Configuration_. This process will be replaced with a Plaster template.\r\n\r\n1. Start by creating a new project using the template `dsccommunity`.\r\n\r\n   ```powershell\r\n   Install-Module -Name 'Sampler' -Scope 'CurrentUser'\r\n\r\n   $newSampleModuleParameters = @{\r\n      DestinationPath   = 'C:\\source'\r\n      ModuleType        = 'dsccommunity'\r\n      ModuleName        = 'MyGCPackages'\r\n      ModuleAuthor      = 'My Name'\r\n      ModuleDescription = 'MyGCPackages Description'\r\n   }\r\n\r\n   New-SampleModule @newSampleModuleParameters\r\n   ```\r\n\r\n1. In the file `build.yaml` add the following top-level key:\r\n\r\n   ```yaml\r\n   BuiltModuleSubdirectory: module\r\n   ```\r\n\r\n1. In the file `build.yaml` modify the `pack` key under the top-level key\r\n   `BuildWorkflow` by adding the task `gcpack`:\r\n\r\n   ```yaml  \r\n   pack:\r\n    - build\r\n    - package_module_nupkg\r\n    - gcpack\r\n   ```\r\n\r\n1. In the file `build.yaml` modify the `GitHubConfig` top-level key\r\n   as follows:\r\n\r\n   ```yaml  \r\n   GitHubConfig:\r\n     GitHubFilesToAdd:\r\n       - 'CHANGELOG.md'\r\n     ReleaseAssets:\r\n       - output/GCPolicyPackages/UserAmyNotPresent*.zip\r\n     GitHubConfigUserName: myGitHubUserName\r\n     GitHubConfigUserEmail: myEmail@address.com\r\n     UpdateChangelogOnPrerelease: false\r\n   ```\r\n\r\n1. In the file `RequiredModules.psd1` add the module _GuestConfiguration_\r\n   and `xPSDesiredStateConfiguration` to the list of dependency modules.\r\n\r\n   ```powershell\r\n   @{\r\n      # ... current dependencies\r\n\r\n      xPSDesiredStateConfiguration = 'latest'\r\n      GuestConfiguration = @{\r\n         Version = 'latest'\r\n         Parameters = @{\r\n               AllowPrerelease = $true\r\n         }\r\n      }\r\n   }\r\n   ```\r\n\r\n1. Modify the `azure-pipelines.yml` as follows:\r\n   1. Replace build image with `windows-latest`.\r\n   1. In the job `Package_Module` after the job `gitversion` and before the job\r\n      `package` add this new job:\r\n\r\n      ```yaml\r\n      - task: PowerShell@2\r\n        name: Exp_Feature\r\n        displayName: 'Enable Experimental features'\r\n        inputs:\r\n          pwsh: true\r\n          targetType: inline\r\n          continueOnError: true\r\n          script: |\r\n             ./build.ps1 -Tasks noop -ResolveDependency\r\n              Import-Module GuestConfiguration\r\n              Enable-ExperimentalFeature -Name GuestConfiguration.Pester\r\n              Enable-ExperimentalFeature -Name GuestConfiguration.SetScenario\r\n              Enable-ExperimentalFeature -Name PSDesiredStateConfiguration.InvokeDscResource -ErrorAction SilentlyContinue\r\n        env:\r\n          ModuleVersion: $(gitVersion.NuGetVersionV2)\r\n      ```\r\n\r\n   1. Remove the job `Test_HQRM`.\r\n   1. Remove the job `Test_Integration`.\r\n   1. Remove the job `Code_Coverage`.\r\n   1. Update deploy condition to use the Azure DevOps organization name:\r\n\r\n      ``` yaml\r\n      contains(variables['System.TeamFoundationCollectionUri'], 'myorganizationname')\r\n      ````\r\n\r\n   1. In the job `Deploy_Module` for both the deploy tasks `publishRelease`\r\n      and `sendChangelogPR` add the following environment variables:\r\n\r\n      ```yaml\r\n      ReleaseBranch: main\r\n      MainGitBranch: main\r\n      ```\r\n\r\n1. Create a new folder `GCPackages` under the folder `source`.\r\n1. Create a new folder `UserAmyNotPresent` under the new folder `GCPackages`.\r\n1. Under the folder `UserAmyNotPresent` create a new file `UserAmyNotPresent.config.ps1`.\r\n1. In the file `UserAmyNotPresent.config.ps1` add the following:\r\n\r\n   ```powershell\r\n   Configuration UserAmyNotPresent {\r\n      Import-DSCResource -ModuleName 'xPSDesiredStateConfiguration'\r\n\r\n      Node UserAmyNotPresent\r\n      {\r\n         xUser 'UserAmyNotPresent'\r\n         {\r\n               Ensure   = 'Absent'\r\n               UserName = 'amy'\r\n         }\r\n      }\r\n   }\r\n   ```\r\n\r\n1. Now resolve dependencies and run the task `gcpack`:\r\n\r\n   ```powershell\r\n   build.ps1 -task gcpack -ResolveDependency\r\n   ```\r\n\r\n1. The built _Guest Configuration_ package can be found in the folder\r\n   `output\\GCPolicyPackages\\UserAmyNotPresent`.\r\n\r\n## Commands\r\n\r\nRefer to the comment-based help for more information about these commands.\r\n\r\n### `Add-Sample`\r\n\r\nThis command is used to invoke a plaster template built-in the\r\nSampler module. With this function you can bootstrap your module project\r\nby adding classes, functions and associated tests, examples and configuration\r\nelements.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nAdd-Sample [[-Sample] \u003cString\u003e] [[-DestinationPath] \u003cString\u003e] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\nNone.\r\n\r\n#### Example\r\n\r\n```powershell\r\nAdd-Sample -Sample PublicFunction -PublicFunctionName Get-MyStuff\r\n```\r\n\r\nThis example adds a public function to the module (in the current folder),\r\nwith a sample unit test that test the public function.\r\n\r\n### `Invoke-SamplerGit`\r\n\r\nThis command executes git with the provided arguments and throws an error\r\nif the call failed.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nInvoke-SamplerGit [-Argument] \u003cstring[]\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n[System.String]\r\n\r\n#### Example\r\n\r\n```powershell\r\nInvoke-SamplerGit -Argument @('config', 'user.name', 'MyName')\r\n```\r\n\r\nCalls git to set user name in the git config.\r\n\r\n### `New-SampleModule`\r\n\r\nThis command helps you scaffold your PowerShell module project by creating\r\nthe folder structure of your module, and optionally add the pipeline files\r\nto help with compiling the module, publishing to a repository like\r\n_PowerShell Gallery_ and GitHub, and testing quality and style such as\r\nper the DSC Community guidelines.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nNew-SampleModule -DestinationPath \u003cString\u003e [-ModuleType \u003cString\u003e] [-ModuleAuthor \u003cString\u003e]\r\n  -ModuleName \u003cString\u003e [-ModuleDescription \u003cString\u003e] [-CustomRepo \u003cString\u003e]\r\n  [-ModuleVersion \u003cString\u003e] [-LicenseType \u003cString\u003e] [-SourceDirectory \u003cString\u003e]\r\n  [\u003cCommonParameters\u003e]\r\n\r\nNew-SampleModule -DestinationPath \u003cString\u003e [-ModuleAuthor \u003cString\u003e] -ModuleName \u003cString\u003e\r\n  [-ModuleDescription \u003cString\u003e] [-CustomRepo \u003cString\u003e] [-ModuleVersion \u003cString\u003e]\r\n  [-LicenseType \u003cString\u003e] [-SourceDirectory \u003cString\u003e] [-Features \u003cString[]\u003e]\r\n  [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\nNone.\r\n\r\n#### Example\r\n\r\nSee section [Usage](#usage).\r\n\r\n## Commands for Build Tasks\r\n\r\nThese commands are primarily meant to be used in tasks that exist either\r\nin Sampler or in third-party modules.\r\n\r\nRefer to the comment-based help for more information about these commands.\r\n\r\n### `Convert-SamplerHashtableToString`\r\n\r\nConvert a Hashtable to a string representation. For instance, calling the\r\nfunction with this hashtable:\r\n\r\n```powershell\r\n@{a=1;b=2; c=3; d=@{dd='abcd'}}\r\n```\r\n\r\nwill return:\r\n\r\n```plaintext\r\na=1; b=2; c=3; d={dd=abcd}\r\n```\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nConvert-SamplerHashtableToString [[-Hashtable] \u003cHashtable\u003e] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n```powershell\r\nConvert-SamplerhashtableToString -Hashtable @{a=1;b=2; c=3; d=@{dd='abcd'}}\r\n```\r\n\r\nThis example will return the string representation of the provided hashtable.\r\n\r\n### `Get-BuiltModuleVersion`\r\n\r\nWill read the properties `ModuleVersion` and `PrivateData.PSData.Prerelease` tag\r\nof the module manifest for a module that has been built by Sampler. The command\r\nlooks into the **OutputDirectory** where the project's module should have been\r\nbuilt.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-BuiltModuleVersion [-OutputDirectory] \u003cString\u003e [[-BuiltModuleSubdirectory] \u003cString\u003e]\r\n  [-ModuleName] \u003cString\u003e [-VersionedOutputDirectory] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n```powershell\r\nGet-BuiltModuleVersion -OutputDirectory 'output' -ProjectName 'MyModuleName'\r\n```\r\n\r\nThis example will return the module version of the built module 'MyModuleName'.\r\n\r\n### `Get-ClassBasedResourceName`\r\n\r\nThis command returns all the class-based DSC resource names in a script file.\r\nThe script file is parsed for classes with the `[DscResource()]` attribute.\r\n\r\n\u003e **Note:** For MOF-based DSC resources, look at the command\r\n\u003e[`Get-MofSchemaName`](#get-mofschemaname).\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-ClassBasedResourceName [-Path] \u003cString\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n```powershell\r\nGet-ClassBasedResourceName -Path 'source/Classes/MyDscResource.ps1'\r\n```\r\n\r\nThis example will return the class-based DSC resource names in the script\r\nfile **MyDscResource.ps1**.\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nImport-Module -Name 'MyResourceModule'\r\n\r\n$module = Get-Module -Name 'MyResourceModule'\r\n\r\nGet-ClassBasedResourceName -Path (Join-Path -Path $module.ModuleBase -ChildPath $module.RootModule)\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return the class-based DSC resource names in built module\r\nscript file for the module named 'MyResourceModule'.\r\n\r\n### `Get-CodeCoverageThreshold`\r\n\r\nThis command returns the **CodeCoverageThreshold** from the build configuration\r\n(or overridden if the parameter `RuntimeCodeCoverageThreshold` is passed).\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-CodeCoverageThreshold [[-RuntimeCodeCoverageThreshold] \u003cString\u003e]\r\n  [[-BuildInfo] \u003cPSObject\u003e] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.Int]`\r\n\r\n#### Example\r\n\r\n```powershell\r\nGet-CodeCoverageThreshold -RuntimeCodeCoverageThreshold 0\r\n```\r\n\r\nThis example will override the code coverage threshold in the build\r\nconfiguration and return the value pass in the parameter **RuntimeCodeCoverageThreshold**.\r\n\r\n### `Get-MofSchemaName`\r\n\r\nThis command looks within a DSC resource's .MOF schema file to find the name\r\nand friendly name of the class.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-MofSchemaName [-Path] \u003cString\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.Collections.Hashtable]`\r\n\r\n| Property Name | Type              | Description                    |\r\n| ------------- | ----------------- | ------------------------------ |\r\n| Name          | `[System.String]` | The name of class              |\r\n| FriendlyName  | `[System.String]` | The friendly name of the class |\r\n\r\n#### Example\r\n\r\n```powershell\r\nGet-MofSchemaName -Path Source/DSCResources/MyResource/MyResource.schema.mof\r\n```\r\n\r\nThis example will return a hashtable containing the name and friendly name\r\nof the MOF-based resource **MyResource**.\r\n\r\n### `Get-OperatingSystemShortName`\r\n\r\nThis command tells what the platform is; `Windows`, `Linux`, or `MacOS`.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-OperatingSystemShortName [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n```powershell\r\nGet-OperatingSystemShortName\r\n```\r\n\r\nThis example will return what platform it is run on.\r\n\r\n### `Get-PesterOutputFileFileName`\r\n\r\nThis command creates a file name to be used as Pester output XML file name.\r\nThe file name will be composed in the format:\r\n`${ProjectName}_v${ModuleVersion}.${OsShortName}.${PowerShellVersion}.xml`\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-OperatingSystemShortName [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nGet-PesterOutputFileFileName -ProjectName 'Sampler' -ModuleVersion '0.110.4-preview001' -OsShortName 'Windows' -PowerShellVersion '5.1'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return the string `Sampler_v0.110.4-preview001.Windows.5.1.xml`.\r\n\r\n### `Get-SamplerAbsolutePath`\r\n\r\nThis command will resolve the absolute value of a path, whether it's\r\npotentially relative to another path, relative to the current working\r\ndirectory, or it's provided with an absolute path.\r\n\r\nThe path does not need to exist, but the command will use the right\r\n`[System.Io.Path]::DirectorySeparatorChar` for the OS, and adjust the\r\n`..` and `.` of a path by removing parts of a path when needed.\r\n\r\n\u003e **Note:**  When the root drive is omitted on Windows, the path is not\r\n\u003e considered absolute.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerAbsolutePath [[-Path] \u003cString\u003e] [[-RelativeTo] \u003cString\u003e] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n```powershell\r\nGet-SamplerAbsolutePath -Path '/src' -RelativeTo 'C:\\Windows'\r\n```\r\n\r\nThis example will return the string `C:\\src` on Windows.\r\n\r\n```powershell\r\nGet-SamplerAbsolutePath -Path 'MySubFolder' -RelativeTo '/src'\r\n```\r\n\r\nThis example will return the string `C:\\src\\MySubFolder` on Windows.\r\n\r\n### `Get-SamplerBuiltModuleBase`\r\n\r\nThis command returns the module base of the built module.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerBuiltModuleBase [-OutputDirectory] \u003cString\u003e [[-BuiltModuleSubdirectory] \u003cString\u003e]\r\n  [-ModuleName] \u003cString\u003e [-VersionedOutputDirectory] [[-ModuleVersion] \u003cString\u003e]\r\n  [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nGet-SamplerBuiltModuleBase -OutputDirectory 'C:\\src\\output' -BuiltModuleSubdirectory 'Module' -ModuleName 'stuff' -ModuleVersion '3.1.2-preview001'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return the string `C:\\src\\output\\Module\\stuff\\3.1.2`.\r\n\r\n### `Get-SamplerBuiltModuleManifest`\r\n\r\nThis command returns the path to the built module's manifest.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerBuiltModuleManifest [-OutputDirectory] \u003cString\u003e [[-BuiltModuleSubdirectory] \u003cString\u003e]\r\n  [-ModuleName] \u003cString\u003e [-VersionedOutputDirectory] [[-ModuleVersion] \u003cString\u003e] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nGet-SamplerBuiltModuleManifest -OutputDirectory 'C:\\src\\output' -BuiltModuleSubdirectory 'Module' -ModuleName 'stuff' -ModuleVersion '3.1.2-preview001'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return the string `C:\\src\\output\\Module\\stuff\\3.1.2\\stuff.psd1`.\r\n\r\n### `Get-SamplerCodeCoverageOutputFile`\r\n\r\nThis command resolves the code coverage output file path from the project's\r\nbuild configuration.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerCodeCoverageOutputFile [-BuildInfo] \u003cPSObject\u003e [-PesterOutputFolder] \u003cString\u003e\r\n  [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nGet-SamplerCodeCoverageOutputFile -BuildInfo $buildInfo -PesterOutputFolder 'C:\\src\\MyModule\\Output\\testResults'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return the code coverage output file path.\r\n\r\n### `Get-SamplerCodeCoverageOutputFileEncoding`\r\n\r\nThis command resolves the code coverage output file encoding from the project's\r\nbuild configuration.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerCodeCoverageOutputFileEncoding [-BuildInfo] \u003cPSObject\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nGet-SamplerCodeCoverageOutputFileEncoding -BuildInfo $buildInfo\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return the code coverage output file encoding.\r\n\r\n### `Get-SamplerModuleInfo`\r\n\r\nThis command loads a module manifest and returns the hashtable.\r\nThis implementation works around the issue where Windows PowerShell has\r\nissues with the pwsh `$env:PSModulePath` such as in _VS Code_ with the _VS Code_\r\n_PowerShell extension_.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerModuleInfo [-ModuleManifestPath] \u003cString\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.Collections.Hashtable]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nGet-SamplerModuleInfo -ModuleManifestPath 'C:\\src\\MyProject\\output\\MyProject\\MyProject.psd1'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return the module manifest's hashtable.\r\n\r\n### `Get-SamplerModuleRootPath`\r\n\r\nThis command reads the module manifest (.psd1) and if the `ModuleRoot` property\r\nis defined it will resolve its absolute path based on the module manifest's\r\npath. If there is no `ModuleRoot` property defined, then this function will\r\nreturn `$null`.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerModuleRootPath [-ModuleManifestPath] \u003cString\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nGet-SamplerModuleRootPath -ModuleManifestPath C:\\src\\MyModule\\output\\MyModule\\2.3.4\\MyModule.psd1\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return the path to module script file, e.g. `C:\\src\\MyModule\\output\\MyModule\\2.3.4\\MyModule.psm1`.\r\n\r\n### `Get-SamplerProjectName`\r\n\r\nThis command returns the project name based on the module manifest, if no\r\nmodule manifest is available it will return `$null`.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerProjectName [-BuildRoot] \u003cString\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n```powershell\r\nGet-SamplerProjectName -BuildRoot 'C:\\src\\MyModule'\r\n```\r\n\r\nThis example will return the project name of the module in the path `C:\\src\\MyModule`.\r\n\r\n### `Get-SamplerSourcePath`\r\n\r\nThis command returns the project's source path based on the module manifest,\r\nif no module manifest is available it will return `$null`.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nGet-SamplerSourcePath [-BuildRoot] \u003cString\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.String]`\r\n\r\n#### Example\r\n\r\n```powershell\r\nGet-SamplerSourcePath -BuildRoot 'C:\\src\\MyModule'\r\n```\r\n\r\nThis example will return the project's source path of the module in the\r\npath `C:\\src\\MyModule`.\r\n\r\n### `Merge-JaCoCoReport`\r\n\r\nThis command merges two JaCoCo reports and return the resulting merged JaCoCo\r\nreport.\r\n\r\n\u003e **Note:** Also see the command [Update-JaCoCoStatistic](#ppdate-jacocostatistic).\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nMerge-JaCoCoReport [-OriginalDocument] \u003cXmlDocument\u003e [-MergeDocument] \u003cXmlDocument\u003e\r\n  [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.Xml.XmlDocument]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nMerge-JaCoCoReport -OriginalDocument 'C:\\src\\MyModule\\Output\\JaCoCoRun_linux.xml' -MergeDocument 'C:\\src\\MyModule\\Output\\JaCoCoRun_windows.xml'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will merge the JaCoCo report `JaCoCoRun_windows.xml` into the\r\nJaCoCo report `JaCoCoRun_linux.xml` and then return the resulting JaCoCo report.\r\n\r\n### `New-SamplerJaCoCoDocument`\r\n\r\nThis command creates a new JaCoCo XML document based on the provided missed\r\nand hit lines. This command is usually used together with the output object\r\nfrom Pester that also have been passed through ModuleBuilder's command\r\n`Convert-LineNumber`.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nNew-SamplerJaCoCoDocument [-MissedCommands] \u003cObject[]\u003e [-HitCommands] \u003cObject[]\u003e\r\n  [-PackageName] \u003cString\u003e [[-PackageDisplayName] \u003cString\u003e] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.Xml.XmlDocument]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\n# Assuming Pester 4, for Pester 5 change the commands accordingly.\r\n$pesterObject = Invoke-Pester ./tests/unit -CodeCoverage -PassThru\r\n\r\n$pesterObject.CodeCoverage.MissedCommands |\r\n   Convert-LineNumber -ErrorAction 'Stop' -PassThru | Out-Null\r\n\r\n$pesterObject.CodeCoverage.HitCommands |\r\n   Convert-LineNumber -ErrorAction 'Stop' -PassThru | Out-Null\r\n\r\nNew-SamplerJaCoCoDocument `\r\n   -MissedCommands $pesterObject.CodeCoverage.MissedCommands `\r\n   -HitCommands $pesterObject.CodeCoverage.HitCommands `\r\n   -PackageName 'source'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will create a new JaCoCo report based on the commands that\r\nwas hit or missed from the Pester run. It will use the ModuleBuilder's\r\ncommand `Convert-LineNumber` to correlate the correct line number from\r\nthe built module script file to the source script files.\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nNew-SamplerJaCoCoDocument `\r\n   -MissedCommands @{\r\n         Class            = 'ResourceBase'\r\n         Function         = 'Compare'\r\n         HitCount         = 0\r\n         SourceFile       = '.\\Classes\\001.ResourceBase.ps1'\r\n         SourceLineNumber = 4\r\n   } `\r\n   -HitCommands @{\r\n         Class            = 'ResourceBase'\r\n         Function         = 'Compare'\r\n         HitCount         = 2\r\n         SourceFile       = '.\\Classes\\001.ResourceBase.ps1'\r\n         SourceLineNumber = 3\r\n   } `\r\n   -PackageName 'source'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will create a new JaCoCo report based on the two hashtables\r\ncontaining hit or missed line.\r\n\r\n### `Out-SamplerXml`\r\n\r\nThis command outputs an XML document to the file specified in the parameter\r\n**Path**.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nOut-SamplerXml [-XmlDocument] \u003cXmlDocument\u003e [-Path] \u003cString\u003e [[-Encoding] \u003cString\u003e]\r\n  [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\nNone.\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nOut-SamplerXml -Path 'C:\\temp\\my.xml' -XmlDocument '\u003c?xml version=\"1.0\"?\u003e\u003ca\u003e\u003cb /\u003e\u003c/a\u003e' -Encoding 'UTF8'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will create a new XML file based on the XML document passed\r\nin the parameter **XmlDocument**.\r\n\r\n### `Set-SamplerTaskVariable`\r\n\r\nThis is an alias that points to a script file that is meant to be dot-sourced\r\nfrom (in) a build task. The script will set common task variables for a build\r\ntask. This function should normally never be called outside of a build task, but\r\nan exception can be tests; tests can call the alias to set the values prior to\r\nrunning tests.\r\n\r\n\u003e **Note:** Running the command `Get-Help -Name 'Set-SamplerTaskVariable'` will\r\n\u003e only return help for the alias. To see the comment-based help for the script,\r\n\u003e run:\r\n\u003e\r\n\u003e ```powershell\r\n\u003e Import-Module -Name Sampler\r\n\u003e\r\n\u003e Get-Help -Name (Get-Alias -Name 'Set-SamplerTaskVariable').Definition -Detailed\r\n\u003e ```\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nSet-SamplerTaskVariable [-AsNewBuild] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\nNone. Sets variables in the current PowerShell session. See comment-based help\r\nfor more information about the variables that are set.\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\n. Set-SamplerTaskVariable\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nCall the scriptblock and tells the script to evaluate the module version\r\nby not checking after the module manifest in the built module.\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\n. Set-SamplerTaskVariable -AsNewBuild\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nCall the scriptblock set script variables. The parameter **AsNewBuild** tells\r\nthe script to skip variables that can only be set when the module has been\r\nbuilt.\r\n\r\n### `Split-ModuleVersion`\r\n\r\nThis command parses a SemVer2 version string, and also a version string returned\r\nby a certain property of GitVersion (containing additional metadata).\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nSplit-ModuleVersion [[-ModuleVersion] \u003cString\u003e] [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.Management.Automation.PSCustomObject]`\r\n\r\n| Property Name    | Type              | Description                                    |\r\n| ---------------- | ----------------- | ---------------------------------------------- |\r\n| Version          | `[System.String]` | The module version (without prerelease string) |\r\n| PreReleaseString | `[System.String]` | The prerelease string part                     |\r\n| ModuleVersion    | `[System.String]` | The full semantic version                      |\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nSplit-ModuleVersion -ModuleVersion '1.15.0-pr0224-0022+Sha.47ae45eb2cfed02b249f239a7c55e5c71b26ab76.Date.2020-01-07'\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return a hashtable with the different parts of the module\r\nversion for a version string that was returned by GitVersion.\r\n\r\n### `Update-JaCoCoStatistic`\r\n\r\nThis command updates statistics of a JaCoCo report. This is meant to be\r\nrun after the command [`Merge-JaCoCoReport`](#merge-jacocoreport) has been\r\nused.\r\n\r\n#### Syntax\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```plaintext\r\nUpdate-JaCoCoStatistic [-Document] \u003cXmlDocument\u003e [\u003cCommonParameters\u003e]\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\n#### Outputs\r\n\r\n`[System.Xml.XmlDocument]`\r\n\r\n#### Example\r\n\r\n\u003c!-- markdownlint-disable MD013 - Line length --\u003e\r\n```powershell\r\nUpdate-JaCoCoStatistic -Document (Merge-JaCoCoReport OriginalDocument $report1 -MergeDocument $report2)\r\n```\r\n\u003c!-- markdownlint-enable MD013 - Line length --\u003e\r\n\r\nThis example will return a XML document containing the JaCoCo report with\r\nthe updated statistics.\r\n\r\n## Build Task Variables\r\n\r\nA task variable is used in a build task and it can be added as a script\r\nparameter to build.ps1 or set as as an environment variable. It can often\r\nbe used if defined in parent scope or read from the $BuildInfo properties\r\ndefined in the configuration file.\r\n\r\n### `BuildModuleOutput`\r\n\r\nThis is the path where the module will be built. The path will, for example,\r\nbe used for the parameter `OutputDirectory` when calling the cmdlet\r\n`Build-Module` of the PowerShell module _Invoke-Build_. Defaults to\r\nthe path for `OutputDirectory`, and concatenated with `BuiltModuleSubdirectory`\r\nif it is set.\r\n\r\n### `BuiltModuleSubdirectory`\r\n\r\nAn optional path that will suffix the `OutputDirectory` to build the\r\ndefault path in variable `BuildModuleOutput`.\r\n\r\n### `ModuleVersion`\r\n\r\nThe module version of the built module. Defaults to the property `NuGetVersionV2`\r\nreturned by the executable `gitversion`, or if the executable `gitversion`\r\nis not available the the variable defaults to an empty string, and the\r\nbuild module task will use the version found in the Module Manifest.\r\n\r\nIt is also possible to set the session environment variable `$env:ModuleVersion`\r\nin the PowerShell session or set the variable `$ModuleVersion` in the\r\nPowerShell session (the parent scope to `Invoke-Build`) before running the\r\ntask `build`\r\n\r\nThis `ModuleVersion` task variable can be overridden by using the key `SemVer`\r\nin the file `build.yml`, e.g. `SemVer: '99.0.0-preview1'`. This can be used\r\nif the preferred method of using GitVersion is not available.\r\n\r\nThe order that the module version is determined is as follows:\r\n\r\n1. the parameter `ModuleVersion` is set from the command line (passing parameter\r\n   to build task)\r\n1. if no parameter was passed it defaults to using the property from the\r\n   environment variable `$env:ModuleVersion` or parent scope variable\r\n   `$ModuleVersion`\r\n1. if the `ModuleVersion` is still not found it will try to use `GitVersion`\r\n   if it is available\r\n1. if `GitVersion` is not available the module version is set from the module\r\n   manifest in the source path using the properties `ModuleVersion` and\r\n   `PrivateData.PSData.Prerelease`\r\n1. if module version is set using key `SemVer` in `build.yml` it will\r\n   override 1), 2), 3), and 4)\r\n1. ~~if `SemVar` is set through parameter from the command line then it will~~\r\n   ~~override 1), 2), 3), 4), and 5)~~. This is not yet supported.\r\n\r\n### `OutputDirectory`\r\n\r\nThe base directory of all output from the build tasks. This is the path\r\nwhere artifacts will be built or saved such as the built module, required\r\nmodules downloaded at build time, test results, etc. This folder should\r\nbe ignored by git as its content is ephemeral. It defaults to the folder\r\n'output', a path relative to the root of the repository (same as `Invoke-Build`'s\r\n[`$BuildRoot`](https://github.com/nightroman/Invoke-Build/wiki/Special-Variables#buildroot)).\r\nYou can override this setting with an absolute path should you need to.\r\n\r\n### `ProjectPath`\r\n\r\nThe root path to the project. Defaults to [`$BuildRoot`](https://github.com/nightroman/Invoke-Build/wiki/Special-Variables#buildroot).\r\n\r\n### `ProjectName`\r\n\r\nThe project name. Defaults to the BaseName of the module manifest it finds\r\nin either the folder 'source', 'src, or a folder with the same name as the\r\nmodule.\r\n\r\n### `ReleaseNotesPath`\r\n\r\nTHe path to the release notes markdown file. Defaults to the path for\r\n`OutputDirectory` concatenated with `ReleaseNotes.md`.\r\n\r\n### `SourcePath`\r\n\r\nThe path to the source folder. Defaults to the same path where the module\r\nmanifest is found in either the folder 'source', 'src', or a folder with\r\nthe same name as the module.\r\n\r\n## Tasks\r\n\r\n### `Create_Changelog_Branch`\r\n\r\nThis build task creates pushes a branch with the changelog updated with\r\nthe current release version.\r\n\r\nThis is an example of how to use the task in the _azure-pipelines.yml_ file:\r\n\r\n```yaml\r\n- task: PowerShell@2\r\n  name: sendChangelogPR\r\n  displayName: 'Send Changelog PR'\r\n  inputs:\r\n    filePath: './build.ps1'\r\n    arguments: '-tasks Create_Changelog_Branch'\r\n    pwsh: true\r\n  env:\r\n    MainGitBranch: 'main'\r\n    BasicAuthPAT: $(BASICAUTHPAT)\r\n```\r\n\r\nThis can be use in conjunction with the `Create_Release_Git_Tag` task\r\nthat creates the release tag.\r\n\r\n```yaml\r\n  publish:\r\n    - Create_Release_Git_Tag\r\n    - Create_Changelog_Branch\r\n```\r\n\r\n#### Task parameters\r\n\r\nSome task parameters are vital for the resource to work. See comment based\r\nhelp for the description for each available parameter. Below is the most\r\nimportant.\r\n\r\n#### Task configuration\r\n\r\nThe build configuration (_build.yaml_) can be used to control the behavior\r\nof the build task.\r\n\r\n```yaml\r\n####################################################\r\n#             Changelog Configuration              #\r\n####################################################\r\nChangelogConfig:\r\n  FilesToAdd:\r\n    - 'CHANGELOG.md'\r\n  UpdateChangelogOnPrerelease: false\r\n\r\n####################################################\r\n#                Git Configuration                 #\r\n####################################################\r\nGitConfig:\r\n  UserName: bot\r\n  UserEmail: bot@company.local\r\n```\r\n\r\n#### Section ChangelogConfig\r\n\r\n##### Property FilesToAdd\r\n\r\nThis specifies one or more files to add to the commit when creating the\r\nPR branch. If left out it will default to the one file _CHANGELOG.md_.\r\n\r\n##### Property UpdateChangelogOnPrerelease\r\n\r\n- `true`: Always create a changelog PR, even on preview releases.\r\n- `false`: Only create a changelog PR for full releases. Default.\r\n\r\n#### Section GitConfig\r\n\r\nThis configures git.  user name and e-mail address of the user before task pushes the\r\ntag.\r\n\r\n##### Property UserName\r\n\r\nUser name of the user that should push the tag.\r\n\r\n##### Property UserEmail\r\n\r\nE-mail address of the user that should push the tag.\r\n\r\n### `Create_Release_Git_Tag`\r\n\r\nThis build task creates and pushes a preview release tag to the default branch.\r\n\r\n\u003eNote: This task is primarily meant to be used for SCM's that does not have\r\n\u003ereleases that connects to tags like GitHub does with GitHub Releases, but\r\n\u003ethis task can also be used as an alternative when using GitHub as SCM.\r\n\r\nThis is an example of how to use the task in the _build.yaml_ file:\r\n\r\n```yaml\r\n  publish:\r\n    - Create_Release_Git_Tag\r\n```\r\n\r\n#### Task parameters\r\n\r\nSome task parameters are vital for the resource to work. See comment based\r\nhelp for the description for each available parameter. Below is the most\r\nimportant.\r\n\r\n#### Task configuration\r\n\r\nThe build configuration (_build.yaml_) can be used to control the behavior\r\nof the build task.\r\n\r\n```yaml\r\n####################################################\r\n#                Git Configuration                 #\r\n####################################################\r\nGitConfig:\r\n  UserName: bot\r\n  UserEmail: bot@company.local\r\n```\r\n\r\n#### Section GitConfig\r\n\r\nThis configures git.  user name and e-mail address of the user before task pushes the\r\ntag.\r\n\r\n##### Property UserName\r\n\r\nUser name of the user that should push the tag.\r\n\r\n##### Property UserEmail\r\n\r\nE-mail address of the user that should push the tag.\r\n\r\n### `Set_PSModulePath`\r\n\r\nThis task sets the `PSModulePath` according to the configuration in the `build.yml`\r\nfile.\r\n\r\nThis task can be important when compiling DSC resource modules or\r\nDSC composite resource modules. When a DSC resource module is available in\r\n'Program Files' and the Required Modules folder, DSC sees this as a conflict.\r\n\r\n\u003e Note: The paths `$BuiltModuleSubdirectory` and `$RequiredModulesDirectory` are\r\n\u003e always prepended to the `PSModulePath`.\r\n\r\nThis sequence sets the `PSModulePath` before starting the tests.\r\n\r\n```yaml\r\n  test:\r\n    - Set_PSModulePath\r\n    - Pester_Tests_Stop_On_Fail\r\n    - Pester_If_Code_Coverage_Under_Threshold\r\n```\r\n\r\n#### Task parameters\r\n\r\nSome task parameters are vital for the resource to work. See comment based\r\nhelp for the description for each available parameter. Below is the most\r\nimportant.\r\n\r\n#### Task configuration\r\n\r\nThe build configuration (_build.yaml_) can be used to control the behavior\r\nof the build task.\r\n\r\n```yaml\r\n####################################################\r\n#           Setting Sampler PSModulePath           #\r\n####################################################\r\nSetPSModulePath:\r\n  PSModulePath: C:\\Users\\Install\\OneDrive\\Documents\\WindowsPowerShell\\Modules;C:\\Program Files\\WindowsPowerShell\\Modules;C:\\Windows\\system32\\WindowsPowerShell\\v1.0\\Modules;c:\\Users\\Install\\.vscode\\extensions\\ms-vscode.powershell-2022.5.1\\modules;\r\n  RemovePersonal: false\r\n  RemoveProgramFiles: false\r\n  RemoveWindows: false\r\n  SetSystemDefault: false\r\n```\r\n\r\nThe `PSModulePath` parameter can access variables and contain sub-expressions.\r\n\r\n```yaml\r\n####################################################\r\n#           Setting Sampler PSModulePath           #\r\n####################################################\r\nSetPSModulePath:\r\n  PSModulePath: $ProjectPath\\.temp\\Microsoft Azure AD Sync\\Bin;$([System.Environment]::GetFolderPath('ProgramFiles'))\\WindowsPowerShell\\Modules;$([System.Environment]::GetFolderPath('System'))\\WindowsPowerShell\\v1.0\\Modules\r\n  RemovePersonal: false\r\n  RemoveProgramFiles: false\r\n  RemoveWindows: false\r\n  SetSystemDefault: false\r\n```\r\n\r\n#### Section SetPSModulePath\r\n\r\n##### Property PSModulePath\r\n\r\nSets the `PSModulePath` to the specified value. This string is treated like an expandable\r\nstring and can access variables and contain sub-expressions.\r\n\r\n##### Property RemovePersonal\r\n\r\nRemoved the personal path from `PSModulePath`, like `C:\\Users\\Install\\Documents\\WindowsPowerShell\\Modules`.\r\n\r\n#### Section RemoveProgramFiles\r\n\r\nRemoved the 'Program Files' path from `PSModulePath`, like `C:\\Program Files\\WindowsPowerShell\\Modules`.\r\n\r\n##### Property RemoveWindows\r\n\r\nRemoved the Windows path from `PSModulePath`, like `C:\\Windows\\system32\\WindowsPowerShell\\v1.0\\Modules`.\r\n\r\n\u003e **Note: It is not recommended to remove the Windows path from `PSModulePath`.**\r\n\r\n##### Property SetSystemDefault\r\n\r\nSets the module path to what is defined for the machine. The machines `PSModulePath` is retrieved with this call:\r\n\r\n```powershell\r\n[System.Environment]::GetEnvironmentVariable('PSModulePath', 'Machine')\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaelcolas%2Fsampler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaelcolas%2Fsampler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaelcolas%2Fsampler/lists"}