Examples of Strongly Opinionated (Custom) Tasks In ReadMe

[bwright86]

Assumption

I believe this module has the ability for users to write custom tasks to the psakebuild.ps1 file, and PowershellBuild will execute what it covers, while PSake executes the custom tasks.

This may be as simple as writing the custom tasks, and adding dependencies from the executing tasks (Build, Publish, Test, etc...)

Request

Would it be worth showing in the ReadMe examples, to show that PowershellBuild helps standardize, but doesn't restrict you from customizing it?

I could help write some examples, if this would be helpful.

Context

I am currently using Git, and wanted to add a "Git Tag" task when I publish a new version of a module. But was struggling at first on how to integrate this while using PowershellBuild. (I am still wrestling on whether tagging should be done at the tip of the commit that adds the feature, or when the artifact is created to be published.)

[thedavecarroll]

I, too, was struggling on how to fit PowerShellBuild into my existing project which had a simple build.ps1 script that I wrote custom for it.

Root Module

I was taken aback when I realized that the Compile option appended the contents of the source root module, rather than starting with that (this was an assumption that my previous script used). I got around this by creating a Prepend folder where I placed my root module and then creating a blank root module in the source path (it failed when this didn't exist).

I also needed to ensure that the module was initialized via a few commands that had to be defined prior to calling. I created an Append folder and put this at the end of the compile directories.

Task Override Not Supported

I tried to override the GenerateMAMLHelp because I specifically did not want it to depend on creating markdown docs, which I have already done. I created a new task in the psakeBuild.ps1. For the project I'm working on, my markdown docs are hosted by readthedocs and I have multiple folders that separate the functions into user friendly categories.

I also wanted to generated an about_.help.txt file.

I was able to define a new task and just ignored the existing help tasks.

Example

I think the most important example that I missed on first take was that you could override the dependencies of the task from the module . Check out the task Build line in my example below.

Here is my psakeBuild.ps1:

properties {
    $PSBPreference.Build.OutDir = (Join-Path -Path $env:BHProjectPath -ChildPath 'BuildOutput')
    $PSBPreference.Build.CompileModule = $true
    $PSBPreference.Build.CompileDirectories = 'Prepend', 'Classes', 'Private', 'Public', 'Append'
    $PSBPreference.Build.CopyDirectories = 'resources'
    $PSBPreference.Build.CompileScriptHeader = [System.Environment]::NewLine
    $PSBPreference.Build.CopyDirectories =  (Join-Path -Path $env:BHPSModulePath -ChildPath 'resources')
}

task CompileApiEndpoint -Depends 'StageFiles' {
    $BuildHelperPath = Join-Path -Path $env:BHProjectPath -ChildPath 'build'
    $ApiEndpointSourcePath = Join-Path -Path $env:BHProjectPath -ChildPath 'Endpoints'
    $ApiEndpointJsonPath = Join-Path -Path $PSBPreference.Build.ModuleOutDir -ChildPath 'resources' -AdditionalChildPath 'TwitterApiEndpoints.json'

    Import-Module (Join-Path -Path $BuildHelperPath -ChildPath 'BuildFunctions.psm1')
    Import-TwitterApiEndpoints -Path $ApiEndpointSourcePath | ConvertTo-Json -Depth 20 | Add-Content -Path $ApiEndpointJsonPath

} -Description 'Compile the Twitter API Endpoint JSON resource'

task GenerateExternalHelp {
    $ExternalHelpPath = Join-Path -Path $PSBPreference.Build.ModuleOutDir -ChildPath (Get-UICulture).Name

    $MarkdownHelp = Get-ChildItem -Path $PSBPreference.Docs.RootDir -Include '*-*.md' -Recurse
    New-ExternalHelp -Path $MarkdownHelp -OutputPath $ExternalHelpPath -Force | Out-Null

    $AboutHelp = Get-ChildItem -Path (Join-Path -Path $PSBPreference.Docs.RootDir -ChildPath "about_$env:BHProjectName.md")
    New-ExternalHelp -Path $AboutHelp -OutputPath $ExternalHelpPath -Force | Out-Null

} -Description 'Generates MAML-based help from PlatyPS markdown files'

task AddFileListToManifest {

    $FileListParentFolder = '{0}{1}' -f $PSBPreference.Build.ModuleOutDir,[IO.Path]::DirectorySeparatorChar
    $FileList = Get-ChildItem -Path $PSBPreference.Build.ModuleOutDir -File -Recurse | ForEach-Object {
        $_.FullName.Replace($FileListParentFolder,'')
    }

    $BuildManifest = Join-Path -Path $PSBPreference.Build.ModuleOutDir -ChildPath "$env:BHProjectName.psd1"
    Update-Manifest -Path $BuildManifest -PropertyName FileList -Value $FileList

} -Description 'Add files list to module manifest'

task Build -FromModule PowerShellBuild -depends @('CompileApiEndpoint','GenerateExternalHelp','AddFileListToManifest')

task default -depends Build