Refactor build script pre/post to before/after.

ReleaseNotes.md

@@ -1,6 +1,7 @@
-## What is New in Plaster 0.1.0
-May 27, 2016
+## What is New in Plaster 0.3.0
+Nov 5, 2016
 
+* Updated build script with support for building help from markdown files, building updatable help files and generating file catalog.
 * Initial release shows the basics of what this module could do.
 
 ### Feedback

appveyor.yml

@@ -14,14 +14,13 @@ install:
 
 build_script:
   - ps: |
-      $testResultsFile = Join-Path $pwd -ChildPath "./TestResults.xml"
+      $testResultsFile = Join-Path $pwd -ChildPath "$PSScriptRoot/TestResults.xml"
       Invoke-psake build.psake.ps1 -taskList Test -properties @{"TestOutputFile" = $testResultsFile}
       if ($psake.build_success -and (Test-Path $testResultsFile)) {
-        (New-Object 'System.Net.WebClient').UploadFile("https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)", $testResultsFile)
+          (New-Object 'System.Net.WebClient').UploadFile("https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)", $testResultsFile)
       }
       else {
-        # Terminate the script to fail the build
-        exit 1;
+          # Terminate the script to fail the build
+          $Error | Format-List * -Force
+          exit 1;
       }
-
-

build.psake.ps1

@@ -67,6 +67,12 @@ Properties {
 
     [System.Diagnostics.CodeAnalysis.SuppressMessage('PSUseDeclaredVarsMoreThanAssigments', '')]
     $UpdatableHelpOutDir = "$OutDir\UpdatableHelp"
+
+    [System.Diagnostics.CodeAnalysis.SuppressMessage('PSUseDeclaredVarsMoreThanAssigments', '')]
+    $SharedProperties = @{}
+
+    [System.Diagnostics.CodeAnalysis.SuppressMessage('PSUseDeclaredVarsMoreThanAssigments', '')]
+    $LineSep = "-" * 78
 }
 
 ###############################################################################
