### Install PSFramework Module Source: https://github.com/powershellframeworkcollective/psframework/blob/development/README.md Installs the latest production build of the PSFramework module using the PowerShell Gallery. This command makes the module available for use in your PowerShell sessions. ```powershell Install-Module PSFramework ``` -------------------------------- ### Register PSFTaskEngine Task (Once) Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psf_taskengine.help.txt Demonstrates how to register a task to run only once using the Register-PSFTaskEngineTask cmdlet. This is useful for one-off maintenance or setup operations. ```powershell Register-PSFTaskEngineTask -Name 'mymodule.buildcache' -ScriptBlock $ScriptBlock -Once -Description 'Builds the object cache used by the mymodule module' ``` -------------------------------- ### ConvertTo-PSFHashtable Cmdlet Documentation Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/ConvertTo-PSFHashtable.md Provides comprehensive documentation for the ConvertTo-PSFHashtable cmdlet. It covers the cmdlet's syntax, detailed description, parameter explanations, and usage examples, enabling users to effectively convert objects to hashtables with fine-grained control. ```APIDOC ConvertTo-PSFHashtable SYNOPSIS Converts an object into a hashtable. SYNTAX ConvertTo-PSFHashtable [-Include ] [-Exclude ] [-CaseSensitive] [-IncludeEmpty] [-Inherit] [-Remap ] [-InputObject ] [-ReferenceCommand ] [-ReferenceParameterSetName ] [-AsPsfHashtable] [-ProgressAction ] [] DESCRIPTION Converts an object into a hashtable. - Use -Exclude to selectively blacklist properties / keys - Use -Include to selectively whitelist properties / keys - Use -Inherit to inherit values from variables when missing keys explicitly included in -Include Optimized to selectively convert $PSBoundParameters for passing through parameters to internal command calls. EXAMPLES Example 1 Get-ChildItem | ConvertTo-PSFHashtable Scans all items in the current path and converts those objects into hashtables. Example 2 $parameters = $PSBoundParameters | ConvertTo-PSFHashtable -Include ComputerName, Credential, Target -Inherit Clones the bound parameters into a new hashtable that can now be used for splatting- Only parameters explicitly specified or with default values will be included. PARAMETERS -Exclude The propertynames to exclude. Must be full property-names, no wildcard/regex matching. Type: String[] Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -Include The propertynames to include. Must be full property-names, no wildcard/regex matching. Type: String[] Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -IncludeEmpty By default, only properties on the input object are included. In order to force all properties defined in -Include to be included, specify this switch. Keys added through this have an empty ($null) value. Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False -Inherit By default, only properties on the input object are included. With this parameter, missing keys are substituted for by looking in the caller scope for variables with the same name. This is explicitly designed to allow inheriting default parameter values when cloning $PSBoundParameters. Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False -InputObject The object(s) to convert Type: PSObject[] Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False -CaseSensitive Make Include and Exclude name-filtering case sensitive. Will be ignored when also specifying the "AsPsfHashtable" parameter. Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -AsPsfHashtable The return object(s) will be of the special type "PsfHashtable", rather than a regular hashtable. This will behave like a regular hashtable, but also supports defining a default value when resolving a key that has not been defined. Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -ProgressAction {{ Fill ProgressAction Description }} Type: ActionPreference Parameter Sets: (All) Aliases: proga Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -ReferenceCommand Only include keys that map to the parameters of the specified command. Type: String Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -ReferenceParameterSetName When mapping keys to the parameters of command, only apply those that are part of this parameter set. Type: String Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -Remap Rename keys from the input object. Provide a hashtable mapping the original property name (key) to the intended name (value). Type: Hashtable Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` -------------------------------- ### Basic Invoke-PSFCallback Example Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Invoke-PSFCallback.md Demonstrates the basic invocation of Invoke-PSFCallback. This triggers any registered callback scriptblocks applicable to the current command without passing any additional data or specific exception handling. ```PowerShell Invoke-PSFCallback ``` -------------------------------- ### Invoke-PSFCallback Cmdlet Documentation Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Invoke-PSFCallback.md Provides detailed information on the Invoke-PSFCallback cmdlet, including its syntax, parameters, and examples. This cmdlet is used to trigger registered callback scripts, allowing for dynamic extension of module functionality. It supports passing data and controlling exception handling for callbacks. ```APIDOC Invoke-PSFCallback SYNOPSIS: Invokes all registered callback scripts applicable to the calling command. SYNTAX: Invoke-PSFCallback [-Data ] [-EnableException ] [-PSCmdlet ] [-ProgressAction ] [] DESCRIPTION: Invokes all registered callback scripts applicable to the calling command. Use Register-PSFCallback to register scriptblocks that get applied. By calling Invoke-PSFCallback, a module can provide extensions points to which other modules can attach, without the implementing module needing to know those external modules. PARAMETERS: -Data Additional data to provide to the callback scriptblock. This can be useful to implement input-driven workflows. For example, it would allow a callback scriptblock to load configuration, based on the server being processed. Type: Object Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -EnableException Enables - if $true - terminating exceptions when a single callback scriptblock fails. The terminating exception is thrown in the context of the calling command, not Invoke-PSFCallback, so it is unnecessary - and impossible - to handle within a try/catch block. If set to $false (default), failure flags the calling command for failure, as detected by Test-PSFFunctionInterrupt. In that case, Invoke-PSFCallback will log the error, but not directly terminate the calling command. Type: Boolean Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -PSCmdlet The $PSCmdlet object of the calling command. If this value is not provided, it will automatically be picked up. Providing it improves performance slightly, as it removes the need to look it up. Type: PSCmdlet Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False -ProgressAction {{ Fill ProgressAction Description }} Type: ActionPreference Parameter Sets: (All) Aliases: proga 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: None OUTPUTS: System.Object RELATED LINKS: Register-PSFCallback ``` -------------------------------- ### PSFramework Error Handling Example Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psf_message.help.txt Demonstrates how to catch an exception using a try-catch block and write a warning message with the caught error record using Write-PSFMessage. This showcases the use of the -ErrorRecord and -Message parameters. ```PowerShell try { $null.ToString() } catch { Write-PSFMessage -Level Warning -ErrorRecord $_ -Message "Failed to do the impossible!" } ``` -------------------------------- ### Set-PSFConfig Cmdlet Documentation Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Set-PSFConfig.md Comprehensive documentation for the Set-PSFConfig PowerShell cmdlet. This cmdlet is used to create or change configuration values, providing a dynamic configuration system outside the standard PowerShell variable system. It details syntax, parameters, and usage examples. ```APIDOC SYNOPSIS Sets configuration entries. DESCRIPTION This function creates or changes configuration values. These can be used to provide dynamic configuration information outside the PowerShell variable system. SYNTAX ### FullName (Default) ```powershell Set-PSFConfig -FullName [-Value ] [-Description ] [-Validation ] [-Handler ] [-Hidden] [-Default] [-Initialize] [-SimpleExport] [-ModuleExport] [-AllowDelete] [-DisableValidation] [-DisableHandler] [-PassThru] [-EnableException] [-ProgressAction ] [] ``` ### Persisted ```powershell Set-PSFConfig -FullName -PersistedValue [-PersistedType ] [-Description ] [-Validation ] [-Handler ] [-Hidden] [-Default] [-Initialize] [-SimpleExport] [-ModuleExport] [-AllowDelete] [-DisableValidation] [-DisableHandler] [-PassThru] [-EnableException] [-ProgressAction ] [] ``` ### Module ```powershell Set-PSFConfig [-Module ] -Name [-Value ] [-Description ] [-Validation ] [-Handler ] [-Hidden] [-Default] [-Initialize] [-SimpleExport] [-ModuleExport] [-AllowDelete] [-DisableValidation] [-DisableHandler] [-PassThru] [-EnableException] [-ProgressAction ] [] ``` PARAMETERS ### -FullName The full name of a configuration element. Must be namespaced .. The name can have any number of sub-segments, in order to better group configurations thematically. ```yaml Type: String Parameter Sets: FullName, Persisted Aliases: Required: True Position: Named Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False ``` ### -Name Name of the configuration entry. If an entry of exactly this non-casesensitive name already exists, its value will be overwritten. Duplicate names across different modules are possible and will be treated separately. If a name contains namespace notation and no module is set, the first namespace element will be used as module instead of name. Example: -Name "Nordwind.Server" Is Equivalent to -Name "Server" -Module "Nordwind" ```yaml Type: String Parameter Sets: Module Aliases: Required: True Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Module This allows grouping configuration elements into groups based on the module/component they serve. If this parameter is not set, the configuration element must have a module name in the name parameter (the first segment will be taken, irrespective of whether that makes sense). ```yaml Type: String Parameter Sets: Module Aliases: Required: False Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Value The value of the configuration entry. ```yaml Type: Object Parameter Sets: FullName, Module Aliases: Required: False Position: Named Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False ``` ### -PersistedValue Stores the value in a persisted manner. This is useful for values that should survive script reloads or system restarts. ```yaml Type: String Parameter Sets: Persisted Aliases: Required: True Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -PersistedType Specifies the type for persisted values, influencing how the value is stored and retrieved. ```yaml Type: ConfigurationValueType Parameter Sets: Persisted Aliases: Required: False Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Description A descriptive text for the configuration entry, explaining its purpose or usage. ```yaml Type: String Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Validation Specifies a validation rule for the configuration entry's value, ensuring data integrity. ```yaml Type: String Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Handler A script block that can be executed when the configuration value is accessed or modified, allowing custom logic. ```yaml Type: ScriptBlock Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Hidden Marks the configuration entry as hidden, preventing it from being displayed by default when listing configurations. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Default Sets the configuration entry as a default value. It is only applied if the configuration entry does not already exist. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Initialize Initializes the configuration entry. This flag is often used in conjunction with other parameters to set up a configuration for the first time. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -SimpleExport Indicates that the configuration entry should be exported in a simple format. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -ModuleExport Indicates that the configuration entry should be exported as part of a module. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -AllowDelete Allows the configuration entry to be deleted. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -DisableValidation Disables the validation for the configuration entry. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -DisableHandler Disables the handler for the configuration entry. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -PassThru Returns the configuration object that was created or modified. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -EnableException Enables exception handling for the cmdlet. ```yaml Type: SwitchParameter Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: False Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -ProgressAction Specifies how this cmdlet responds to the operation progress. Possible values are SilentlyContinue, Continue, Inquire, Suspend, Wait, and Stop. ```yaml Type: ActionPreference Parameter Sets: FullName, Persisted, Module Aliases: Required: False Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` EXAMPLES ### Example 1: Simple ```powershell Set-PSFConfig -FullName 'MyModule.User' -Value "Friedrich" ``` Creates or updates a configuration entry under the module "MyModule" named "User" with the value "Friedrich" ### Example 2: Module Definition ```powershell Set-PSFConfig -Name 'mymodule.User' -Value "Friedrich" -Description "The user under which the show must go on." -Handler $scriptBlock -Initialize -Validation String ``` Creates a configuration entry named "mymodule.user" with the value "Friedrich". It adds a description, registers a scriptblock as a handler, initializes the script (this block only executes the first time it is run), and registers a basic string input type validator. This is the default example for modules using the configuration system. Note: While the -Handler parameter is optional, it is important to add it at the initial initialize call if you are planning to add it. Only then will the system validate previous settings (such as what a user might have placed in his user profile). ### Example 3: Hiding things ```powershell Set-PSFConfig 'Company' 'ConfigLink' 'https://www.example.com/config.xml' -Hidden ``` Creates a configuration entry named "ConfigLink" in the "Company" module with the value 'https://www.example.com/config.xml'. This entry is hidden from casual discovery using Get-PSFConfig. ### Example 4: Default Settings ```powershell Set-PSFConfig -FullName 'Network.Firewall' -Value '10.0.0.2' -Default ``` Creates a configuration entry named "Firewall" in the "Network" module with the value '10.0.0.2'. This is only set if the setting does not exist yet. If it does, this command will apply no changes. ``` -------------------------------- ### Full Invoke-PSFCallback Invocation Example Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Invoke-PSFCallback.md Illustrates a comprehensive invocation of Invoke-PSFCallback, including passing data and enabling terminating exceptions. If any callback scriptblock fails with a terminating exception, the calling command will also fail. ```PowerShell Invoke-PSFCallback -Data $Server -EnableException $true -PSCmdlet $PSCmdlet ``` -------------------------------- ### Invoke-PSFCallback with Data Example Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Invoke-PSFCallback.md Shows how to invoke Invoke-PSFCallback while passing data. The provided data, stored in the $Server variable, is made available to the executed callback scriptblocks, enabling input-driven workflows. ```PowerShell Invoke-PSFCallback -Data $Server ``` -------------------------------- ### PowerShell Parameter Documentation Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Select-PSFObject.md Detailed documentation for parameters used in psframework cmdlets, covering property selection, exclusion, expansion, filtering, and display options. ```APIDOC Parameter: -Property Description: The properties to select. Supports hashtables for renaming (e.g., "Length AS Size") and casting (e.g., "Address to IPAddress"). Also supports parsing numbers to sizes (e.g., "Length size GB:2") and selecting properties from other variables (e.g., "ComputerName from VarName"). Can also filter when selecting from outside objects (e.g., "ComputerName from VarName where ObjectId = Id"). Type: SelectParameter[] Parameter Sets: DefaultParameter, SkipLastParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -ExcludeProperty Description: Properties to not list. Type: String[] Parameter Sets: DefaultParameter, SkipLastParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -ExpandProperty Description: Properties to expand. Type: String Parameter Sets: DefaultParameter, SkipLastParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -Unique Description: Do not list multiples of the same value. Type: SwitchParameter Parameter Sets: (All) Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -Last Description: Select the last n items. Type: Int32 Parameter Sets: DefaultParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -First Description: Select the first n items. Type: Int32 Parameter Sets: DefaultParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -Skip Description: Skip the first (or last if used with -Last) n items. Type: Int32 Parameter Sets: DefaultParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -SkipLast Description: Skip the last n items. Type: Int32 Parameter Sets: SkipLastParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -Wait Description: Indicates that the cmdlet turns off optimization. Windows PowerShell runs commands in the order that they appear in the command pipeline and lets them generate all objects. By default, if you include a Select-PSFObject command with the First or Index parameters in a command pipeline, Windows PowerShell stops the command that generates the objects as soon as the selected number of objects is generated. Type: SwitchParameter Parameter Sets: DefaultParameter, IndexParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -Index Description: Specifies an array of objects based on their index values. Enter the indexes in a comma-separated list. Type: Int32[] Parameter Sets: IndexParameter Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -ShowProperty Description: Only the specified properties will be shown by default. Supersedes ShowExcludeProperty. Type: String[] Parameter Sets: (All) Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -ShowExcludeProperty Description: Hides the specified properties from the default display style of the output object. Is ignored if used together with ShowProperty. Type: String[] Parameter Sets: (All) Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False Parameter: -TypeName Description: Adds a typename to the selected object. Will automatically prefix the module. Type: String Parameter Sets: (All) Required: False Position: Named Accept pipeline input: False Accept wildcard characters: False ``` -------------------------------- ### PSFramework New-PSFTeppCompletionResult Usage Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psf_tabexpansion.help.txt Demonstrates the usage of the New-PSFTeppCompletionResult cmdlet, which is used internally by tab expansion scriptblocks to format completion suggestions. It creates objects that PowerShell's tab expansion engine understands, including text and tooltips. ```PowerShell # Example usage within a ScriptBlock: New-PSFTeppCompletionResult -CompletionText 'name' -ToolTip 'name' ``` -------------------------------- ### PSFramework Cmdlet Parameters Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Write-PSFMessage.md This entry consolidates the documentation for various parameters used across PSFramework cmdlets, providing details on their functionality, types, and typical usage scenarios. ```APIDOC Write-PSFMessage Parameters: -Exception - Description: Allows specifying an inner exception as input object. This will be passed on to the logging and used for messages. When specifying both ErrorRecord AND Exception, Exception wins, but ErrorRecord is still used for record metadata. - Type: Exception - Required: False - Accept pipeline input: False -Once - Description: Setting this parameter will cause this function to write the message only once per session. The string passed here and the calling function's name are used to create a unique ID, which is then used to register the action in the configuration system. Thus will the lockout only be written if called once and not burden the system unduly. This lockout will be written as a hidden value, to see it use Get-PSFConfig -Force. - Type: String - Required: False - Accept pipeline input: False -OverrideExceptionMessage - Description: Disables automatic appending of exception messages. Use in cases where you already have a speaking message interpretation and do not need the original message. - Type: SwitchParameter - Required: False - Accept pipeline input: False -Target - Description: Add the object the message is all about, in order to simplify debugging / troubleshooting. For example, when calling this from a function targeting a remote computer, the computername could be specified here, allowing all messages to easily be correlated to the object processed. - Type: Object - Required: False - Accept pipeline input: False -EnableException - Description: This parameters disables user-friendly warnings and enables the throwing of exceptions. This is less user friendly, but allows catching exceptions in calling scripts. - Type: Boolean - Required: False - Accept pipeline input: False -Breakpoint - Description: The breakpoint switch enables breaking on this debug message. By default, Write-PSFMessage will not interrupt execution if the -Debug parameter is specified, even when writing to the debug stream. - Type: SwitchParameter - Required: False - Accept pipeline input: False -String - Description: The key to the localized message (omitting the module name). For more details on the PSFramework localization feature, see the help on Import-PSFLocalizedString. - Type: String - Required: True - Accept pipeline input: False -StringValues - Description: The values to format into the localized string defined. For more details on the PSFramework localization feature, see the help on Import-PSFLocalizedString. - Type: Object[] - Required: False - Accept pipeline input: False - Aliases: Format -NoNewLine - Description: Does not include a new line entry when writing a message to screen. Note: The message will still be logged as a single entry, even if you later add additional text. - Type: SwitchParameter - Required: False - Accept pipeline input: False -Data - Description: Specify additional data points that are furnished to the logging providers. Data provided may be arbitrary and will not be touched by the logging system itself. - Type: Hashtable - Required: False - Accept pipeline input: False - Aliases: Data -PSCmdlet - Description: The cmdlet object to use for writing errors. Offer the $PSCmdlet variable of the calling function for this parameter. - Type: PSCmdlet - Required: False - Accept pipeline input: False -ProgressAction - Description: {{ Fill ProgressAction Description }} - Type: ActionPreference - Required: False - Accept pipeline input: False - Aliases: proga CommonParameters: - Description: 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). ``` -------------------------------- ### Test-PSFShouldProcess Cmdlet Documentation Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Test-PSFShouldProcess.md Documentation for the PowerShell cmdlet Test-PSFShouldProcess, which implements the ShouldProcess question for PowerShell commands. It helps manage user confirmation prompts and allows for easier scripting and mocking of confirmation logic. ```APIDOC Test-PSFShouldProcess Cmdlet Documentation SYNOPSIS: Implements the shouldprocess question. SYNTAX: ### Message (Default) ```powershell Test-PSFShouldProcess -Target -Action [-PSCmdlet ] [-ProgressAction ] [-WhatIf] [-Confirm] [] ``` ### String ```powershell Test-PSFShouldProcess -Target -ActionString [-ActionStringValues ] [-PSCmdlet ] [-ProgressAction ] [-WhatIf] [-Confirm] [] ``` DESCRIPTION: This command can be used in other commands to implement the ShouldProcess question asked if using the command requires confirmation. This replaces / wraps the traditional ShouldProcess call, makes it easier to read in script and allows mocking it. EXAMPLES: ### Example 1: Basic Usage ```powershell if (Test-PSFShouldProcess -PSCmdlet $PSCmdlet -Target $item -Action "Performing some arbitrary action") { } ``` This will test whether the user should be prompted for confirmation, will do so if necessary and report back the results. PARAMETERS: ### -PSCmdlet The $PSCmdlet variable of the calling function. Used to ensure the actual prompt logic as intended is being used. ```yaml Type: PSCmdlet Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Target The target that is being processed. ```yaml Type: String Parameter Sets: (All) Aliases: Required: True Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Action The action that will be performed on the target. ```yaml Type: String Parameter Sets: Message Aliases: Required: True Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -ActionString Localized string of the action that will be performed on the target. Omit the modulename in the string. For more details on the PSFramework localization feature, see the help on Import-PSFLocalizedString. ```yaml Type: String Parameter Sets: String Aliases: Required: True Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -ActionStringValues Specify values to format into the localization string specified. For more details on the PSFramework localization feature, see the help on Import-PSFLocalizedString. ```yaml Type: Object[] Parameter Sets: String Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Confirm Prompts you for confirmation before running the cmdlet. ```yaml Type: SwitchParameter Parameter Sets: (All) Aliases: cf Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter Parameter Sets: (All) Aliases: wi Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -ProgressAction {{ Fill ProgressAction Description }} ```yaml Type: ActionPreference Parameter Sets: (All) Aliases: proga 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: OUTPUTS: NOTES: RELATED LINKS: [Online Documentation](https://psframework.org/documentation/commands/PSFramework/Test-PSFShouldProcess.html) ``` -------------------------------- ### Accessing PSFramework Internal Documentation Source: https://github.com/powershellframeworkcollective/psframework/blob/development/README.md Retrieves help information for all PSFramework-related cmdlets and concepts. This command is useful for understanding the module's functionality and exploring its features directly within PowerShell. ```powershell Get-Help about_psf* ``` -------------------------------- ### PSFramework Configuration Management Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psframework.help.txt Demonstrates basic usage of PSFramework configuration cmdlets for retrieving and updating settings. These cmdlets allow for self-documenting settings with input validation and change events, providing a centrally managed store for information. ```APIDOC Get-PSFConfig -FullName Retrieves an entire configuration element. Parameters: -FullName: The full name of the configuration element to retrieve. Set-PSFConfig -Name -Value Updates a configuration entry with a new value. Parameters: -Name: The name of the configuration entry to update. -Value: The new value for the configuration entry. Supports input validation. Example: # Update with valid value Set-PSFConfig -Name 'psframework.message.info.maximum' -Value 5 Example: # Update with invalid value (will trigger validation) Set-PSFConfig -Name 'psframework.message.info.maximum' -Value 'foo' Related Commands: - Get-PSFConfig: Retrieves configuration settings. - New-PSFConfig: (Not detailed here) Likely used for creating new configuration entries. ``` ```PowerShell # Retrieve entire configuration element Get-PSFConfig -FullName 'psframework.message.info.maximum' # Update with valid value Set-PSFConfig -Name 'psframework.message.info.maximum' -Value 5 # Update with invalid value Set-PSFConfig -Name 'psframework.message.info.maximum' -Value 'foo' ``` -------------------------------- ### PSFramework Tab Expansion ScriptBlock Parameters Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psf_tabexpansion.help.txt Details the parameters available within a PSFramework tab expansion ScriptBlock. These parameters provide crucial context, such as the command name, parameter name, and the text the user has typed so far, enabling dynamic completion suggestions. ```APIDOC ScriptBlock Parameters: - CommandName: The name of the command for which tab completion is being provided. Allows for context-aware completions. - ParameterName: The name of the specific parameter requiring tab completion. Useful for assigning the same completion logic to multiple parameters. - WordToComplete: The text the user has typed before triggering tab completion. Suggestions should typically start with this string. - CommandAst: Provides access to the Abstract Syntax Tree of the entire command line, offering deep insight into the command's structure. - FakeBoundParameters: Similar to $PSBoundParameters, this provides access to values already bound to parameters in the current command context. Note: Does not provide access to pipeline input. ``` -------------------------------- ### Register PSFTaskEngine Task (Interval) Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psf_taskengine.help.txt Shows how to register a task to run repeatedly at a specified interval with a delay before the first execution. This is suitable for recurring background maintenance or updates. ```powershell Register-PSFTaskEngineTask -Name 'mymodule.maintenance' -ScriptBlock $ScriptBlock -Interval "00:05:00" -Delay "00:01:00" -Priority Critical -Description 'Performs critical system maintenance in order for the mymodule module to function' ``` -------------------------------- ### PSFramework Task Engine Commands Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psf_taskengine.help.txt Provides a comprehensive list of commands for managing the PSFramework Task Engine, including registering, enabling, disabling, and retrieving task and cache information. These commands allow for background task execution, scheduling, and data exchange between tasks and the main runspace. ```APIDOC PSFramework Task Engine Commands: - Disable-PSFTaskEngineTask Disables a registered task in the Task Engine. - Enable-PSFTaskEngineTask Enables a registered task in the Task Engine. - Get-PSFTaskEngineCache Retrieves cache entries managed by the Task Engine. - Get-PSFTaskEngineTask Retrieves information about registered tasks. - Register-PSFTaskEngineTask Registers a new task with the Task Engine. Requires a unique name, a scriptblock to execute, and optionally a description, schedule (once or interval), delay, and priority. Example: Register-PSFTaskEngineTask -Name 'mymodule.buildcache' -ScriptBlock $ScriptBlock -Once -Description 'Builds the object cache used by the mymodule module' Example with interval and priority: Register-PSFTaskEngineTask -Name 'mymodule.maintenance' -ScriptBlock $ScriptBlock -Interval "00:05:00" -Delay "00:01:00" -Priority Critical -Description 'Performs critical system maintenance' - Set-PSFTaskEngineCache Sets a value in the Task Engine's cache. This allows background tasks to provide information back to the main runspace. Parameters: -Module: The module name associated with the cache entry. -Name: The name of the cache entry. -Value: The data to store in the cache. Example: Set-PSFTaskEngineCache -Module 'mymodule' -Name 'database-cache' -Value $results - Test-PSFTaskEngineCache Tests the availability or state of the Task Engine cache. - Test-PSFTaskEngineTask Tests the status or execution of a registered task. ``` -------------------------------- ### -Description Parameter Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Set-PSFConfig.md The -Description parameter allows users to provide a descriptive text for a configuration setting, enhancing clarity. It is a String type parameter applicable to all parameter sets. ```APIDOC -Description Using this, the configuration setting is given a description, making it easier for a user to comprehend, what a specific setting is for. Type: String Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` -------------------------------- ### Write-PSFMessage Cmdlet Parameters Source: https://github.com/powershellframeworkcollective/psframework/blob/development/help/en-us/Write-PSFMessage.md Comprehensive documentation for the parameters of the Write-PSFMessage cmdlet. This covers message content, verbosity levels, metadata overrides, error handling, and debugging integration. ```APIDOC Write-PSFMessage Purpose: Writes or logs messages with configurable verbosity and metadata. Parameters: -Level MessageLevel Description: The verbosity level of the message. Lower numbers indicate higher importance. Maps to output methods (Host, Verbose, Debug). Possible values: Critical (1), Important / Output / Host (2), Significant (3), VeryVerbose (4), Verbose (5), SomewhatVerbose (6), System (7), Debug (8), InternalComment (9), Warning (666). Required: False Default value: [PSFramework.Message.MessageLevel]::Verbose -Message String Description: The actual message content to write or log. Function name and timestamp are automatically prepended. Required: True Position: Named -Tag String[] Description: Tags to associate with the message for filtering and grouping. Required: False Position: Named -FunctionName String Description: The name of the calling function. Automatically set but can be overridden. Required: False Position: Named -ModuleName String Description: The name of the module the calling function belongs to. Automatically set but can be overridden. Required: False Position: Named -File String Description: The file where Write-PSFMessage was called. Automatically set but can be overridden. Required: False Position: Named -Line Int32 Description: The line number where Write-PSFMessage was called. Automatically set but can be overridden. Required: False Position: Named -ErrorRecord ErrorRecord[] Description: An ErrorRecord object to be noted with the message. Adds the error to the $Error variable and logging system. Required: False Position: Named -Breakpoint Description: When present, causes PowerShell to break into the debugger at this position if the command is run with the -Debug parameter. Required: False Position: Named ``` -------------------------------- ### PSFramework License Commands Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psf_license.help.txt Commands for managing the PSFramework license component. These cmdlets allow users to retrieve, create, and remove license information. ```APIDOC Get-PSFLicense - Retrieves information about the PSFramework license. - Parameters: - None specified in provided text. - Returns: - License details (type and format not specified). New-PSFLicense - Creates or updates a PSFramework license. - Parameters: - None specified in provided text. - Returns: - Status of license creation/update (type and format not specified). Remove-PSFLicense - Removes the PSFramework license. - Parameters: - None specified in provided text. - Returns: - Status of license removal (type and format not specified). ``` -------------------------------- ### PSFramework Logging System Overview Source: https://github.com/powershellframeworkcollective/psframework/blob/development/PSFramework/en-us/about_psf_message.help.txt Provides an overview of the PSFramework logging system's architecture, including its in-memory queue, logging queue, and logging script components. It explains how messages are handled, stored, and processed. ```APIDOC PSFramework Logging System Architecture: Components: - In-memory queue: Stores all messages and exceptions. It is self-limiting, removing the oldest entry when capacity is exceeded. Messages are tagged by runspace ID for parallel processing troubleshooting. - Logging queue: A set of queues where messages and exceptions are also added. These have a more generous maximum capacity and should not accumulate much data as the logging script collects them frequently. - Logging script: Gathers information from the logging queue and logs them. Currently supports filesystem logging, with plans for additional providers. Operated by the module's runspace component. Key Functions: - Get-PSFMessage: Retrieves information from the in-memory queue. - Write-PSFHostColor: A command for building menus or head messages, essentially the function used by Write-PSFMessage for final colorful output. ``` -------------------------------- ### PSFramework Postimport File List Source: https://github.com/powershellframeworkcollective/psframework/blob/development/build/filesBefore.txt Lists the files executed by the postimport.ps1 script in the PSFramework project, in the order they are loaded. These files define the core environment and code for the framework. ```powershell bin\assembly.ps1 internal\scripts\environment.ps1 internal\scripts\teppCoreCode.ps1 ```