diff --git a/PSScriptTools.psd1 b/PSScriptTools.psd1 index 44b84ab..0a1ecd8 100644 Binary files a/PSScriptTools.psd1 and b/PSScriptTools.psd1 differ diff --git a/README.md b/README.md index 4b476e4..36f06de 100644 --- a/README.md +++ b/README.md @@ -664,8 +664,26 @@ PS C:\> get-runspace | where ID -gt 1 | Remove-Runspace Get all runspaces with an ID greater than 1, which is typically your session, and remove the runspace. +## [Get-ParameterInfo](docs/Get-ParameterInfo.md) + +Using Get-Command, this function will return information about parameters for any loaded cmdlet or function. The common parameters like Verbose and ErrorAction are omitted. Get-ParameterInfo returns a custom object with the most useful information an administrator might need to know. + +```powershell +PS C:\> Get-ParameterInfo -Command Get-Counter -Parameter computername + + +Name : computername +Aliases : Cn +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : __AllParameterSets +``` + ## Compatibility Where possible these commands have been tested with PowerShell Core, but not every platform. If you encounter problems, have suggestions or other feedback, please post an issue. -*last updated 12 February 2019* +*last updated 17 February 2019* diff --git a/changelog.md b/changelog.md index 29a7005..0ae8ada 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,13 @@ # Change Log for PSScriptTools +## v2.1.0 + ++ Added parameter to allow user to specify a type name with `New-PSFormatXML` (Issue #26) ++ Added `Get-ParameterInfo` command with an alias of `gpi` ++ Updated help for `Optimize-Text` ++ Help updates ++ Updated `README.md` + ## v2.0.0 + Added `New-PSFormatXml` and its alias `nfx` diff --git a/docs/Get-ParameterInfo.md b/docs/Get-ParameterInfo.md new file mode 100644 index 0000000..e8f67cb --- /dev/null +++ b/docs/Get-ParameterInfo.md @@ -0,0 +1,228 @@ +--- +external help file: PSScriptTools-help.xml +Module Name: PSScriptTools +online version: +schema: 2.0.0 +--- + +# Get-ParameterInfo + +## SYNOPSIS + +Retrieve command parameter information. + +## SYNTAX + +```yaml +Get-ParameterInfo [-Command] [-Parameter ] [] +``` + +## DESCRIPTION + +Using Get-Command, this function will return information about parameters for any loaded cmdlet or function. The common parameters like Verbose and ErrorAction are omitted. Get-ParameterInfo returns a custom object with the most useful information an administrator might need to know. See examples. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +PS C:\> get-parameterinfo get-service + + +Name : Name +Aliases : ServiceName +Mandatory : False +Position : 0 +ValueFromPipeline : True +ValueFromPipelineByPropertyName : True +Type : System.String[] +ParameterSet : Default + +Name : ComputerName +Aliases : Cn +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : True +Type : System.String[] +ParameterSet : __AllParameterSets + +Name : DependentServices +Aliases : DS +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.Management.Automation.SwitchParameter +ParameterSet : __AllParameterSets + +Name : RequiredServices +Aliases : SDO,ServicesDependedOn +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.Management.Automation.SwitchParameter +ParameterSet : __AllParameterSets + +Name : DisplayName +Aliases : +Mandatory : True +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : DisplayName + +Name : Include +Aliases : +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : __AllParameterSets + +Name : Exclude +Aliases : +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : __AllParameterSets + +Name : InputObject +Aliases : +Mandatory : False +Position : Named +ValueFromPipeline : True +ValueFromPipelineByPropertyName : False +Type : System.ServiceProcess.ServiceController[] +ParameterSet : InputObject +``` + +Return parameter information for Get-Service + +### EXAMPLE 2 + +```powershell +PS C:\> get-parameterinfo mkdir | Select Name,Type,Position,parameterset + +Name Type Position ParameterSet +---- ---- -------- ------------ +Path System.String[] 0 pathSet +Path System.String[] 0 nameSet +Name System.String Named nameSet +Value System.Object Named __AllParameterSets +Force System.Management.Automation.SwitchParameter Named __AllParameterSets +Credential System.Management.Automation.PSCredential Named __AllParameterSets +UseTransaction System.Management.Automation.SwitchParameter Named __AllParameterSets +``` + +Get selected parameter information for the mkdir command. + +### EXAMPLE 3 + +```powershell +PS C:\> get-parameterinfo get-ciminstance | sort parameterset | format-table -GroupBy ParameterSet -Property Name,Mandatory,Alias,Position,Type + + ParameterSet: __AllParameterSets + +Name Mandatory Alias Position Type +---- --------- ----- -------- ---- +OperationTimeoutSec False Named System.UInt32 + + + ParameterSet: CimInstanceComputerSet + +Name Mandatory Alias Position Type +---- --------- ----- -------- ---- +ResourceUri False Named System.Uri +InputObject True 0 Microsoft.Management.Infrastructure.CimInstance +ComputerName False Named System.String[] + + + ParameterSet: CimInstanceSessionSet + +Name Mandatory Alias Position Type +---- --------- ----- -------- ---- +CimSession True Named Microsoft.Management.Infrastructure.CimSession[] +InputObject True 0 Microsoft.Management.Infrastructure.CimInstance +ResourceUri False Named System.Uri... +``` + +Get all parameters from Get-CimInstance and display details as a formatted table. + +### Example 4 + +```powershell +PS C:\> Get-ParameterInfo -Command Get-Counter -Parameter computername + + +Name : computername +Aliases : Cn +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : __AllParameterSets +``` + +Get details on the Computername parameter of the Get-Counter cmdlet. + +## PARAMETERS + +### -Command + +The name of a cmdlet or function. The parameter has an alias of Name. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: name + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Parameter + +{{Fill Parameter Description}} + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [string] + +## OUTPUTS + +### custom object + +## NOTES + +Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ + +## RELATED LINKS + +[Get-Command]() diff --git a/docs/New-PSFormatXML.md b/docs/New-PSFormatXML.md index d4e4534..7bcf14e 100644 --- a/docs/New-PSFormatXML.md +++ b/docs/New-PSFormatXML.md @@ -14,8 +14,9 @@ Create or modify a format.ps1xml file ## SYNTAX ```yaml -New-PSFormatXML [-InputObject] [[-Properties] ] [[-FormatType] ] - [[-ViewName] ] [-Path] [-Append] [-Passthru] [-WhatIf] [-Confirm] [] +New-PSFormatXML [-InputObject] [[-Properties] ] [-Typename ] + [[-FormatType] ] [[-ViewName] ] [-Path] [-Append] [-Passthru] [-WhatIf] [-Confirm] + [] ``` ## DESCRIPTION @@ -236,10 +237,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Typename + +Specify the object typename. If you don't, then the command will use the detected object type from the Inputobject. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. -For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/docs/Optimize-Text.md b/docs/Optimize-Text.md index ae3369a..63a03d3 100644 --- a/docs/Optimize-Text.md +++ b/docs/Optimize-Text.md @@ -1,6 +1,6 @@ --- external help file: PSScriptTools-help.xml -Module Name: psscripttools +Module Name: PSScriptTools online version: schema: 2.0.0 --- @@ -13,7 +13,7 @@ Clean and optimize text input. ## SYNTAX -### Default (Default) +### default (Default) ```yaml Optimize-Text [[-Text] ] [-Filter ] [-Ignore ] [-ToUpper] [] @@ -22,7 +22,7 @@ Optimize-Text [[-Text] ] [-Filter ] [-Ignore ] [-ToUppe ### object ```yaml -Optimize-Text [[-Text] ] [-Filter ] [-PropertyName ] [-Ignore ] [-ToUpper] +Optimize-Text [[-Text] ] [-Filter ][-Ignore ] [-ToUpper] [-PropertyName ] [] ``` @@ -49,7 +49,7 @@ srv1 dc01 app02 - + PS C:\> get-content c:\scripts\computers.txt | optimize-text @@ -74,7 +74,6 @@ srv1 quark dc01 app02 - ``` Using the same text file, the command creates a custom object using the Computername property. @@ -134,7 +133,19 @@ The text to be optimized. Typically read in from a file. ```yaml Type: String[] -Parameter Sets: (All) +Parameter Sets: default +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +```yaml +Type: String[] +Parameter Sets: object Aliases: Required: False @@ -211,8 +222,7 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. -For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/en-us/PSScriptTools-help.xml b/en-us/PSScriptTools-help.xml index f90b83e..287d87f 100644 --- a/en-us/PSScriptTools-help.xml +++ b/en-us/PSScriptTools-help.xml @@ -2582,6 +2582,252 @@ up Param(\[string\]$computername=$env:com... + + + Get-ParameterInfo + Get + ParameterInfo + + Retrieve command parameter information. + + + + Using Get-Command, this function will return information about parameters for any loaded cmdlet or function. The common parameters like Verbose and ErrorAction are omitted. Get-ParameterInfo returns a custom object with the most useful information an administrator might need to know. See examples. + + + + Get-ParameterInfo + + Command + + The name of a cmdlet or function. The parameter has an alias of Name. + + String + + String + + + None + + + Parameter + + {{Fill Parameter Description}} + + String + + String + + + None + + + + + + Command + + The name of a cmdlet or function. The parameter has an alias of Name. + + String + + String + + + None + + + Parameter + + {{Fill Parameter Description}} + + String + + String + + + None + + + + + + [string] + + + + + + + + + + custom object + + + + + + + + + Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ + + + + + -------------------------- EXAMPLE 1 -------------------------- + PS C:\> get-parameterinfo get-service + + +Name : Name +Aliases : ServiceName +Mandatory : False +Position : 0 +ValueFromPipeline : True +ValueFromPipelineByPropertyName : True +Type : System.String[] +ParameterSet : Default + +Name : ComputerName +Aliases : Cn +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : True +Type : System.String[] +ParameterSet : __AllParameterSets + +Name : DependentServices +Aliases : DS +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.Management.Automation.SwitchParameter +ParameterSet : __AllParameterSets + +Name : RequiredServices +Aliases : SDO,ServicesDependedOn +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.Management.Automation.SwitchParameter +ParameterSet : __AllParameterSets + +Name : DisplayName +Aliases : +Mandatory : True +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : DisplayName + +Name : Include +Aliases : +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : __AllParameterSets + +Name : Exclude +Aliases : +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : __AllParameterSets + +Name : InputObject +Aliases : +Mandatory : False +Position : Named +ValueFromPipeline : True +ValueFromPipelineByPropertyName : False +Type : System.ServiceProcess.ServiceController[] +ParameterSet : InputObject + + Return parameter information for Get-Service + + + + -------------------------- EXAMPLE 2 -------------------------- + PS C:\> get-parameterinfo mkdir | Select Name,Type,Position,parameterset + +Name Type Position ParameterSet +---- ---- -------- ------------ +Path System.String[] 0 pathSet +Path System.String[] 0 nameSet +Name System.String Named nameSet +Value System.Object Named __AllParameterSets +Force System.Management.Automation.SwitchParameter Named __AllParameterSets +Credential System.Management.Automation.PSCredential Named __AllParameterSets +UseTransaction System.Management.Automation.SwitchParameter Named __AllParameterSets + + Get selected parameter information for the mkdir command. + + + + -------------------------- EXAMPLE 3 -------------------------- + PS C:\> get-parameterinfo get-ciminstance | sort parameterset | format-table -GroupBy ParameterSet -Property Name,Mandatory,Alias,Position,Type + + ParameterSet: __AllParameterSets + +Name Mandatory Alias Position Type +---- --------- ----- -------- ---- +OperationTimeoutSec False Named System.UInt32 + + + ParameterSet: CimInstanceComputerSet + +Name Mandatory Alias Position Type +---- --------- ----- -------- ---- +ResourceUri False Named System.Uri +InputObject True 0 Microsoft.Management.Infrastructure.CimInstance +ComputerName False Named System.String[] + + + ParameterSet: CimInstanceSessionSet + +Name Mandatory Alias Position Type +---- --------- ----- -------- ---- +CimSession True Named Microsoft.Management.Infrastructure.CimSession[] +InputObject True 0 Microsoft.Management.Infrastructure.CimInstance +ResourceUri False Named System.Uri... + + Get all parameters from Get-CimInstance and display details as a formatted table. + + + + -------------------------- Example 4 -------------------------- + PS C:\> Get-ParameterInfo -Command Get-Counter -Parameter computername + + +Name : computername +Aliases : Cn +Mandatory : False +Position : Named +ValueFromPipeline : False +ValueFromPipelineByPropertyName : False +Type : System.String[] +ParameterSet : __AllParameterSets + + Get details on the Computername parameter of the Get-Counter cmdlet. + + + + + + Get-Command + + + + Get-PowerShellEngine @@ -4352,6 +4598,18 @@ PS DeepDive:\> False + + Typename + + Specify the object typename. If you don't, then the command will use the detected object type from the Inputobject. + + String + + String + + + None + @@ -4463,6 +4721,18 @@ PS DeepDive:\> False + + Typename + + Specify the object typename. If you don't, then the command will use the detected object type from the Inputobject. + + String + + String + + + None + @@ -5104,6 +5374,56 @@ False Finally, you can use the -Filter parameter to specify a regular expression pattern to further filter what text is written to the pipeline. The filter is applied after leading and trailing spaces have been removed and before any text is converted to upper case. + + Optimize-Text + + Text + + The text to be optimized. Typically read in from a file. + + String[] + + String[] + + + None + + + Filter + + Use a regular expression pattern to filter. The filtering is applied after leading and trailing spaces have been trimmed and before text can be converted to upper case. + + Regex + + Regex + + + None + + + Ignore + + Specify a character that will be interpreted as a comment character. It must be the first word character in a line. These lines will be ignored. This parameter has an alias of 'comment'. + + String + + String + + + None + + + ToUpper + + Write text output as upper case. + + + SwitchParameter + + + False + + Optimize-Text @@ -5274,7 +5594,7 @@ srv1 dc01 app02 - + PS C:\> get-content c:\scripts\computers.txt | optimize-text diff --git a/functions/Get-Parameter.ps1 b/functions/Get-Parameter.ps1 new file mode 100644 index 0000000..610cb6c --- /dev/null +++ b/functions/Get-Parameter.ps1 @@ -0,0 +1,116 @@ + +Function Get-ParameterInfo { + + [cmdletbinding()] + [Outputtype("PSCustomobject")] + [alias("gpi")] + + Param( + [Parameter(Position = 0, Mandatory, + ValueFromPipeline, ValueFromPipelineByPropertyName, + HelpMessage = "Enter a cmdlet name")] + [ValidateNotNullorEmpty()] + [Alias("name")] + [string]$Command, + [string]$Parameter + ) + + Begin { + Write-Verbose "Starting $($myinvocation.MyCommand)" + #define the set of common parameters to exclude + $common = @("Verbose", + "Debug", + "ErrorAction", + "ErrorVariable", + "WarningAction", + "WarningVariable", + "OutVariable", + "OutBuffer", + "WhatIf", + "Confirm", + "InformationAction", + "InformationVariable", + "pipelinevariable" + ) + } #begin + + Process { + Write-Verbose "Processing $command for parameter information" + Try { + $data = (Get-Command -Name $command -errorAction "Stop").parameters + } + Catch { + Write-Warning "Failed to find command $command" + } + #keep going if parameters were found + if ($data.count -gt 0) { + #$data is a hash table + if ($Parameter) { + Write-Verbose "Getting parameter $Parameter" + if ($data.ContainsKey( $Parameter)) { + $params = $Parameter + } + else { + Throw "Can't find a parameter called $Parameter." + } + } + else { + Write-Verbose "Getting parameter all non-common parameters" + $params = $data.keys | where-object {$common -notcontains $_} + } + $count = ($params | measure-object).count + #only keep going if non-common parameters were found + write-verbose "Found $count non-common parameters for $command" + + if ($count -gt 0) { + #get information from each parameter + + $params | foreach-object { + $name = $_ + Write-Verbose "Analyzing $name" + $type = $data.item($name).ParameterType + $aliases = $data.item($name).Aliases -join "," + + $sets = $data.item($name).ParameterSets.Keys + + foreach ($set in $sets) { + + #retrieve parameter attribute class + $attributes = $data.item($name).Attributes | where-object {$_ -is [system.management.automation.parameterAttribute] -AND $_.ParameterSetName -eq $set} + + #a parameter could have different positions in different property sets + if ($attributes.position -ge 0) { + $position = $attributes.position + } + else { + $position = "Named" + } + + #write a custom object to the pipeline + [PSCustomObject]@{ + Name = $name + Aliases = $aliases + Mandatory = $attributes.mandatory + Position = $position + ValueFromPipeline = $attributes.ValueFromPipeline + ValueFromPipelineByPropertyName = $attributes.ValueFromPipelineByPropertyName + Type = $type + ParameterSet = $attributes.ParameterSetName + } + + } #foreach set + } #foreach object + } #if $count + } #if $data + else { + Write-warning "$command has no defined parameters" + } + } #process + + End { + Write-Verbose "Ending $($myinvocation.MyCommand)" + } #end + +} #end function + + diff --git a/functions/New-PSFormatXML.ps1 b/functions/New-PSFormatXML.ps1 index ccffbdf..f367cef 100644 --- a/functions/New-PSFormatXML.ps1 +++ b/functions/New-PSFormatXML.ps1 @@ -9,6 +9,8 @@ Function New-PSFormatXML { [object]$InputObject, [Parameter(HelpMessage = "Enter a set of properties to include. The default is all.")] [string[]]$Properties, + [Parameter(HelpMessage = "Specify the object typename. If you don't, then the command will use the detected object type from the Inputobject.")] + [string]$Typename, [Parameter(HelpMessage = "Specify whether to create a table or list view")] [ValidateSet("Table", "List")] [string]$FormatType = "Table", @@ -81,7 +83,12 @@ by $env:USERDOMAIN\$env:username Process { If ($counter -eq 0) { - $tname = $Inputobject.psobject.typenames[0] + if ($Typename) { + $tname = $TypeName + } + else { + $tname = $Inputobject.psobject.typenames[0] + } $tnameElement = $doc.CreateElement("TypeName") $tnameElement.InnerText = $tname $select.AppendChild($tnameElement) | Out-Null diff --git a/functions/Optimize-Text.ps1 b/functions/Optimize-Text.ps1 index a88da14..aa0d001 100644 --- a/functions/Optimize-Text.ps1 +++ b/functions/Optimize-Text.ps1 @@ -1,24 +1,35 @@ Function Optimize-Text { - [cmdletbinding(DefaultParameterSetName = "Default")] - [OutputType([System.String], ParameterSetName = "Default")] + [cmdletbinding(DefaultParameterSetName = "default")] + [OutputType([System.String], ParameterSetName = "default")] [OutputType([psobject], ParameterSetName = "object")] [Alias("ot")] Param( - [Parameter(Position = 0, HelpMessage = "Enter some text", ValueFromPipeline = $True)] + [Parameter(Position = 0, HelpMessage = "Enter some text", ValueFromPipeline, ParameterSetName = "default")] + [Parameter(ParameterSetName = "object")] [string[]]$Text, + + [Parameter(ParameterSetName = "object")] + [Parameter(ParameterSetName = "default")] [regex]$Filter, + [Parameter(ParameterSetName = "object")] [string]$PropertyName, + [Alias("comment")] + [Parameter(ParameterSetName = "object")] + [Parameter(ParameterSetName = "default")] [string]$Ignore, + + [Parameter(ParameterSetName = "object")] + [Parameter(ParameterSetName = "default")] [switch]$ToUpper ) Begin { - Write-Verbose "Starting $($MyInvocation.Mycommand)" - + Write-Verbose "Starting $($MyInvocation.Mycommand)" + } #begin Process { @@ -57,7 +68,7 @@ } #else not ignoring } #if output } #if item matches non-whitespce - } #foreach + } #foreach } #process