Merge pull request #51 from PowershellFrameworkCollective/template-update

Template update

Author: FriedrichWeinmann

PSModuleDevelopment/changelog.md

@@ -1,6 +1,7 @@
 # Changelog
-## 2.2.5.29
+## 2.2.5.30
  - Upd: Template integrated NUnit Test Reporting
+ - Upd: Template support for compiled module files
 
 ## 2.2.5.28 (September 08th, 2018)
  - Fix: Template CommandTest would throw an exception due to missing quotes on a string index

build/vsts-prerequisites.ps1

@@ -1,4 +1,6 @@
 Write-Host "Installing Pester" -ForegroundColor Cyan
 Install-Module Pester -Force -SkipPublisherCheck
+Write-Host "Installing PSScriptAnalyzer" -ForegroundColor Cyan
+Install-Module PSScriptAnalyzer -Force -SkipPublisherCheck
 Write-Host "Installing PSFramework" -ForegroundColor Cyan
 Install-Module PSFramework -Force -SkipPublisherCheck

templates/PSFModule/internal/configurations/configuration.ps1

@@ -9,4 +9,7 @@ feel totally free to split them into multiple files.
 <#
 # Example Configuration
 Set-PSFConfig -Module 'þnameþ' -Name 'Example.Setting' -Value 10 -Initialize -Validation 'integer' -Handler { } -Description "Example configuration setting. Your module can then use the setting using 'Get-PSFConfigValue'"
-#>
+#>
+
+Set-PSFConfig -Module 'þnameþ' -Name 'Import.DoDotSource' -Value $false -Initialize -Validation 'bool' -Description "Whether the module files should be dotsourced on import. By default, the files of this module are read as string value and invoked, which is faster but worse on debugging."
+Set-PSFConfig -Module 'þnameþ' -Name 'Import.IndividualFiles' -Value $false -Initialize -Validation 'bool' -Description "Whether the module files should be imported individually. During the module build, all module code is compiled into few files, which are imported instead by default. Loading the compiled versions is faster, using the individual files is easier for debugging and testing out adjustments."

templates/PSFModule/readme.md

@@ -0,0 +1,17 @@
+# PSFModule guidance
+
+This is a finished module layout optimized for implementing the PSFramework.
+
+If you don't care to deal with the details, this is what you need to do to get started seeing results:
+
+ - Add the functions you want to publish to `/functions/`
+ - Update the `FunctionsToExport` node in the module manifest (þnameþ.psd1). All functions you want to publish should be in a list.
+ - Add internal helper functions the user should not see to `/internal/functions/`
+ 
+ ## Path Warning
+ 
+ > If you want your module to be compatible with Linux and MacOS, keep in mind that those OS are case sensitive for paths and files.
+ 
+ `Import-ModuleFile` is preconfigured to resolve the path of the files specified, so it will reliably convert weird path notations the system can't handle.
+ Content imported through that command thus need not mind the path separator.
+ If you want to make sure your code too will survive OS-specific path notations, get used to using `Resolve-path` or the more powerful `Resolve-PSFPath`.

templates/PSFModule/þnameþ.psm1

@@ -1,6 +1,24 @@
 $script:ModuleRoot = $PSScriptRoot
 $script:ModuleVersion = "1.0.0.0"
 
+# Detect whether at some level dotsourcing was enforced
+$script:doDotSource = Get-PSFConfigValue -FullName þnameþ.Import.DoDotSource -Fallback $false
+if ($þnameþ_dotsourcemodule) { $script:doDotSource = $true }
+
+<#
+Note on Resolve-Path:
+All paths are sent through Resolve-Path/Resolve-PSFPath in order to convert them to the correct path separator.
+This allows ignoring path separators throughout the import sequence, which could otherwise cause trouble depending on OS.
+Resolve-Path can only be used for paths that already exist, Resolve-PSFPath can accept that the last leaf my not exist.
+This is important when testing for paths.
+#>
+
+# Detect whether at some level loading individual module files, rather than the compiled module was enforced
+$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 }
+	
 function Import-ModuleFile
 {
 	<#
@@ -31,24 +49,37 @@ function Import-ModuleFile
 	else { $ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText((Resolve-Path $Path)))), $null, $null) }
 }
 
