functions/templating/New-PSMDTemplate.ps1
|
function New-PSMDTemplate { <# .SYNOPSIS Creates a template from a reference file / folder. .DESCRIPTION This function creates a template based on an existing folder or file. It automatically detects parameters that should be filled in one creation time. # Template reference: # #---------------------# Project templates can be preconfigured by a special reference file in the folder root. This file must be named "PSMDTemplate.ps1" and will not be part of the template. It must emit a single hashtable with various pieces of information. This hashtable can have any number of the following values, in any desired combination: - Scripts: A Hashtable, of scriptblocks. These are scripts used for replacement parameters, the key is the name used on insertions. - TemplateName: Name of the template - Version: The version number for the template (See AutoIncrementVersion property) - AutoIncrementVersion: Whether the version number should be incremented - Tags: Tags to add to a template - makes searching and finding templates easier - Author: Name of the author of the template - Description: Description of the template - Exclusions: List of relative file/folder names to not process / skip. Each of those entries can also be overridden by specifying the corresponding parameter of this function. # Parameterizing templates: # #---------------------------# The script will pick up any parameter found in the files and folders (including the file/folder name itself). There are three ways to do this: - Named text replacement: The user will need to specify what to insert into this when creating a new project from this template. - Scriptblock replacement: The included scriptblock will be executed on initialization, in order to provide a text to insert. Duplicate scriptblocks will be merged. - Named scriptblock replacement: The template reference file can define scriptblocks, their value will be inserted here. The same name can be reused any number of times across the entire project, it will always receive the same input. Naming Rules: - Parameter names cannot include the characters '!', '{', or '}' - Parameter names cannot include the parameter identifier. This is by default 'þ'. This identifier can be changed by updating the 'psmoduledevelopment.template.identifier' configuration setting. - Names are not case sensitive. Examples: ° Named for replacement: "Test þnameþ" --> "Test <inserted text of parameter>" ° Scriptblock replacement: "Test þ{ $env:COMPUTERNAME }þ" --> "Test <Name of invoking computer>" - Important: No space between identifier and curly braces! - Scriptblock can have multiple lines. ° Named Scriptblock replacement: "Test þ!ClosestDomainController!þ" --> "Test <Result of script ClosestDomainController>" - Named Scriptblocks are created by using a template reference file (see section above) .PARAMETER ReferencePath Root path in which all files are selected for creating a template project. The folder will not be part of the template, only its content. .PARAMETER FilePath Path to a single file. Used to create a template for that single file, instead of a full-blown project. Note: Does not support template reference files. .PARAMETER TemplateName Name of the template. .PARAMETER Filter Only files matching this filter will be included in the template. .PARAMETER OutStore Where the template will be stored at. By default, it will push the template to the default store (A folder in appdata unless configuration was changed). .PARAMETER OutPath If the template should be written to a specific path instead. Specify a folder. .PARAMETER Exclusions The relative path of the files or folders to ignore. Ignoring folders will also ignore all items in the folder. .PARAMETER Version The version of the template. .PARAMETER Author The author of the template. .PARAMETER Description A description text for the template itself. This will be visible to the user before invoking the template and should describe what this template is for. .PARAMETER Tags Tags to apply to the template, making it easier to filter & search. .PARAMETER Force If the template in the specified version in the specified destination already exists, this will fail unless the Force parameter is used. .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 PS C:\> New-PSMDTemplate -FilePath .\þnameþ.Test.ps1 -TemplateName functiontest Creates a new template named 'functiontest', based on the content of '.\þnameþ.Test.ps1' #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")] [CmdletBinding(DefaultParameterSetName = 'Project')] param ( [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'Project')] [string] $ReferencePath, [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'File')] [string] $FilePath, [Parameter(Position = 1, ParameterSetName = 'Project')] [Parameter(Position = 1, ParameterSetName = 'File', Mandatory = $true)] [string] $TemplateName, [string] $Filter = "*", [string] $OutStore = "Default", [string] $OutPath, [string[]] $Exclusions, [version] $Version = "1.0.0.0", [string] $Description, [string] $Author = (Get-PSFConfigValue -FullName 'PSModuleDevelopment.Template.ParameterDefault.Author' -Fallback $env:USERNAME), [string[]] $Tags, [switch] $Force, [switch] $EnableException ) begin { Write-PSFMessage -Level InternalComment -Message "Bound parameters: $($PSBoundParameters.Keys -join ", ")" -Tag 'debug', 'start', 'param' #region Insert basic meta-data $identifier = [regex]::Escape(( Get-PSFConfigValue -FullName 'psmoduledevelopment.template.identifier' -Fallback 'þ' )) $binaryExtensions = Get-PSFConfigValue -FullName 'PSModuleDevelopment.Template.BinaryExtensions' -Fallback @('.dll', '.exe', '.pdf', '.doc', '.docx', '.xls', '.xlsx') $template = New-Object PSModuleDevelopment.Template.Template $template.Name = $TemplateName $template.Version = $Version $template.Tags = $Tags $template.Description = $Description $template.Author = $Author if ($PSCmdlet.ParameterSetName -eq 'File') { $template.Type = 'File' } else { $template.Type = 'Project' $processedReferencePath = Resolve-Path $ReferencePath if (Test-Path (Join-Path $processedReferencePath "PSMDTemplate.ps1")) { $templateData = & (Join-Path $processedReferencePath "PSMDTemplate.ps1") foreach ($key in $templateData.Scripts.Keys) { $template.Scripts[$key] = New-Object PSModuleDevelopment.Template.ParameterScript($key, $templateData.Scripts[$key]) } if ($templateData.TemplateName -and (Test-PSFParameterBinding -ParameterName TemplateName -Not)) { $template.Name = $templateData.TemplateName } if ($templateData.Version -and (Test-PSFParameterBinding -ParameterName Version -Not)) { $template.Version = $templateData.Version } if ($templateData.Tags -and (Test-PSFParameterBinding -ParameterName Tags -Not)) { $template.Tags = $templateData.Tags } if ($templateData.Description -and (Test-PSFParameterBinding -ParameterName Description -Not)) { $template.Description = $templateData.Description } if ($templateData.Author -and (Test-PSFParameterBinding -ParameterName Author -Not)) { $template.Author = $templateData.Author } if (-not $template.Name) { Stop-PSFFunction -Message "No template name detected: Make sure to specify it as parameter or include it in the 'PSMDTemplate.ps1' definition file!" -EnableException $EnableException return } if ($templateData.AutoIncrementVersion) { $oldTemplate = Get-PSMDTemplate -TemplateName $template.Name -WarningAction SilentlyContinue | Sort-Object Version | Select-Object -First 1 if (($oldTemplate) -and ($oldTemplate.Version -ge $template.Version)) { $major = $oldTemplate.Version.Major $minor = $oldTemplate.Version.Minor $revision = $oldTemplate.Version.Revision $build = $oldTemplate.Version.Build # Increment lowest element if ($build -ge 0) { $build++ } elseif ($revision -ge 0) { $revision++ } elseif ($minor -ge 0) { $minor++ } else { $major++ } $template.Version = "$($major).$($minor).$($revision).$($build)" -replace "\.-1",'' } } if ($templateData.Exclusions -and (Test-PSFParameterBinding -ParameterName Exclusions -Not)) { $Exclusions = $templateData.Exclusions } } if ($Exclusions) { $oldExclusions = $Exclusions $Exclusions = @() foreach ($exclusion in $oldExclusions) { $Exclusions += Join-Path $processedReferencePath $exclusion } } } #endregion Insert basic meta-data #region Validation #region Validate FilePath if ($FilePath) { if (-not (Test-Path $FilePath -PathType Leaf)) { Stop-PSFFunction -Message "Filepath $FilePath is invalid. Ensure it exists and is a file" -EnableException $EnableException -Category InvalidArgument -Tag 'fail', 'argument', 'path' return } } #endregion Validate FilePath #region Validate & ensure output folder $fileName = "$($template.Name)-$($template.Version).xml" $infoFileName = "$($template.Name)-$($template.Version)-Info.xml" if ($OutPath) { $exportFolder = $OutPath } else { $exportFolder = Get-PsmdTemplateStore -Filter $OutStore | Select-Object -ExpandProperty Path -First 1 } if (-not $exportFolder) { Stop-PSFFunction -Message "Unable to resolve a path to create the template in. Verify a valid template store or path were specified." -Category InvalidArgument -EnableException $EnableException -Tag 'fail', 'argument', 'path' return } if (-not (Test-Path $exportFolder)) { if ($Force) { try { $null = New-Item -Path $exportFolder -ItemType Directory -Force -ErrorAction Stop } catch { Stop-PSFFunction -Message "Failed to create output path: $exportFolder" -ErrorRecord $_ -Tag 'fail', 'folder', 'create' -EnableException $EnableException return } } else { Stop-PSFFunction -Message "Output folder does not exist. Use '-Force' to have this function automatically create it: $exportFolder" -Category InvalidArgument -EnableException $EnableException -Tag 'fail', 'argument', 'path' return } } if ((Test-Path (Join-Path $exportFolder $fileName)) -and (-not $Force)) { Stop-PSFFunction -Message "Template already exists in the current version. Use '-Force' if you want to overwrite it!" -Category InvalidArgument -EnableException $EnableException -Tag 'fail', 'argument', 'path' return } #endregion Validate & ensure output folder #endregion Validation #region Utility functions function Convert-Item { [CmdletBinding()] param ( [System.IO.FileSystemInfo] $Item, [PSModuleDevelopment.Template.TemplateItemBase] $Parent, [string] $Filter, [string[]] $Exclusions, [PSModuleDevelopment.Template.Template] $Template, [string] $ReferencePath, [string] $Identifier, [string[]] $BinaryExtensions ) if ($Item.FullName -in $Exclusions) { return } #region Regex <# Fixed string Replacement pattern: "$($Identifier)([^{}!]+?)$($Identifier)" Named script replacement pattern: "$($Identifier)!([^{}!]+?)!$($Identifier)" Live script replacement pattern: "$($Identifier){(.+?)}$($Identifier)" Chained together in a logical or, in order to avoid combination issues. #> $pattern = "$($Identifier)([^{}!]+?)$($Identifier)|$($Identifier)!([^{}!]+?)!$($Identifier)|(?ms)$($Identifier){(.+?)}$($Identifier)" #endregion Regex $name = $Item.Name $relativePath = "" if ($ReferencePath) { $relativePath = ($Item.FullName -replace "^$([regex]::Escape($ReferencePath))","").Trim("\") } #region Folder if ($Item.GetType().Name -eq "DirectoryInfo") { $object = New-Object PSModuleDevelopment.Template.TemplateItemFolder $object.Name = $name $object.RelativePath = $relativePath foreach ($find in ([regex]::Matches($name, $pattern, 'IgnoreCase'))) { #region Fixed string replacement if ($find.Groups[1].Success) { if ($object.FileSystemParameterFlat -notcontains $find.Groups[1].Value) { $null = $object.FileSystemParameterFlat.Add($find.Groups[1].Value) } if ($Template.Parameters -notcontains $find.Groups[1].Value) { $null = $Template.Parameters.Add($find.Groups[1].Value) } } #endregion Fixed string replacement #region Named Scriptblock replacement if ($find.Groups[2].Success) { $scriptName = $find.Groups[2].Value if ($Template.Scripts.Keys -eq $scriptName) { $object.FileSystemParameterScript($scriptName) } else { throw "Unknown named scriptblock '$($scriptName)' in name of '$($Item.FullName)'. Make sure the named scriptblock exists in the configuration file." } } #endregion Named Scriptblock replacement } foreach ($child in (Get-ChildItem -Path $Item.FullName -Filter $Filter)) { $paramConvertItem = @{ Item = $child Filter = $Filter Exclusions = $Exclusions Template = $Template ReferencePath = $ReferencePath Identifier = $Identifier BinaryExtensions = $BinaryExtensions Parent = $object } Convert-Item @paramConvertItem } } #endregion Folder #region File else { $object = New-Object PSModuleDevelopment.Template.TemplateItemFile $object.Name = $name $object.RelativePath = $relativePath #region File Name foreach ($find in ([regex]::Matches($name, $pattern, 'IgnoreCase'))) { #region Fixed string replacement if ($find.Groups[1].Success) { if ($object.FileSystemParameterFlat -notcontains $find.Groups[1].Value) { $null = $object.FileSystemParameterFlat.Add($find.Groups[1].Value) } if ($Template.Parameters -notcontains $find.Groups[1].Value) { $null = $Template.Parameters.Add($find.Groups[1].Value) } } #endregion Fixed string replacement #region Named Scriptblock replacement if ($find.Groups[2].Success) { $scriptName = $find.Groups[2].Value if ($Template.Scripts.Keys -eq $scriptName) { $null = $object.FileSystemParameterScript.Add($scriptName) } else { throw "Unknown named scriptblock '$($scriptName)' in name of '$($Item.FullName)'. Make sure the named scriptblock exists in the configuration file." } } #endregion Named Scriptblock replacement } #endregion File Name #region File Content if (-not ($Item.Extension -in $BinaryExtensions)) { $text = [System.IO.File]::ReadAllText($Item.FullName) foreach ($find in ([regex]::Matches($text, $pattern, 'IgnoreCase, Multiline'))) { #region Fixed string replacement if ($find.Groups[1].Success) { if ($object.ContentParameterFlat -notcontains $find.Groups[1].Value) { $null = $object.ContentParameterFlat.Add($find.Groups[1].Value) } if ($Template.Parameters -notcontains $find.Groups[1].Value) { $null = $Template.Parameters.Add($find.Groups[1].Value) } } #endregion Fixed string replacement #region Named Scriptblock replacement if ($find.Groups[2].Success) { $scriptName = $find.Groups[2].Value if ($Template.Scripts.Keys -eq $scriptName) { $null = $object.ContentParameterScript.Add($scriptName) } else { throw "Unknown named scriptblock '$($scriptName)' in name of '$($Item.FullName)'. Make sure the named scriptblock exists in the configuration file." } } #endregion Named Scriptblock replacement #region Live Scriptblock replacement if ($find.Groups[3].Success) { $scriptCode = $find.Groups[3].Value $scriptBlock = [ScriptBlock]::Create($scriptCode) if ($scriptBlock.ToString() -in $Template.Scripts.Values.StringScript) { $scriptName = ($Template.Scripts.Values | Where-Object StringScript -EQ $scriptBlock.ToString() | Select-Object -First 1).Name if ($object.ContentParameterScript -notcontains $scriptName) { $null = $object.ContentParameterScript.Add($scriptName) } $text = $text -replace ([regex]::Escape("$($Identifier){$($scriptCode)}$($Identifier)")), "$($Identifier)!$($scriptName)!$($Identifier)" } else { do { $scriptName = "dynamicscript_$(Get-Random -Minimum 100000 -Maximum 999999)" } until ($Template.Scripts.Keys -notcontains $scriptName) $parameter = New-Object PSModuleDevelopment.Template.ParameterScript($scriptName, ([System.Management.Automation.ScriptBlock]::Create($scriptCode))) $Template.Scripts[$scriptName] = $parameter $null = $object.ContentParameterScript.Add($scriptName) $text = $text -replace ([regex]::Escape("$($Identifier){$($scriptCode)}$($Identifier)")), "$($Identifier)!$($scriptName)!$($Identifier)" } } #endregion Live Scriptblock replacement } $object.Value = $text } else { $bytes = [System.IO.File]::ReadAllBytes($Item.FullName) $object.Value = [System.Convert]::ToBase64String($bytes) } #endregion File Content } #endregion File # Set identifier, so that Invoke-PSMDTemplate knows what to use when creating the item # Needed for sharing templates between users with different identifiers $object.Identifier = $Identifier if ($Parent) { $null = $Parent.Children.Add($object) } else { $null = $Template.Children.Add($object) } } #endregion Utility functions } process { if (Test-PSFFunctionInterrupt) { return } #region Parse content and produce template if ($ReferencePath) { foreach ($item in (Get-ChildItem -Path $processedReferencePath -Filter $Filter)) { if ($item.FullName -in $Exclusions) { continue } if ($item.Name -eq "PSMDTemplate.ps1") { continue } Convert-Item -Item $item -Filter $Filter -Exclusions $Exclusions -Template $template -ReferencePath $processedReferencePath -Identifier $identifier -BinaryExtensions $binaryExtensions } } else { $item = Get-Item -Path $FilePath Convert-Item -Item $item -Template $template -Identifier $identifier -BinaryExtensions $binaryExtensions } #endregion Parse content and produce template } end { if (Test-PSFFunctionInterrupt) { return } $template.CreatedOn = (Get-Date).Date $template | Export-Clixml -Path (Join-Path $exportFolder $fileName) $template.ToTemplateInfo() | Export-Clixml -Path (Join-Path $exportFolder $infoFileName) } } |