Merge pull request #62 from PowershellFrameworkCollective/template-update

Template update

Author: FriedrichWeinmann

PSModuleDevelopment/changelog.md

@@ -1,4 +1,10 @@
 # Changelog
+## 2.2.?.?
+ - Upd: Set-PSMDEncoding - use `PSFEncoding` parameter class & tabcompletion
+ - Upd: Template PSFProject - build directly into psm1
+ - Upd: Template PSFProject, PSFModule - automatically read version in psm1 from psd1, rather than requiring explicit maintenance.
+ - Fix: Template PSFTest - use category exclusions
+
 ## 2.2.5.31 (September 29th, 2018)
  - Fix: Template PSFProject dependencies installed correctly
 

PSModuleDevelopment/functions/refactor/Set-PSMDEncoding.ps1

@@ -40,8 +40,8 @@
 		[string[]]
 		$Path,
 
-		[System.Text.Encoding]
-		$Encoding = [System.Text.Encoding]::UTF8,
+		[PSFEncoding]
+		$Encoding = (Get-PSFConfigValue -FullName 'psframework.text.encoding.defaultwrite' -Fallback 'utf-8'),
 
 		[switch]
 		$EnableException

PSModuleDevelopment/internal/tabcompletion/assignment.ps1

@@ -19,4 +19,8 @@ Register-PSFTeppArgumentCompleter -Name PSMD_templatename -Command Invoke-PSMDTe
 Register-PSFTeppArgumentCompleter -Name PSMD_templatestore -Command Remove-PSMDTemplate -Parameter Store
 Register-PSFTeppArgumentCompleter -Name PSMD_templatename -Command Remove-PSMDTemplate -Parameter TemplateName
 
-#endregion Templates
+#endregion Templates
+
+#region Refactor
+Register-PSFTeppArgumentCompleter -Name psframework-encoding -Command Set-PSMDEncoding -Parameter Encoding
+#endregion Refactor

templates/PSFModule/þnameþ.psd1

@@ -3,7 +3,7 @@
 	ModuleToProcess = 'þnameþ.psm1'
 
 	# Version number of this module.
-	ModuleVersion = '1.0.0.0'
+	ModuleVersion = '1.0.0'
 
 	# ID used to uniquely identify this module
 	GUID = 'þ!guid!þ'

templates/PSFModule/þnameþ.psm1

@@ -1,5 +1,5 @@
 $script:ModuleRoot = $PSScriptRoot
-$script:ModuleVersion = "1.0.0.0"
+$script:ModuleVersion = (Import-PowerShellDataFile -Path "$($script:ModuleRoot)\þnameþ.psd1").ModuleVersion
 
 # Detect whether at some level dotsourcing was enforced
 $script:doDotSource = Get-PSFConfigValue -FullName þnameþ.Import.DoDotSource -Fallback $false
@@ -17,7 +17,7 @@ This is important when testing for paths.
 $importIndividualFiles = Get-PSFConfigValue -FullName þnameþ.Import.IndividualFiles -Fallback $false
 if ($þnameþ_importIndividualFiles) { $importIndividualFiles = $true }
 if (Test-Path (Resolve-PSFPath -Path "$($script:ModuleRoot)\..\.git" -SingleItem -NewChild)) { $importIndividualFiles = $true }
-if (-not (Test-Path (Resolve-PSFPath "$($script:ModuleRoot)\commands.ps1" -SingleItem -NewChild))) { $importIndividualFiles = $true }
+if ("<was not compiled>" -eq '<was not compiled>') { $importIndividualFiles = $true }
 
 function Import-ModuleFile
 {
@@ -49,6 +49,7 @@ function Import-ModuleFile
 	else { $ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText((Resolve-Path $Path)))), $null, $null) }
 }
 