-# Detect whether at some level dotsourcing was enforced
-$script:doDotSource = Get-PSFConfigValue -FullName þnameþ.Import.DoDotSource -Fallback $false
-if ($þnameþ_dotsourcemodule) { $script:doDotSource = $true }
-
-# Execute Preimport actions
-. Import-ModuleFile -Path "$ModuleRoot\internal\scripts\preimport.ps1"
-
-# Import all internal functions
-foreach ($function in (Get-ChildItem "$ModuleRoot\internal\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore))
+if ($importIndividualFiles)
 {
-	. Import-ModuleFile -Path $function.FullName
+	# Execute Preimport actions
+	. Import-ModuleFile -Path "$ModuleRoot\internal\scripts\preimport.ps1"
+	
+	# Import all internal functions
+	foreach ($function in (Get-ChildItem "$ModuleRoot\internal\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore))
+	{
+		. Import-ModuleFile -Path $function.FullName
+	}
+	
+	# Import all public functions
+	foreach ($function in (Get-ChildItem "$ModuleRoot\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore))
+	{
+		. Import-ModuleFile -Path $function.FullName
+	}
+	
+	# Execute Postimport actions
+	. Import-ModuleFile -Path "$ModuleRoot\internal\scripts\postimport.ps1"
 }
-
-# Import all public functions
-foreach ($function in (Get-ChildItem "$ModuleRoot\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore))
+else
 {
-	. Import-ModuleFile -Path $function.FullName
-}
-
-# Execute Postimport actions
-. Import-ModuleFile -Path "$ModuleRoot\internal\scripts\postimport.ps1"
+	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"
+	}
+}

templates/PSFProject/.gitignore

@@ -16,4 +16,7 @@ library/þnameþ/þnameþ/obj/*
 þnameþ/þnameþ.psproj
 
 # ignore the TestResults
-TestResults/*
+TestResults/*
+
+# ignore the publishing Directory
+publish/*

templates/PSFProject/build/filesAfter.txt

@@ -0,0 +1,7 @@
+# List all files that are loaded in the preimport.ps1
+# In the order they are loaded during preimport
+
+internal\configurations\*.ps1
+internal\tepp\*.tepp.ps1
+internal\tepp\assignment.ps1
+internal\scripts\license.ps1

templates/PSFProject/build/filesBefore.txt

@@ -0,0 +1,2 @@
+# List all files that are loaded in the postimport.ps1
+# In the order they are loaded during postimport

templates/PSFProject/build/vsts-build.ps1

@@ -5,9 +5,61 @@ 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,
-	$WhatIf
+	$ApiKey
 )
 
-if ($WhatIf) { Publish-Module -Path "$($env:SYSTEM_DEFAULTWORKINGDIRECTORY)\þnameþ" -NuGetApiKey $ApiKey -Force -WhatIf }
-else { Publish-Module -Path "$($env:SYSTEM_DEFAULTWORKINGDIRECTORY)\þnameþ" -NuGetApiKey $ApiKey -Force }
+# 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
+
+# Create commands.ps1
+$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 = @()
+foreach ($line in (Get-Content "$($PSScriptRoot)\filesBefore.txt" | Where-Object { $_ -notlike "#*" }))
+{
+	if ([string]::IsNullOrWhiteSpace($line)) { continue }
+	
+	$basePath = Join-Path "$($publishDir.FullName)\þnameþ" $line
+	foreach ($entry in (Resolve-PSFPath -Path $basePath))
+	{
+		$item = Get-Item $entry
+		if ($item.PSIsContainer) { continue }
+		if ($item.FullName -in $processed) { continue }
+		$text += [System.IO.File]::ReadAllText($item.FullName)
+		$processed += $item.FullName
+	}
+}
+if ($text) { $text -join "`n`n" | Set-Content -Path "$($publishDir.FullName)\þnameþ\resourcesBefore.ps1" }
+
+# Create resourcesAfter.ps1
+$processed = @()
+$text = @()
+foreach ($line in (Get-Content "$($PSScriptRoot)\filesAfter.txt" | Where-Object { $_ -notlike "#*" }))
+{
+	if ([string]::IsNullOrWhiteSpace($line)) { continue }
+	
+	$basePath = Join-Path "$($publishDir.FullName)\þnameþ" $line
+	foreach ($entry in (Resolve-PSFPath -Path $basePath))
+	{
+		$item = Get-Item $entry
+		if ($item.PSIsContainer) { continue }
+		if ($item.FullName -in $processed) { continue }
+		$text += [System.IO.File]::ReadAllText($item.FullName)
+		$processed += $item.FullName
+	}
+}
+if ($text) { $text -join "`n`n" | Set-Content -Path "$($publishDir.FullName)\þnameþ\resourcesAfter.ps1" }
+
+# Publish to Gallery
+Publish-Module -Path "$($publishDir.FullName)\þnameþ" -NuGetApiKey $ApiKey -Force

templates/PSFTests/general/FileIntegrity.Tests.ps1

@@ -28,7 +28,7 @@ function Get-FileEncoding
 	elseif ($byte[0] -eq 0xfe -and $byte[1] -eq 0xff) { 'Unicode' }
 	elseif ($byte[0] -eq 0 -and $byte[1] -eq 0 -and $byte[2] -eq 0xfe -and $byte[3] -eq 0xff) { 'UTF32' }
 	elseif ($byte[0] -eq 0x2b -and $byte[1] -eq 0x2f -and $byte[2] -eq 0x76) { 'UTF7' }
-	else { 'Unknown, possible ASCII' }
+	else { 'Unknown' }
 }
 
 Describe "Verifying integrity of module files" {