## Pre-Loaded Module code ##

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseDeclaredVarsMoreThanAssignments", "ModuleBuildLoggingEnabled",Justification="ModuleBuildLoggingEnabled is optional. It's used to enable Nlog-based logging.")]

param()

$ModuleBuildLoggingEnabled = $false # Set to true to enable nlog-based logging

Function Add-MBMissingCBH {

<#

[CmdletBinding()]

param(

[parameter(Position=0, ValueFromPipeline=$true, HelpMessage='Lines of code to process.')]

[string[]]$Code

)

begin {

# CBH pattern that tells us CBH likely already exists

$CBHPattern = "(?ms)(^\s*\<#.*[\.SYNOPSIS|\.DESCRIPTION|\.PARAMETER|\.EXAMPLE|\.NOTES|\.LINK].*?#>)"

$Codeblock = @()

}

process {

$Codeblock += $Code

}

end {

$ScriptText = ($Codeblock | Out-String).trim("`r`n")

# If no sign of CBH exists then try to generate and insert it

if ($ScriptText -notmatch $CBHPattern) {

$CBH = @($ScriptText | New-MBCommentBasedHelp)

if ($CBH.Count -gt 1) {

throw 'Too many functions are defined in the input string!'

}

if ($CBH.Count -ne 0) {

try {

$currscriptblock = [scriptblock]::Create($ScriptText)

. $currscriptblock

$currfunct = get-command $CBH.FunctionName

}

catch {

throw $_

}

$UpdatedFunct = 'Function ' + $currfunct.Name + ' {' + "`r`n" + $CBH.CBH + "`r`n" + $currfunct.definition + "`r`n" + '}'

$UpdatedFunct

}

else {

Write-Warning 'Unable to generate CBH for the script text!'

$ScriptText

}

}

else {

Write-Verbose "Comment based help already exists - skipping CBH insertion and returning original script."

$ScriptText

}

}

}

function Convert-MBArrayToRegex {

# Takes an array of strings and turns it into a regex matchable string

[CmdletBinding()]

param(

[parameter(Position = 0, ValueFromPipeline = $TRUE)]

[String[]]$Item,

[parameter(Position = 1)]

[Switch]$DoNotEscape

)

begin {

$Items = @()

}

process {

$Items += $Item

}

end {

if ($Items.Count -gt 0) {

if ($DoNotEscape) {

'^(' + ($Items -join '|') + ')$'

}

else {

'^(' + (($Items | ForEach-Object{[regex]::Escape($_)}) -join '|') + ')$'

}

}

else {

'^()$'

}

}

}