+#region Load individual files
 if ($importIndividualFiles)
 {
 	# Execute Preimport actions
@@ -68,18 +69,12 @@ if ($importIndividualFiles)
 
 	# Execute Postimport actions
 	. Import-ModuleFile -Path "$ModuleRoot\internal\scripts\postimport.ps1"
-}
-else
-{
-	if (Test-Path (Resolve-PSFPath "$($script:ModuleRoot)\resourcesBefore.ps1" -SingleItem -NewChild))
-	{
-		. Import-ModuleFile -Path "$($script:ModuleRoot)\resourcesBefore.ps1"
-	}
-	
-	. Import-ModuleFile -Path "$($script:ModuleRoot)\commands.ps1"
 
-	if (Test-Path (Resolve-PSFPath "$($script:ModuleRoot)\resourcesAfter.ps1" -SingleItem -NewChild))
-	{
-		. Import-ModuleFile -Path "$($script:ModuleRoot)\resourcesAfter.ps1"
-	}
-}
+	# End it here, do not load compiled code below
+	return
+}
+#endregion Load individual files
+
+#region Load compiled code
+"<compile code into here>"
+#endregion Load compiled code

templates/PSFProject/README.md

@@ -2,4 +2,32 @@
 
 Insert a useful description for the þnameþ project here.
 
-Remember, it's the first thing a visitor will see.
+Remember, it's the first thing a visitor will see.
+
+# Project Setup Instructions
+## Working with the layout
+
+ - Don't touch the psm1 file
+ - Place functions you export in `functions/` (can have subfolders)
+ - Place private/internal functions invisible to the user in `internal/functions` (can have subfolders)
+ - Don't add code directly to the `postimport.ps1` or `preimport.ps1`.
+   Those files are designed to import other files only.
+ - When adding files you load during `preimport.ps1`, be sure to add corresponding entries to `filesBefore.txt`.
+   The text files are used as reference when compiling the module during the build script.
+ - When adding files you load during `postimport.ps1`, be sure to add corresponding entries to `filesAfter.txt`.
+   The text files are used as reference when compiling the module during the build script.
+
+## Setting up CI/CD
+
+> To create a PR validation pipeline, set up tasks like this:
+
+ - Install Prerequisites (PowerShell Task; VSTS-Prerequisites.ps1)
+ - Validate (PowerShell Task; VSTS-Validate.ps1)
+ - Publish Test Results (Publish Test Results; NUnit format; Run no matter what)
+
+> To create a build/publish pipeline, set up tasks like this:
+
+ - Install Prerequisites (PowerShell Task; VSTS-Prerequisites.ps1)
+ - Validate (PowerShell Task; VSTS-Validate.ps1)
+ - Build (PowerShell Task; VSTS-Build.ps1)
+ - Publish Test Results (Publish Test Results; NUnit format; Run no matter what)

templates/PSFProject/build/vsts-build.ps1

@@ -5,27 +5,21 @@ It expects as input an ApiKey authorized to publish the module.
 Insert any build steps you may need to take before publishing it here.
 #>
 param (
-	$ApiKey
+	$ApiKey,
+	
+	$WorkingDirectory = $env:SYSTEM_DEFAULTWORKINGDIRECTORY
 )
 
 # Prepare publish folder
 Write-PSFMessage -Level Important -Message "Creating and populating publishing directory"
-$publishDir = New-Item -Path $env:SYSTEM_DEFAULTWORKINGDIRECTORY -Name publish -ItemType Directory
-Copy-Item -Path "$($env:SYSTEM_DEFAULTWORKINGDIRECTORY)\þnameþ" -Destination $publishDir.FullName -Recurse -Force
+$publishDir = New-Item -Path $WorkingDirectory -Name publish -ItemType Directory
+Copy-Item -Path "$($WorkingDirectory)\þnameþ" -Destination $publishDir.FullName -Recurse -Force
 
-# Create commands.ps1
+#region Gather text data to compile
 $text = @()
