en-us/about_psframework.help.txt

1
2
3
4
5
6
7
8
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