function Get-CallerPreference {

<#

[CmdletBinding(DefaultParameterSetName = 'AllVariables')]

param (

[Parameter(Mandatory = $true)]

[ValidateScript({ $_.GetType().FullName -eq 'System.Management.Automation.PSScriptCmdlet' })]

$Cmdlet,

[Parameter(Mandatory = $true)]

[System.Management.Automation.SessionState]$SessionState,

[Parameter(ParameterSetName = 'Filtered', ValueFromPipeline = $true)]

[string[]]$Name

)

begin {

$filterHash = @{}

}

process {

if ($null -ne $Name)

{

foreach ($string in $Name)

{

$filterHash[$string] = $true

}

}

}

end {

# List of preference variables taken from the about_Preference_Variables help file in PowerShell version 4.0

$vars = @{

'ErrorView' = $null

'FormatEnumerationLimit' = $null

'LogCommandHealthEvent' = $null

'LogCommandLifecycleEvent' = $null

'LogEngineHealthEvent' = $null

'LogEngineLifecycleEvent' = $null

'LogProviderHealthEvent' = $null

'LogProviderLifecycleEvent' = $null

'MaximumAliasCount' = $null

'MaximumDriveCount' = $null

'MaximumErrorCount' = $null

'MaximumFunctionCount' = $null

'MaximumHistoryCount' = $null

'MaximumVariableCount' = $null

'OFS' = $null

'OutputEncoding' = $null

'ProgressPreference' = $null

'PSDefaultParameterValues' = $null

'PSEmailServer' = $null

'PSModuleAutoLoadingPreference' = $null

'PSSessionApplicationName' = $null

'PSSessionConfigurationName' = $null

'PSSessionOption' = $null

'ErrorActionPreference' = 'ErrorAction'

'DebugPreference' = 'Debug'

'ConfirmPreference' = 'Confirm'

'WhatIfPreference' = 'WhatIf'

'VerbosePreference' = 'Verbose'

'WarningPreference' = 'WarningAction'

}

foreach ($entry in $vars.GetEnumerator()) {

if (([string]::IsNullOrEmpty($entry.Value) -or -not $Cmdlet.MyInvocation.BoundParameters.ContainsKey($entry.Value)) -and

($PSCmdlet.ParameterSetName -eq 'AllVariables' -or $filterHash.ContainsKey($entry.Name))) {

$variable = $Cmdlet.SessionState.PSVariable.Get($entry.Key)

if ($null -ne $variable) {

if ($SessionState -eq $ExecutionContext.SessionState) {

Set-Variable -Scope 1 -Name $variable.Name -Value $variable.Value -Force -Confirm:$false -WhatIf:$false

}

else {

$SessionState.PSVariable.Set($variable.Name, $variable.Value)

}

}

}

}

if ($PSCmdlet.ParameterSetName -eq 'Filtered') {

foreach ($varName in $filterHash.Keys) {

if (-not $vars.ContainsKey($varName)) {

$variable = $Cmdlet.SessionState.PSVariable.Get($varName)

if ($null -ne $variable)

{

if ($SessionState -eq $ExecutionContext.SessionState)

{

Set-Variable -Scope 1 -Name $variable.Name -Value $variable.Value -Force -Confirm:$false -WhatIf:$false

}

else

{

$SessionState.PSVariable.Set($variable.Name, $variable.Value)

}

}

}

}

}

}

}

function Get-MBCommonParameter {

# Helper function to get all the automatically added parameters in an

# advanced function

function somefunct {

[CmdletBinding(SupportsShouldProcess = $true, SupportsPaging = $true, SupportsTransactions = $true)]

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Scope="Function", Target="somefunct",Justification="This is a dummy function in order to get all CommonParameters without hardcoding them. There is no reason for it to actually use SupportsShouldProcess.")]

param()

}

((Get-Command somefunct).Parameters).Keys

}

function Get-MBFunction {

<#

[CmdletBinding()]

param(

[parameter(Position = 0, Mandatory = $true, ValueFromPipeline=$true, HelpMessage='Lines of code to process.')]

[AllowEmptyString()]

[string[]]$Code,

[parameter(Position=1, HelpMessage='Name of function to process.')]

[string]$Name = '*'

)

begin {

$ThisFunc = $MyInvocation.MyCommand.Name

Write-Verbose "$($ThisFunc): Begin."

$Codeblock = @()

$ParseError = $null

$Tokens = $null

$predicate = {

($args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst]) -and

($args[0].Name -like $name)

}

}

process {

$Codeblock += $Code

}

end {

$ScriptText = ($Codeblock | Out-String).trim("`r`n")

Write-Verbose "$($ThisFunc): Attempting to parse AST."

$AST = [System.Management.Automation.Language.Parser]::ParseInput($ScriptText, [ref]$Tokens, [ref]$ParseError)

if($ParseError) {

throw "$($ThisFunc): Will not work properly with errors in the script, please modify based on the above errors and retry."

}

# First get all blocks

$Blocks = $AST.FindAll($predicate, $true)

Foreach ($Block in $Blocks) {

$FunctionProps = @{

Name = $Block.Name

Definition = $Block.Extent.Text

IsEmbedded = $false

AST = $Block

}

if (@(Get-MBParentASTType $Block) -contains 'FunctionDefinitionAst') {

$FunctionProps.IsEmbedded = $true

}

New-Object -TypeName psobject -Property $FunctionProps

}

Write-Verbose "$($ThisFunc): End."

}

}