@@ -75,7 +81,7 @@ Properties {
 Task default -depends Build
 
 Task Init -requiredVariables OutDir {
-    if (!(Test-Path $OutDir)) {
+    if (!(Test-Path -LiteralPath $OutDir)) {
         New-Item $OutDir -ItemType Directory -Verbose:$VerbosePreference > $null
     }
     else {
@@ -93,11 +99,11 @@ Task Clean -depends Init -requiredVariables OutDir {
     }
 }
 
-Task Build -depends BuildImpl, Analyze, Sign, PostBuild {
+Task StageFiles -depends Init, Clean, BeforeStageFiles, CoreStageFiles, AfterStageFiles {
 }
 
-Task BuildImpl -depends Init, Clean, PreBuild -requiredVariables ModuleOutDir, SrcRootDir {
-    if (!(Test-Path $ModuleOutDir)) {
+Task CoreStageFiles -requiredVariables ModuleOutDir, SrcRootDir {
+    if (!(Test-Path -LiteralPath $ModuleOutDir)) {
         New-Item $ModuleOutDir -ItemType Directory -Verbose:$VerbosePreference > $null
     }
     else {
@@ -107,7 +113,11 @@ Task BuildImpl -depends Init, Clean, PreBuild -requiredVariables ModuleOutDir, S
     Copy-Item -Path $SrcRootDir\* -Destination $ModuleOutDir -Recurse -Exclude $Exclude -Verbose:$VerbosePreference
 }
 
-Task Analyze -depends BuildImpl -requiredVariables ModuleOutDir, ScriptAnalysisEnabled, ScriptAnalysisFailBuildOnSeverityLevel, ScriptAnalyzerSettingsPath {
+Task Build -depends Init, Clean, BeforeBuild, StageFiles, Analyze, Sign, AfterBuild {
+}
+
+Task Analyze -depends StageFiles `
+             -requiredVariables ModuleOutDir, ScriptAnalysisEnabled, ScriptAnalysisFailBuildOnSeverityLevel, ScriptAnalyzerSettingsPath {
     if (!$ScriptAnalysisEnabled) {
         "Script analysis is not enabled. Skipping $($psake.context.currentTaskName) task."
         return
@@ -145,7 +155,7 @@ Task Analyze -depends BuildImpl -requiredVariables ModuleOutDir, ScriptAnalysisE
     }
 }
 
-Task Sign -depends BuildImpl -requiredVariables CertPath, SettingsPath, ScriptSigningEnabled {
+Task Sign -depends StageFiles -requiredVariables CertPath, SettingsPath, ScriptSigningEnabled {
     if (!$ScriptSigningEnabled) {
         "Script signing is not enabled. Skipping $($psake.context.currentTaskName) task."
         return
@@ -178,6 +188,8 @@ Task Sign -depends BuildImpl -requiredVariables CertPath, SettingsPath, ScriptSi
                        Sort-Object NotAfter -Descending | Select-Object -First 1
 
     if ($certificate) {
+        $SharedProperties.CodeSigningCertificate = $certificate
+
         if ($storeCertSubjectName) {
             SetSetting -Key $certSubjectNameKey -Value $certificate.SubjectName.Name -Path $SettingsPath
             "The new certificate subject name has been stored in ${SettingsPath}."
@@ -186,11 +198,19 @@ Task Sign -depends BuildImpl -requiredVariables CertPath, SettingsPath, ScriptSi
             "Using stored certificate subject name $CertSubjectName from ${SettingsPath}."
         }
 
+        $LineSep
         "Using code-signing certificate: $certificate"
+        $LineSep
 
         $files = @(Get-ChildItem -Path $ModuleOutDir\* -Recurse -Include *.ps1,*.psm1)
         foreach ($file in $files) {
-            $result = Set-AuthenticodeSignature -FilePath $file.FullName -Certificate $certificate -Verbose:$VerbosePreference
+            $setAuthSigParams = @{
+                FilePath = $file.FullName
+                Certificate = $certificate
+                Verbose = $VerbosePreference
+            }
+
+            $result = Microsoft.PowerShell.Security\Set-AuthenticodeSignature @setAuthSigParams
             if ($result.Status -ne 'Valid') {
                 throw "Failed to sign script: $($file.FullName)."
             }
@@ -212,7 +232,15 @@ Task Sign -depends BuildImpl -requiredVariables CertPath, SettingsPath, ScriptSi
     }
 }
 
-Task GenerateMarkdown -depends Build, PreBuildHelp -requiredVariables DefaultLocale, DocsRootDir, ModuleName, ModuleOutDir {
+Task BuildHelp -depends Build, BeforeBuildHelp, GenerateMarkdown, GenerateHelpFiles, AfterBuildHelp {
+}
+
+Task GenerateMarkdown -requiredVariables DefaultLocale, DocsRootDir, ModuleName, ModuleOutDir {
+    if (!(Get-Module platyPS -ListAvailable)) {
+        "platyPS module is not installed. Skipping $($psake.context.currentTaskName) task."
+        return
+    }
+
     $moduleInfo = Import-Module $ModuleOutDir\$ModuleName.psd1 -Global -Force -PassThru
 
     try {
@@ -240,11 +268,13 @@ Task GenerateMarkdown -depends Build, PreBuildHelp -requiredVariables DefaultLoc
     }
 }
 
-Task BuildHelp -depends BuildHelpImpl, PostBuildHelp {
-}
+Task GenerateHelpFiles -requiredVariables DocsRootDir, ModuleName, ModuleOutDir, OutDir {
+    if (!(Get-Module platyPS -ListAvailable)) {
+        "platyPS module is not installed. Skipping $($psake.context.currentTaskName) task."
+        return
+    }
 
-Task BuildHelpImpl -depends GenerateMarkdown -requiredVariables DocsRootDir, ModuleName, ModuleOutDir, OutDir {
-    if (!(Test-Path -LiteralPath $DocsRootDir) -or !(Get-ChildItem -LiteralPath $DocsRootDir -Filter *.md -Recurse)) {
+    if (!(Get-ChildItem -LiteralPath $DocsRootDir -Filter *.md -Recurse -ErrorAction SilentlyContinue)) {
         "No markdown help files to process. Skipping $($psake.context.currentTaskName) task."
         return
     }
@@ -256,36 +286,93 @@ Task BuildHelpImpl -depends GenerateMarkdown -requiredVariables DocsRootDir, Mod
         New-ExternalHelp -Path $DocsRootDir\$locale -OutputPath $ModuleOutDir\$locale -Force `
                          -ErrorAction SilentlyContinue -Verbose:$VerbosePreference > $null
     }
+}
+
+Task BuildUpdatableHelp -depends BuildHelp, BeforeBuildUpdatableHelp, CoreBuildUpdatableHelp, AfterBuildUpdatableHelp {
+}
+
+Task CoreBuildUpdatableHelp -requiredVariables DocsRootDir, ModuleName, UpdatableHelpOutDir {
+    if (!(Get-Module platyPS -ListAvailable)) {
+        "platyPS module is not installed. Skipping $($psake.context.currentTaskName) task."
+        return
+    }
+
+    $helpLocales = (Get-ChildItem -Path $DocsRootDir -Directory).Name
 
     # Create updatable help output directory.
-    if (!(Test-Path $UpdatableHelpOutDir)) {
+    if (!(Test-Path -LiteralPath $UpdatableHelpOutDir)) {
         New-Item $UpdatableHelpOutDir -ItemType Directory -Verbose:$VerbosePreference > $null
     }
     else {
         Write-Verbose "$($psake.context.currentTaskName) - directory already exists '$UpdatableHelpOutDir'."
         Get-ChildItem $UpdatableHelpOutDir | Remove-Item -Recurse -Force -Verbose:$VerbosePreference
     }
 
-    # Generate updatable help files.
+    # Generate updatable help files.  Note: this will currently update the version number in the module's MD
+    # file in the metadata.
     foreach ($locale in $helpLocales) {
         New-ExternalHelpCab -CabFilesFolder $ModuleOutDir\$locale -LandingPagePath $DocsRootDir\$locale\$ModuleName.md `
                             -OutputFolder $UpdatableHelpOutDir -Verbose:$VerbosePreference > $null
     }
 }
 
-Task Install -depends InstallImpl, PostInstall {
+Task GenerateFileCatalog -depends Build, BuildHelp, BeforeGenerateFileCatalog, CoreGenerateFileCatalog, AfterGenerateFileCatalog {
 }
 
-Task InstallImpl -depends BuildHelp, PreInstall -requiredVariables ModuleOutDir {
-    if ($null -eq $InstallPath) {
-        # The default installation path is the current user's module path.
-        $moduleInfo = Test-ModuleManifest -Path $SrcRootDir\$ModuleName.psd1
-        $InstallPath = Join-Path -Path (Split-Path $profile.CurrentUserAllHosts -Parent) `
-                                 -ChildPath "Modules\$ModuleName\$($moduleInfo.Version.ToString())"
+Task CoreGenerateFileCatalog -requiredVariables CatalogGenerationEnabled, CatalogVersion, ModuleName, ModuleOutDir, OutDir {
+    if (!$CatalogGenerationEnabled) {
+        "FileCatalog generation is not enabled. Skipping $($psake.context.currentTaskName) task."
+        return
+    }
+
+    if (!(Get-Command Microsoft.PowerShell.Security\New-FileCatalog -ErrorAction SilentlyContinue)) {
+        "FileCatalog commands not available on this version of PowerShell. Skipping $($psake.context.currentTaskName) task."
+        return
+    }
+
+    $catalogFilePath = "$OutDir\$ModuleName.cat"
+
+    $newFileCatalogParams = @{
+        Path = $ModuleOutDir
+        CatalogFilePath = $catalogFilePath
+        CatalogVersion = $CatalogVersion
+        Verbose = $VerbosePreference
+    }
+
+    Microsoft.PowerShell.Security\New-FileCatalog @newFileCatalogParams > $null
+
+    if ($ScriptSigningEnabled) {
+        if ($SharedProperties.CodeSigningCertificate) {
+            $setAuthSigParams = @{
+                FilePath = $catalogFilePath
+                Certificate = $SharedProperties.CodeSigningCertificate
+                Verbose = $VerbosePreference
+            }
+
+            $result = Microsoft.PowerShell.Security\Set-AuthenticodeSignature @setAuthSigParams
+            if ($result.Status -ne 'Valid') {
+                throw "Failed to sign file catalog: $($catalogFilePath)."
+            }
+
+            "Successfully signed file catalog: $($catalogFilePath)"
+        }
+        else {
+            "No code-signing certificate was found to sign the file catalog."
+        }
     }
+    else {
+        "Script signing is not enabled. Skipping signing of file catalog."
+    }
+
+    Move-Item -LiteralPath $newFileCatalogParams.CatalogFilePath -Destination $ModuleOutDir
+}
+
+Task Install -depends Build, BuildHelp, GenerateFileCatalog, BeforeInstall, CoreInstall, AfterInstall {
+}
 
-    if (!(Test-Path -Path $InstallPath)) {
-        Write-Verbose 'Creating local install directory'
+Task CoreInstall -requiredVariables ModuleOutDir {
+    if (!(Test-Path -LiteralPath $InstallPath)) {
+        Write-Verbose 'Creating install directory'
         New-Item -Path $InstallPath -ItemType Directory -Verbose:$VerbosePreference > $null
     }
 
@@ -342,10 +429,10 @@ Task Test -depends Build -requiredVariables TestRootDir, ModuleName, CodeCoverag
     }
 }
 
-Task Publish -depends Test, PrePublish, PublishImpl, PostPublish {
+Task Publish -depends Build, Test, BuildHelp, GenerateFileCatalog, BeforePublish, CorePublish, AfterPublish {
 }
 
-Task PublishImpl -requiredVariables SettingsPath, ModuleOutDir {
+Task CorePublish -requiredVariables SettingsPath, ModuleOutDir {
     $publishParams = @{
         Path        = $ModuleOutDir
         NuGetApiKey = $NuGetApiKey