en-us/about_PSFramework.help.txt
|
TOPIC
about_psframework SHORT DESCRIPTION Gives an overview over the components that make up the PSFramework LONG DESCRIPTION Note: All documentation has been moved to the project's website: https://psframework.org Future content can be found there exclusively. When scripting for our everyday work, we often end up doing two things: - Implement the same functionality again and again (Example: Logging), because it either isn't worth the effort or we simply don't have the time to do it right, once. - Think "Wouldn't it be cool to have this feature?", then get back into the reality of deadlines and overwork While there is probably no way an outsider can help you with company- specific challenges, this framework is designed to bring you a rich toolkit to deal with the generic scripting issues. Its two main goals in specific are: - Speed up your development, by providing a solid framework of tools to build upon - Provide a manageability to your code The module consists of several component parts: - Configuration : Provide self-documenting settings with input validation and change events - Flow Control : Designed for modules, provide a managed way to handle exceptions and how they are presented to the user - License : Centralize license registration - Message : Powerful logging system, gives flexible control over what message goes where - Result Cache : Allows caching the output of a function, enabling access to its contents, even when the user forgot to store the output in a variable - Runspace : A system that manages runspaces in a peculiar fashion: It guarantees that there is a single copy of the runspace you start #-------------------------------------------------------------------------# # Configuration # #-------------------------------------------------------------------------# Main Article: https://psframework.org/documentation/documents/psframework/configuration.html Key Benefits: - Avoid hardcoding information - Selfdocumented settings that carry their own validation and reaction to change The configuration system is a system designed to store and retrieve settings. On the surface it has similarities to variables, in that it maps names to values. However, there are a few key differences: - No scopes: The same value is the same value. Always - Shared across runspaces: All runspaces have access to the same data - Documented: Each setting can contain a description of what it does - Input Validation: Each setting can flexibly validate its changes - Update events: Changes in value can trigger scriptblocks in response This makes it particularly apt at centrally storing and revealing information that would otherwise have been hardcoded somewhere. A few Examples that will show the basic usage: # 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' While manipulating existing configuration entries is simple, creating new ones is slightly more involved, for which it is recommended to read the full article on the configuration system first. #-------------------------------------------------------------------------# # Flow Control # #-------------------------------------------------------------------------# Main Article: Get-Help about_psf_flowcontrol Key Benefits: - Integrate error handling into logging - Manage function termination - Hide exceptions from users but make them available to scripters The target audience for this feature are module developers that want to make using their modules more userfriendly. It provides tools to uniformly suppress exceptions but provide opt-in mechanisms for cases where exceptions rather than warnings are needed. The basic issue this component tries to solve, is the fact that beginners will not process and understand exceptions, but removing them completely brings issues with scripts (which no longer can use try/catch). This is the compromise, bringing exceptions via opt-in. #-------------------------------------------------------------------------# # License # #-------------------------------------------------------------------------# Main Article: Get-Help about_psf_license Key Benefits: - Provide central, manageable store for license of used products The license system allows a module to easily register the license terms for itself and component it uses in a central location. This makes it easier to discover what licenses are currently in use, as it no longer is necessary to parse directories for license texts. #-------------------------------------------------------------------------# # Message / Logging # #-------------------------------------------------------------------------# Main Article: Get-Help about_psf_message Key Benefits: - Easy logging / log management - Logging with automatic logrotate - Configurable and manageable logging - Configurable and manageable script verbosity - Enhanced debugging tools When importing this module for first time in a process, it will start a runspace in the background that will perform the logging. This allows all logging to be performed independent of the function/script that wants to log something, removing disk I/O as a bottleneck. Adopting this system is trivially simple: # Previous code: Write-Host "Some text" Write-Verbose "Some verbose text" # New code: Write-PSFMessage -Level Host -Message "Some text" Write-PSFMessage -Level Verbose -Message "Some verbose text" This will cause the same message to be written to host or verbose respectively. They will also be queued for logging. It is possible to dig much deeper and discover the deep debugging features integrated into this system, but simply replacing your common message handling calls (see above example) is all it takes to get started with benefiting from this component. #-------------------------------------------------------------------------# # Result Cache # #-------------------------------------------------------------------------# Main Article: Get-Help about_psf_resultcache Key Benefits: - Cache the last result in a uniform way - Improve user experience by forgiving forgetting to store results in variables This provides a standardized way to 'remember' the last output of a command. Often PowerShell users forget to save the output in a variable. In case of lengthy queries, this could introduce a long wait that was not necessary, when the information is still needed after all. If the command was a function that changes things, it may not even be possible to repeat the execution. In cases like that, having the original output still available helps. This must be implemented in the function that is generating the output, by calling the function 'Set-PSFResultCache'. Retrieving the information for the user is as simple as calling 'glr', the alias for 'Get-PSFResultCache'. #-------------------------------------------------------------------------# # Runspace # #-------------------------------------------------------------------------# Main Article: Get-Help about_psf_runspace Key Benefits: - Manages named runspaces for background tasks - Prevents multiple copies being executed in parallel This component runs a script in parallel to the main code execution. This script must be registered by name, the system will prevent multiple copies to be executed in parallel. This allows a module to create a maintenance script that will run in parallel, without: - Having to implement this parallelism. - Having to worry about multiple copies to run in parallel (so issues such as conflicts when accessing a file are avoided) - Having to worry about doubling the number of runspaces when the module is used in parallel operations. KEYWORDS psframework |