Merge pull request #64 from PowershellFrameworkCollective/development

FriedrichWeinmann · web-flow · commit a1954b196795 · 2018-10-20T08:29:02.000+02:00
2.2.5.37
diff --git a/PSModuleDevelopment/PSModuleDevelopment.psd1 b/PSModuleDevelopment/PSModuleDevelopment.psd1
@@ -4,7 +4,7 @@
 	RootModule = 'PSModuleDevelopment.psm1'
 	
 	# Version number of this module.
-	ModuleVersion = '2.2.5.31'
+	ModuleVersion = '2.2.5.37'
 	
 	# ID used to uniquely identify this module
 	GUID = '37dd5fce-e7b5-4d57-ac37-832055ce49d6'
diff --git a/PSModuleDevelopment/PSModuleDevelopment.psm1 b/PSModuleDevelopment/PSModuleDevelopment.psm1
@@ -1,5 +1,5 @@
 ﻿$script:PSModuleRoot = $PSScriptRoot
-$script:PSModuleVersion = "2.2.5.31"
+$script:PSModuleVersion = "2.2.5.37"
 
 $script:doDotSource = $false
 if (Get-PSFConfigValue -FullName PSModuleDevelopment.Import.DoDotSource) { $script:doDotSource = $true }
diff --git a/PSModuleDevelopment/changelog.md b/PSModuleDevelopment/changelog.md
@@ -1,4 +1,12 @@
 ﻿# Changelog
+## 2.2.5.37 ( October 20th, 2018)
+ - Upd: Set-PSMDModulePath - add `-Module` parameter to persist the setting
+ - Upd: Set-PSMDModulePath - add `-Register` parameter for integrated persistence
+ - 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
  