function Get-MBTFunctionParameter {

<#

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseDeclaredVarsMoreThanAssignments","functionpredicate",Scope="Function",Target='Get-MBTFunctionParameter',Justification="Unused AST filter")]

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseDeclaredVarsMoreThanAssignments","CommonParams",Scope="Function",Target='Get-MBTFunctionParameter',Justification="")]

[CmdletBinding()]

param(

[parameter(ValueFromPipeline=$true, HelpMessage='Lines of code to process.')]

[string[]]$Code,

[parameter(Position=1, HelpMessage='Name of function to process.')]

[string]$Name = '*',

[parameter(Position=2, HelpMessage='Try to parse for top-level/non-function script parameters as well.')]

[switch]$ScriptParameters,

[parameter(Position=3, HelpMessage='Include parameters and functions of embedded functions.')]

[switch]$IncludeEmbedded

)

begin {

$FunctionName = $MyInvocation.MyCommand.Name

Write-Verbose "$($FunctionName): Begin."

$Codeblock = @()

$ParseError = $null

$Tokens = $null

$functionpredicate = {

($args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst]) -and

($args[0].Name -like $name)

}

$parampredicate = { ($args[0] -is [System.Management.Automation.Language.ParameterAst]) }

$typepredicate = { ($args[0] -is [System.Management.Automation.Language.TypeConstraintAst]) }

$paramattributes = { ($args[0] -is [System.Management.Automation.Language.NamedAttributeArgumentAst]) }

$output = @()

}

process {

$Codeblock += $Code

$CommonParams = Get-MBCommonParameter

}

end {

$ScriptText = ($Codeblock | Out-String).trim("`r`n")

Write-Verbose "$($FunctionName): Attempting to parse AST."

$AST = [System.Management.Automation.Language.Parser]::ParseInput($ScriptText, [ref]$Tokens, [ref]$ParseError)

if($ParseError) {

throw "$($FunctionName): Will not work properly with errors in the script, please modify based on the above errors and retry."

}

if (-not $ScriptParameters) {

$functions = $CodeBlock | Get-MBFunction -Name $Name

if (-not $IncludeEmbedded) {

Write-Verbose "$($FunctionName): Not including embedded functions."

$functions = $functions | Where-Object {-not $_.IsEmbedded}

}

If([string]::IsNullOrEmpty($functions))

{

Write-Verbose "$($FunctionName): There were no script parameters found"

} else

{

Foreach ($f in $functions) {

$function = $f.ast

$Parameters = $function.FindAll($parampredicate, $true)

foreach ($p in $Parameters) {

$ParamType = $p.FindAll($typepredicate, $true)

Write-Verbose "$($FunctionName): Processing Parameter of type [$($ParamType.typeName.FullName)] - $($p.Name.VariablePath.ToString())"

$OutProps = @{

'FunctionName' = $function.Name.ToString()

'ParameterName' = $p.Name.VariablePath.ToString()

'ParameterType' = $ParamType[0].typeName.FullName

}

# This will add in any other parameter attributes if they are specified (default attributes are thus not included and output may not be normalized)

$p.FindAll($paramattributes, $true) | ForEach-Object {

$OutProps.($_.ArgumentName) = $_.Argument.Value

}

$Output += New-Object -TypeName PSObject -Property $OutProps

}

}

}

}

else {

Write-Verbose "$($FunctionName): Processing Script parameters"

if ($ast.ParamBlock -ne $null) {

$scriptparams = $ast.ParamBlock

$Parameters = $scriptparams.FindAll($parampredicate, $true)

foreach ($p in $Parameters) {

$ParamType = $p.FindAll($typepredicate, $true)

Write-Verbose "$($FunctionName): Processing Parameter of type [$($ParamType.typeName.FullName)] - $($p.Name.VariablePath.ToString())"

$OutProps = @{

'FunctionName' = 'Script'

'ParameterName' = $p.Name.VariablePath.ToString()

'ParameterType' = $ParamType[0].typeName.FullName

}

# This will add in any other parameter attributes if they are specified (default attributes are thus not included and output may not be normalized)

$p.FindAll($paramattributes, $true) | ForEach-Object {

$OutProps.($_.ArgumentName) = $_.Argument.Value

}

$Output += New-Object -TypeName PSObject -Property $OutProps

}

}

else {

Write-Verbose "$($FunctionName): There were no script parameters found"

}

}

$Output

Write-Verbose "$($FunctionName): End."

}

}

