MetaNull.ModuleMaker.psm1
|
#Requires -Module Microsoft.PowerShell.PSResourceGet # Module Constants Set-Variable INSIDE_MODULEMAKER_MODULE -Scope script -Option Constant -Value $true Function Get-BlueprintResourcePath { <# .SYNOPSIS Get the location of the Module's ResourceDirectory .EXAMPLE $Item = Get-BlueprintResourcePath #> [CmdletBinding()] [OutputType([PSCustomObject])] param( [switch] $Test ) Process { if(-not $Test) { # Running from within an installed module (PSScriptRoot is the path to the module's root directory) Get-Item (Join-Path $PSScriptRoot resource) } else { # Running from within a TEST (thus not from an installed module; PSScriptRoot is the path to the test script itself) Get-Item (Join-Path (Split-Path (Split-Path $PSScriptRoot)) resource) } } } Function New-FunctionBlueprint { <# .SYNOPSIS Create a new function in a module created by ModuleMaker .DESCRIPTION This function creates a new function in a module created by ModuleMaker. It creates a new function in the source directory and a new test file in the test directory. .PARAMETER BlueprintPath The path to the module definition file (Blueprint.psd1). This file is created by New-Module and contains the module's metadata. .PARAMETER Name The name of the new function. This name must be a valid Powershell function name. .PARAMETER Private If this switch is present, the function will be created in the private directory. Otherwise, it will be created in the public directory. .OUTPUTS The path to the module definition file (Blueprint.psd1) is returned. #> [CmdletBinding()] param( [Parameter(Mandatory,ValueFromPipeline)] [ValidateScript({ Test-BlueprintPath -BlueprintPath $_ })] [Alias('Path','DataFile')] [string] $BlueprintPath, [Parameter(Mandatory)] [ValidateScript({ $_ -match '^[a-zA-Z][a-zA-Z0-9\._-]*$' })] [string] $Name, [Parameter(Mandatory=$false)] [switch] $Private ) Process { $BackupErrorActionPreference = $ErrorActionPreference $ErrorActionPreference = 'Stop' try { $DummyName = "Get-Dummy" $ModulePath = $BlueprintPath | Split-Path -Parent $ResourcePath = Get-BlueprintResourcePath $Visibility = if($Private) { 'private' } else { 'public' } $TargetSourceDirectory = Join-Path (Join-Path $ModulePath source) $Visibility -Resolve $TargetTestDirectory = Join-Path (Join-Path $ModulePath test) $Visibility -Resolve $TemplateFunction = Join-Path $ResourcePath "dummy\source\public\$DummyName.ps1" -Resolve $TargetFunction = Join-Path $TargetSourceDirectory "$Name.ps1" Copy-Item -Path $TemplateFunction -Destination $TargetFunction | Out-Null $Content = Get-Content -LiteralPath $TemplateFunction -Raw $Content -replace $DummyName, $Name | Set-Content -LiteralPath $TargetFunction $TemplateTest = Join-Path $ResourcePath "dummy\test\public\$DummyName.Tests.ps1" -Resolve $TargetTest = Join-Path $TargetTestDirectory "$Name.Tests.ps1" Copy-Item -Path $TemplateTest -Destination $TargetTest | Out-Null $Content = Get-Content -LiteralPath $TemplateTest -Raw $Content -replace $DummyName, $Name | Set-Content -LiteralPath $TargetTest } finally { $ErrorActionPreference = $BackupErrorActionPreference } } } Function New-ModuleBlueprint { <# .SYNOPSIS Create an empty Powershell Module .DESCRIPTION Create an empty Powershell Module with the following structure: - ModuleName - Blueprint.psd1 # Contains the module's configuration (automatically generated by New-Module) - Version.psd1 # Contains the module's version (automatically generated during Build) - Build.ps1 # A script that builds the module - Publish.ps1 # A script that publishes the built module to a repository such as PSGallery - source # Contains the module's source code - public # Contains public/exposed functions - Verb-Name.ps1 # Defines the public function "Verb-Name" (e.g.: "Get-Something") - private # Contains private functions (accessible only from within the module) - Verb-Name.ps1 # Defines the private function "Verb-Name" (e.g.: "Invoke-Something") - init # Contains module initialization code - Init.ps1 # Contains module initialization code, such as definition of Constants, etc. - class # Contains .net classes exposed by the module - ClassName.cs # Defines the class "ClassName" - test # Contains the module's tests - public # Contains tests for public/exposed functions - Verb-Name.Tests.ps1 # Contains tests for the public function "Verb-Name" (e.g.: "Get-Something") - private # Contains tests for private functions - Verb-Name.Tests.ps1 # Contains tests for the private function "Verb-Name" (e.g.: "Invoke-Something") - resource # Contains resources contained in the module (e.g. data files that are accessible to the module) .PARAMETER LiteralPath The path to the directory where the module will be created. E.g: $env:TEMP .PARAMETER Name The name of the module. E.g.: MyModule .PARAMETER Description The description of the module. E.g.: "A module that does something" .PARAMETER Uri The URI of the module's documentation or repository. E.g.: "https://www.test.com/mymodule" .PARAMETER Author The author of the module. E.g.: "Pascal Havelange" .PARAMETER Vendor The vendor/company of the authors. E.g.: "MetaNull" .PARAMETER Copyright The copyright statement of the module. E.g.: "(c) 2025" .PARAMETER ModuleDependencies An array of module dependencies. E.g.: @("PackageManagement", "PowerShellGet") The module automatically adds the dependencies to the module's configuration file. .PARAMETER AssemblyDependencies An array of assembly dependencies. E.g.: @("System.Net.WebUtility", "System.Management.Automation.PSCredential") The module automatically adds the dependencies to the module's configuration file. .PARAMETER Force If the module directory already exists, overwrite it. .OUTPUTS Returns a [System.IO.FileInfo] object representing the module's configuration file (Blueprint.psd1) .EXAMPLE # Create a new 'MyModule' module in the $env:TEMP directory $Module = New-Module -Path $env:TEMP -Name MyModule # Create a new public function 'Get-Something' in the module, and a test for it $Module | New-Function -Public -Verb Get -Name Something $Module | Invoke-Build $Module | Invoke-Publish #> [CmdletBinding()] [OutputType([System.IO.FileInfo])] param( [Parameter(Mandatory)] [ValidateScript({ Test-Path -Path $_ -PathType Container })] [Alias('Path')] [string] $LiteralPath, [Parameter(Mandatory)] [ValidateScript({ $_ -match '^[a-zA-Z][a-zA-Z0-9\._-]*$' })] [string] $Name, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $Description = $null, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [ValidateScript({ try { if($null -eq $_ -or [string]::empty -eq $_ -or [System.Uri]::new($_)) { return $true } } catch { # Swallow exception, to permit returninbg $false instead of throwing } return $false })] [string] $Uri = 'https://www.test.com/mymodule', [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $Author = ([System.Security.Principal.WindowsIdentity]::GetCurrent().Name), [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $Vendor = 'Unknown', [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $Copyright = "© $((Get-Date).Year). All rights reserved", [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyCollection()] [string[]] $ModuleDependencies, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyCollection()] [string[]] $AssemblyDependencies, [Parameter(Mandatory = $false)] [switch] $Force ) Process { $BackupErrorActionPreference = $ErrorActionPreference $ErrorActionPreference = 'Stop' try { $NewItemForce = $false $DirectoryPath = Join-Path $LiteralPath $Name if(Test-Path $DirectoryPath -PathType Any) { if($Force.IsPresent -and $Force) { "Target directory $DirectoryPath exists, overwriting." | Write-Warning $NewItemForce = $true } else { throw "Target directory $DirectoryPath exists" } } # Create the directories $RootDirectory = New-Item -Path $LiteralPath -Name $Name -ItemType Directory -Force:$NewItemForce $SourceDirectory = New-Item (Join-Path $RootDirectory source) -ItemType Directory -Force:$NewItemForce $TestDirectory = New-Item (Join-Path $RootDirectory test) -ItemType Directory -Force:$NewItemForce $SourcePublicDirectory = New-Item (Join-Path $SourceDirectory public) -ItemType Directory -Force:$NewItemForce $SourcePrivateDirectory = New-Item (Join-Path $SourceDirectory private) -ItemType Directory -Force:$NewItemForce $SourceInitDirectory = New-Item (Join-Path $SourceDirectory init) -ItemType Directory -Force:$NewItemForce $TestPublicDirectory = New-Item (Join-Path $TestDirectory public) -ItemType Directory -Force:$NewItemForce $TestPrivateDirectory = New-Item (Join-Path $TestDirectory private) -ItemType Directory -Force:$NewItemForce # Create the module's configuration file, script files, and module's sample source and test files if((Get-Variable INSIDE_MODULEMAKER_MODULE -ErrorAction SilentlyContinue)) { #INSIDE_MODULEMAKER_MODULE is a constant defined in the module #If it is set, then the script is run from a loaded module, PSScriptRoot = Directory of the psm1 $ResourceDirectory = Get-Item (Join-Path $PSScriptRoot resource) } else { #Otherwise, the script was probably called from the command line, PSScriptRoot = Directory /source/private $ResourceDirectory = Get-Item (Join-Path (Split-Path (Split-Path $PSScriptRoot)) resource) } Copy-Item $ResourceDirectory\script\*.ps1 $RootDirectory -Force:$NewItemForce Copy-Item $ResourceDirectory\data\*.psd1 $RootDirectory -Force:$NewItemForce # For the dummy files, -Force is always enabled, as it overwrites existing directories source and test Copy-Item -Path $ResourceDirectory\dummy\* -Destination $RootDirectory -Recurse -Force # Update Module's configuration $ManifestFile = Get-Item (Join-Path $RootDirectory Blueprint.psd1) $ManifestFileContent = Get-Content -LiteralPath $ManifestFile $Replace = @{ '%%MODULE_GUID%%'= (New-Guid) '%%MODULE_NAME%%' = "$Name" '%%MODULE_DESCRIPTION%%' = "$Description" '%%MODULE_URI%%' = "$Uri" '%%MODULE_AUTHOR%%' = "$Author" '%%MODULE_VENDOR%%'= "$Vendor" '%%MODULE_COPYRIGHT%%' = "$Copyright" "%%ASSEMBLY_DEPENDENCIES%%" = $null "%%MODULE_DEPENDENCIES%%" = $null } if($AssemblyDependencies) { $Replace.'%%ASSEMBLY_DEPENDENCIES%%' = "'$($AssemblyDependencies -join "','")'" } if($ModuleDependencies) { $Replace.'"%%MODULE_DEPENDENCIES%%"' = "'$($ModuleDependencies -join "','")'" } $Replace.GetEnumerator() | Foreach-Object { if($_.Value) { $ManifestFileContent = $ManifestFileContent -replace "$($_.Key)","$($_.Value)" } else { $ManifestFileContent = $ManifestFileContent -replace "$($_.Key)" } } $ManifestFileContent | Set-Content -LiteralPath $ManifestFile -Force:$NewItemForce $ManifestFile | Write-Output } finally { $ErrorActionPreference = $BackupErrorActionPreference } } } Function Test-BlueprintPath { [CmdletBinding()] param( [Parameter(Mandatory = $false)] [AllowEmptyString()] [AllowNull()] [Alias('Path','DataFile')] [string] $BlueprintPath ) End { $EAB = $ErrorActionPreference $ErrorActionPreference = 'Stop' try { if(-not $BlueprintPath) { throw "Blueprint path is null, empty or not provided" } if(-not (Test-Path -Path $BlueprintPath -PathType Leaf)) { throw "Blueprint file does not exist or is not a file, for path: $BlueprintPath" } $BlueprintPath = Resolve-Path $BlueprintPath if(-not ((Split-Path $BlueprintPath -Leaf) -eq 'Blueprint.psd1' )) { throw "Blueprint filename is not compliant (expecting Blueprint.psd1), for path: $BlueprintPath" } Write-Debug "Importing Blueprint from: $BlueprintPath" $ModuleDefinition = Import-PowerShellDataFile -Path $BlueprintPath if($null -eq $ModuleDefinition.Name -or $null -eq $ModuleDefinition.ModuleSettings -or $null -eq $ModuleDefinition.ModuleSettings.GUID) { throw "Blueprint is invalid: `$_.Name or `$_.GUID are missing" } if($ModuleDefinition.Name -eq '%%MODULE_NAME%%' -or $ModuleDefinition.ModuleSettings.GUID -eq '%%MODULE_GUID%%') { throw "Blueprint is invalid: `$_.Name or `$_.GUID are not initialized" } if($ModuleDefinition.Name -eq [string]::empty -or $ModuleDefinition.ModuleSettings.GUID -eq [string]::empty) { throw "Blueprint is invalid: `$_.Name or `$_.GUID are empty" } $ModulePath = $BlueprintPath | Split-Path -Parent if(-not (Test-Path -Path (Join-Path $ModulePath source) -PathType Container)) { throw "Module source directory does not exist" } if(-not (Test-Path -Path (Join-Path $ModulePath test) -PathType Container)) { throw "Module test directory does not exist" } if(-not (Test-Path -Path (Join-Path $ModulePath Build.ps1) -PathType Leaf)) { throw "Module's Build script does not exist" } if(-not (Test-Path -Path (Join-Path $ModulePath Publish.ps1) -PathType Leaf)) { throw "Module's Publish script does not exist" } return $true } catch { Write-Verbose "$($_.Exception.Message)" # Swallow exception, to permit returninbg $false instead of throwing } finally { $ErrorActionPreference = $EAB } return $false } } |