diff --git a/PSModuleDevelopment/functions/refactor/Set-PSMDEncoding.ps1 b/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
diff --git a/PSModuleDevelopment/functions/utility/Set-PSMDModulePath.ps1 b/PSModuleDevelopment/functions/utility/Set-PSMDModulePath.ps1
@@ -1,56 +1,80 @@
 ﻿function Set-PSMDModulePath
 {
-	<#
-		.SYNOPSIS
-			Sets the path of the module currently being developed.
-		
-		.DESCRIPTION
-			Sets the path of the module currently being developed.
-			This is used by several utility commands in order to not require any path input.
+<#
+	.SYNOPSIS
+		Sets the path of the module currently being developed.
 	
-			This is a wrapper around the psframework configuration system, the same action can be taken by running this command:
-			Set-PSFConfig -Module PSModuleDevelopment -Name "Module.Path" -Value $Path
-		
-		.PARAMETER Path
-			The path to set as currently developed module.
+	.DESCRIPTION
+		Sets the path of the module currently being developed.
+		This is used by several utility commands in order to not require any path input.
 		
-		.PARAMETER EnableException
-            Replaces user friendly yellow warnings with bloody red exceptions of doom!
-            Use this if you want the function to throw terminating errors you want to catch.
-		
-		.EXAMPLE
-			Set-PSMDModulePath -Path "C:\github\dbatools"
+		This is a wrapper around the psframework configuration system, the same action can be taken by running this command:
+		Set-PSFConfig -Module PSModuleDevelopment -Name "Module.Path" -Value $Path
+	
+	.PARAMETER Module
+		The module, the path of which to register.
 	
-			Sets the current module path to "C:\github\dbatools"
+	.PARAMETER Path
+		The path to set as currently developed module.
 	
-		.EXAMPLE
-			Set-PSMDModulePath -Path "C:\github\dbatools"
-			Register-PSFConfig -FullName 'PSModuleDevelopment.Module.Path'
+	.PARAMETER Register
+		Register the specified path, to have it persist across sessions
+	
+	.PARAMETER EnableException
+		Replaces user friendly yellow warnings with bloody red exceptions of doom!
+		Use this if you want the function to throw terminating errors you want to catch.
+	
+	.EXAMPLE
+		Set-PSMDModulePath -Path "C:\github\dbatools"
+		
+		Sets the current module path to "C:\github\dbatools"
 	
-			Sets the current module path to "C:\github\dbatools"
-			Then stores the setting in registry, causing it to be persisted acros multiple sessions.
-	#>
+	.EXAMPLE
+		Set-PSMDModulePath -Path "C:\github\dbatools" -Register
+		
+		Sets the current module path to "C:\github\dbatools"
+		Then stores the setting in registry, causing it to be persisted acros multiple sessions.
+#>
 	[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
 	[CmdletBinding()]
-	Param (
-		[Parameter(Mandatory = $true)]
+	param (
+		[Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'Module')]
+		[System.Management.Automation.PSModuleInfo]
+		$Module,
+		
+		[Parameter(Mandatory = $true, ParameterSetName = 'Path')]
 		[string]
 		$Path,
 		
+		[switch]
+		$Register,
+		
 		[switch]
 		$EnableException
 	)
 	
-	$resolvedPath = Resolve-Path -Path $Path
-	if (Test-Path -Path $resolvedPath)
+	process
 	{
-		if ((Get-Item $resolvedPath).PSIsContainer)
+		if ($Path)
 		{
-			Set-PSFConfig -Module PSModuleDevelopment -Name "Module.Path" -Value $resolvedPath
+			$resolvedPath = Resolve-PSFPath -Path $Path -Provider FileSystem -SingleItem
+			if (Test-Path -Path $resolvedPath)
+			{
+				if ((Get-Item $resolvedPath).PSIsContainer)
+				{
+					Set-PSFConfig -Module PSModuleDevelopment -Name "Module.Path" -Value $resolvedPath
+					if ($Register) { Register-PSFConfig -Module 'PSModuleDevelopment' -Name 'Module.Path' }
+					return
+				}
+			}
+			
+			Stop-PSFFunction -Target $Path -Message "Could not validate/resolve path: $Path" -EnableException $EnableException -Category InvalidArgument
 			return
 		}
+		else
+		{
+			Set-PSFConfig -Module PSModuleDevelopment -Name "Module.Path" -Value $Module.ModuleBase
+			if ($Register) { Register-PSFConfig -Module 'PSModuleDevelopment' -Name 'Module.Path' }
+		}
 	}
-	
-	Stop-PSFFunction -Target $Path -Message "Could not validate/resolve path: $Path" -EnableException $EnableException -Category InvalidArgument
-	return
 }
diff --git a/PSModuleDevelopment/internal/tabcompletion/assignment.ps1 b/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
diff --git a/templates/CommandTest/þnameþ.Tests.ps1 b/templates/CommandTest/þnameþ.Tests.ps1
@@ -16,7 +16,7 @@
 			$commonParameters = 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'Confirm', 'WhatIf'
 			foreach ($parameter in ((Get-Command $Parameters.Name).Parameters.Values | Where-Object Name -NotIn $commonParameters))
 			{
-				$lines += "		It 'Should habe the expected parameter $($parameter.Name)' {"
+				$lines += "		It 'Should have the expected parameter $($parameter.Name)' {"
 				$lines += "			`$parameter = (Get-Command $($Parameters.Name)).Parameters['$($parameter.Name)']"
 				$lines += "			`$parameter.Name | Should -Be '$($parameter.Name)'"
 				$lines += "			`$parameter.ParameterType.ToString() | Should -Be $($parameter.ParameterType.ToString())"
diff --git a/templates/PSFModule/þnameþ.psd1 b/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!þ'
diff --git a/templates/PSFModule/þnameþ.psm1 b/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
diff --git a/templates/PSFProject/README.md b/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)
diff --git a/templates/PSFProject/build/filesAfter.txt b/templates/PSFProject/build/filesAfter.txt
@@ -1,5 +1,5 @@
-﻿# List all files that are loaded in the preimport.ps1
-# In the order they are loaded during preimport
+﻿# List all files that are loaded in the postimport.ps1
+# In the order they are loaded during postimport
 
 internal\configurations\*.ps1
 internal\tepp\*.tepp.ps1
diff --git a/templates/PSFProject/build/filesBefore.txt b/templates/PSFProject/build/filesBefore.txt
@@ -1,2 +1,2 @@
-# List all files that are loaded in the postimport.ps1
-# In the order they are loaded during postimport
+# List all files that are loaded in the preimport.ps1
+# In the order they are loaded during preimport
diff --git a/templates/PSFProject/build/vsts-build.ps1 b/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
diff --git a/templates/PSFProject/þnameþ/internal/scripts/postimport.ps1 b/templates/PSFProject/þnameþ/internal/scripts/postimport.ps1
@@ -1,4 +1,5 @@
 ﻿# Add all things you want to run after importing the main code
+# If you add entries to this file, you aslo need to edit the .\build\filesAfter.txt
 
 # Load Configurations
 foreach ($file in (Get-ChildItem "$ModuleRoot\internal\configurations\*.ps1" -ErrorAction Ignore)) {
diff --git a/templates/PSFProject/þnameþ/internal/scripts/preimport.ps1 b/templates/PSFProject/þnameþ/internal/scripts/preimport.ps1
@@ -1 +1,2 @@
-﻿# Add all things you want to run before importing the main code
+﻿# Add all things you want to run before importing the main code
+# If you add entries to this file, you also need to edit the .\build\filesBefore.txt
diff --git a/templates/PSFTests/general/Manifest.Tests.ps1 b/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" {
diff --git a/templates/PSFTests/pester.ps1 b/templates/PSFTests/pester.ps1

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@`
`16`	`16`	`$commonParameters = 'Verbose', 'Debug', 'ErrorAction', 'WarningAction', 'InformationAction', 'ErrorVariable', 'WarningVariable', 'InformationVariable', 'OutVariable', 'OutBuffer', 'PipelineVariable', 'Confirm', 'WhatIf'`
`17`	`17`	`foreach ($parameter in ((Get-Command $Parameters.Name).Parameters.Values \| Where-Object Name -NotIn $commonParameters))`
`18`	`18`	`{`
`19`		`- $lines += " It 'Should habe the expected parameter $($parameter.Name)' {"`
	`19`	`+ $lines += " It 'Should have the expected parameter $($parameter.Name)' {"`
`20`	`20`	$lines += " `$parameter = (Get-Command $($Parameters.Name)).Parameters['$($parameter.Name)']"
`21`	`21`	$lines += " `$parameter.Name \| Should -Be '$($parameter.Name)'"
`22`	`22`	$lines += " `$parameter.ParameterType.ToString() \| Should -Be $($parameter.ParameterType.ToString())"