function Get-MBParentASTType {

<#

[CmdletBinding()]

param(

[parameter(Position = 0, Mandatory = $true, ValueFromPipeline=$true, HelpMessage='AST element to process.')]

$AST

)

# Pull in all the caller verbose,debug,info,warn and other preferences

if ($script:ThisModuleLoaded -eq $true) { Get-CallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState }

$FunctionName = $MyInvocation.MyCommand.Name

Write-Verbose "$($FunctionName): Begin."

$ASTParents = @()

if ($AST.Parent -ne $null) {

$CurrentParent = $AST.Parent

$KeepProcessing = $true

}

else {

$KeepProcessing = $false

}

while ($KeepProcessing) {

$ASTParents += $CurrentParent.GetType().Name.ToString()

if ($CurrentParent.Parent -ne $null) {

$CurrentParent = $CurrentParent.Parent

$KeepProcessing = $true

}

else {

$KeepProcessing = $false

}

}

$ASTParents

Write-Verbose "$($FunctionName): End."

}

function New-MBCommentBasedHelp {

<#

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseDeclaredVarsMoreThanAssignments", "ScriptText",Scope="Function",Target="New-MBCommentBasedHelp",Justification="Seems it's here since duo a copy paste from other functions (Add-MBMissingCBH,Get-MBFunction,Get-MBTFunctionParameter). Leaving it here since it doesn't do any harm.")]

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions","",Scope="Function",Target="New-MBCommentBasedHelp",Justification="Function does not change system state. Simply outputs a obj with CommentBasedHelp.")]

[CmdletBinding()]

param(

[parameter(Position=0, ValueFromPipeline=$true, HelpMessage='Lines of code to process.')]

[string[]]$Code,

[parameter(Position=1, HelpMessage='Process the script parameters as the source of the comment based help.')]

[switch]$ScriptParameters

)

begin {

$FunctionName = $MyInvocation.MyCommand.Name

Write-Verbose "$($FunctionName): Begin."

$CBH_PARAM = @'

$Codeblock = @()

$CBHTemplate = @'

}

process {

$Codeblock += $Code

}

end {

$ScriptText = ($Codeblock | Out-String).trim("`r`n")

Write-Verbose "$($FunctionName): Attempting to parse parameters."

$FuncParams = @{}

if ($ScriptParameters) {

$FuncParams.ScriptParameters = $true

}

$AllParams = Get-MBTFunctionParameter @FuncParams -Code $Codeblock | Sort-Object -Property FunctionName

$AllFunctions = @($AllParams.FunctionName | Select-Object -unique)

If([string]::IsNullOrEmpty($AllFunctions))

{

Write-Verbose "$($FunctionName): Found no Params in function."

} else

{

foreach ($f in $AllFunctions) {

$OutCBH = @{}

$OutCBH.FunctionName = $f

[string]$OutParams = ''

$fparams = @($AllParams | Where-Object {$_.FunctionName -eq $f} | Sort-Object -Property Position)

if ($fparams.count -gt 0) {

$fparams | ForEach-Object {

$ParamHelpMessage = if ([string]::IsNullOrEmpty($_.HelpMessage)) { $_.ParameterName + " explanation`n`r`n`r"} else {$_.HelpMessage + "`n`r`n`r"}

$OutParams += $CBH_PARAM -replace '%%PARAM%%',$_.ParameterName -replace '%%PARAMHELP%%',$ParamHelpMessage

}

}

else {

}

$OutCBH.'CBH' = $CBHTemplate -replace '%%PARAMETER%%',$OutParams

New-Object PSObject -Property $OutCBH

}

}

Write-Verbose "$($FunctionName): End."

}

}

function New-MBDynamicParameter {

<#