-Get-ChildItem -Path "$($publishDir.FullName)\þnameþ\internal\functions\" -Recurse -File -Filter "*.ps1" | ForEach-Object {
-	$text += [System.IO.File]::ReadAllText($_.FullName)
-}
-Get-ChildItem -Path "$($publishDir.FullName)\þnameþ\functions\" -Recurse -File -Filter "*.ps1" | ForEach-Object {
-	$text += [System.IO.File]::ReadAllText($_.FullName)
-}
-$text -join "`n`n" | Set-Content -Path "$($publishDir.FullName)\þnameþ\commands.ps1"
-
-# Create resourcesBefore.ps1
 $processed = @()
-$text = @()
+
+# Gather Stuff to run before
 foreach ($line in (Get-Content "$($PSScriptRoot)\filesBefore.txt" | Where-Object { $_ -notlike "#*" }))
 {
 	if ([string]::IsNullOrWhiteSpace($line)) { continue }
@@ -40,11 +34,16 @@ foreach ($line in (Get-Content "$($PSScriptRoot)\filesBefore.txt" | Where-Object
 		$processed += $item.FullName
 	}
 }
-if ($text) { $text -join "`n`n" | Set-Content -Path "$($publishDir.FullName)\þnameþ\resourcesBefore.ps1" }
 
-# Create resourcesAfter.ps1
-$processed = @()
-$text = @()
+# Gather commands
+Get-ChildItem -Path "$($publishDir.FullName)\þnameþ\internal\functions\" -Recurse -File -Filter "*.ps1" | ForEach-Object {
+	$text += [System.IO.File]::ReadAllText($_.FullName)
+}
+Get-ChildItem -Path "$($publishDir.FullName)\þnameþ\functions\" -Recurse -File -Filter "*.ps1" | ForEach-Object {
+	$text += [System.IO.File]::ReadAllText($_.FullName)
+}
+
+# Gather stuff to run afterwards
 foreach ($line in (Get-Content "$($PSScriptRoot)\filesAfter.txt" | Where-Object { $_ -notlike "#*" }))
 {
 	if ([string]::IsNullOrWhiteSpace($line)) { continue }
@@ -59,7 +58,14 @@ foreach ($line in (Get-Content "$($PSScriptRoot)\filesAfter.txt" | Where-Object
 		$processed += $item.FullName
 	}
 }
-if ($text) { $text -join "`n`n" | Set-Content -Path "$($publishDir.FullName)\þnameþ\resourcesAfter.ps1" }
+#endregion Gather text data to compile
+
+#region Update the psm1 file
+$fileData = Get-Content -Path "$($publishDir.FullName)\þnameþ\þnameþ.psm1" -Raw
+$fileData = $fileData -replace '"<was not compiled>"', '"<was compiled>"'
+$fileData = $fileData -replace '"<compile code into here>"', ($text -join "`n`n")
+[System.IO.File]::WriteAllText("$($publishDir.FullName)\þnameþ\þnameþ.psm1", $fileData, [System.Text.Encoding]::UTF8)
+#endregion Update the psm1 file
 
 # Publish to Gallery
 Publish-Module -Path "$($publishDir.FullName)\þnameþ" -NuGetApiKey $ApiKey -Force

templates/PSFTests/general/Manifest.Tests.ps1

@@ -1,7 +1,6 @@
 Describe "Validating the module manifest" {
 	$moduleRoot = (Resolve-Path "$PSScriptRoot\..\..").Path
 	$manifest = ((Get-Content "$moduleRoot\þnameþ.psd1") -join "`n") | Invoke-Expression
-	[version]$moduleVersion = Get-Item "$moduleRoot\þnameþ.psm1" | Select-String -Pattern '\$script:ModuleVersion = "(.*?)"' | ForEach-Object { $_.Matches[0].Groups[1].Value }
 	Context "Basic resources validation" {
 		$files = Get-ChildItem "$moduleRoot\functions" -Recurse -File -Filter "*.ps1"
 		It "Exports all functions in the public folder" {
@@ -18,10 +17,6 @@
 			$files = Get-ChildItem "$moduleRoot\internal\functions" -Recurse -File -Filter "*.ps1"
 			$files | Where-Object BaseName -In $manifest.FunctionsToExport | Should -BeNullOrEmpty
 		}
-		
-		It "Has the same version as the psm1 file" {
-			([version]$manifest.ModuleVersion) | Should -Be $moduleVersion
-		}
 	}
 
 	Context "Individual file validation" {

templates/PSFTests/pester.ps1

@@ -27,50 +27,56 @@ $totalRun = 0
 $testresults = @()
 
 #region Run General Tests
-Write-PSFMessage -Level Important -Message "Modules imported, proceeding with general tests"
-foreach ($file in (Get-ChildItem "$PSScriptRoot\general" -Filter "*.Tests.ps1"))
+if ($TestGeneral)
 {
-	Write-PSFMessage -Level Significant -Message "  Executing <c='em'>$($file.Name)</c>"
-	þ!testresults!þ
-	foreach ($result in $results)
+	Write-PSFMessage -Level Important -Message "Modules imported, proceeding with general tests"
+	foreach ($file in (Get-ChildItem "$PSScriptRoot\general" -Filter "*.Tests.ps1"))
 	{
-		$totalRun += $result.TotalCount
-		$totalFailed += $result.FailedCount
-		$result.TestResult | Where-Object { -not $_.Passed } | ForEach-Object {
-			$name = $_.Name
-			$testresults += [pscustomobject]@{
-				Describe  = $_.Describe
-				Context   = $_.Context
-				Name	  = "It $name"
-				Result    = $_.Result
-				Message   = $_.FailureMessage
+		Write-PSFMessage -Level Significant -Message "  Executing <c='em'>$($file.Name)</c>"
+		þ!testresults!þ
+		foreach ($result in $results)
+		{
+			$totalRun += $result.TotalCount
+			$totalFailed += $result.FailedCount
+			$result.TestResult | Where-Object { -not $_.Passed } | ForEach-Object {
+				$name = $_.Name
+				$testresults += [pscustomobject]@{
+					Describe = $_.Describe
+					Context  = $_.Context
+					Name	 = "It $name"
+					Result   = $_.Result
+					Message  = $_.FailureMessage
+				}
 			}
 		}
 	}
 }
 #endregion Run General Tests
 
 #region Test Commands
-Write-PSFMessage -Level Important -Message "Proceeding with individual tests"
-foreach ($file in (Get-ChildItem "$PSScriptRoot\functions" -Recurse -File -Filter "*Tests.ps1"))
+if ($TestFunctions)
 {
-	if ($file.Name -notlike $Include) { continue }
-	if ($file.Name -like $Exclude) { continue }
-	
-	Write-PSFMessage -Level Significant -Message "  Executing $($file.Name)"
-	þ!testresults!þ
-	foreach ($result in $results)
+Write-PSFMessage -Level Important -Message "Proceeding with individual tests"
+	foreach ($file in (Get-ChildItem "$PSScriptRoot\functions" -Recurse -File -Filter "*Tests.ps1"))
 	{
-		$totalRun += $result.TotalCount
-		$totalFailed += $result.FailedCount
-		$result.TestResult | Where-Object { -not $_.Passed } | ForEach-Object {
-			$name = $_.Name
-			$testresults += [pscustomobject]@{
-				Describe   = $_.Describe
-				Context    = $_.Context
-				Name	   = "It $name"
-				Result	   = $_.Result
-				Message    = $_.FailureMessage
+		if ($file.Name -notlike $Include) { continue }
+		if ($file.Name -like $Exclude) { continue }
+		
+		Write-PSFMessage -Level Significant -Message "  Executing $($file.Name)"
+		þ!testresults!þ
+		foreach ($result in $results)
+		{
+			$totalRun += $result.TotalCount
+			$totalFailed += $result.FailedCount
+			$result.TestResult | Where-Object { -not $_.Passed } | ForEach-Object {
+				$name = $_.Name
+				$testresults += [pscustomobject]@{
+					Describe = $_.Describe
+					Context  = $_.Context
+					Name	 = "It $name"
+					Result   = $_.Result
+					Message  = $_.FailureMessage
+				}
 			}
 		}
 	}