PSFramework

PSFramework is a toolkit designed to speed up PowerShell development and improve code manageability by providing solutions for generic scripting challenges. Its core components include:

• Configuration: Self-documenting settings with input validation and change events.
• Flow Control: Managed exception handling and termination for modules.
• License: Centralized registration of product licenses.
• Message: A powerful, asynchronous logging system.
• Result Cache: Caching function outputs to allow retrieval even if not stored in a variable.
• Runspace: A system for managing named runspaces that prevents multiple parallel executions of the same task.

The PSFramework Result Cache component allows you to store and retrieve the results of expensive operations (such as API calls or complex computations) to improve performance. You can manage the cache using the following core commands:

• Set-PSFResultCache: Stores a value or object in the cache.
• Get-PSFResultCache: Retrieves a previously stored value from the cache.
• Clear-PSFResultCache: Removes items from the cache.

When a breaking change is necessary (e.g., to improve performance or reduce environmental impact), PSFramework follows a transparent, multi-stage process:

1. RFC (Request for Comments): An issue is posted describing the change and its benefits. It remains open for discussion for three months.
2. Pending Change: If no convincing arguments against the change are raised during the RFC period, the change is marked as 'Pending'.
3. Deprecation: The old way of operating is declared deprecated. Affected features will trigger warnings when the deprecated method is used.
4. Warning Mechanism: On Windows systems, using deprecated functionality generates a PowerShell Eventlog warning (ID: 666; Category: 1; EntryType: Warning; Source: PowerShell).
5. Implementation: The breaking change is implemented nine months after the RFC is approved.

You can perform a simple property-matching join between your current pipeline objects and another variable. This allows you to pull data from a secondary list based on a matching property value.

Syntax: "<PropertyFromOtherObject> from <VariableName> WHERE <OtherObjectProperty> = <CurrentObjectProperty>"

Note: Currently only supports simple property-matching.

$list = @()
$list += [PSCustomObject]@{ Type = "Foo"; ID = 1 }
$list += [PSCustomObject]@{ Type = "Bar"; ID = 2 }

# Selects Name from $obj, and for each, finds the ID from $list where Type matches Name
$obj | Select-PSFObject Name, "ID from list WHERE Type = Name"

The -Inherit switch allows the cmdlet to substitute missing keys (specified in -Include) with values from variables in the caller's scope that share the same name. This is specifically designed to allow inheriting default parameter values when cloning $PSBoundParameters.

$parameters = $PSBoundParameters | ConvertTo-PSFHashtable -Include ComputerName, Credential, Target -Inherit

Flow Control is designed for module developers to create user-friendly error handling. It allows you to:

• Integrate error handling directly into your logging system.
• Manage how functions terminate.
• Suppress exceptions from end-users while providing opt-in mechanisms for scripters who need to catch them.

The PSFramework Flow Control component provides mechanisms to signal and test for interruptions within functions. This allows you to implement graceful exits or pause processing when a stop signal is received.

Key commands:

• Stop-PSFFunction: Signals that the current function should stop execution.
• Test-PSFFunctionInterrupt: Checks if a stop signal has been issued for the current function context.

To ensure optimal import performance, projects should contain only one Format XML file and one Type Extension XML file. Use the following specific filenames:

• Format XML: PSFramework.Format.ps1xml
• Type Extension XML: PSFramework.Types.ps1xml

Note: Do not place external help files in the XML folder.