Merge pull request #203 from Icinga:doc/adds_code_cache_docs

Adds code caching docs and removes experimental

Removes experimental state of the Icinga PowerShell Framework code caching and adds docs on how to use the feature

doc/06-Framework-Usage.md

@@ -8,6 +8,7 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
 * [Enable Proxy Server](frameworkusage/02-Enable-Proxy-Server.md)
 * [Install Wizard Guide](frameworkusage/03-Install-Wizard-Guide.md)
 * [Disable Certificate Validation](frameworkusage/04-Disable-Certificate-Validation.md)
+* [Enable Framework Code Caching](frameworkusage/05-Enable-Framework-Code-Caching.md)
 
 ## Icinga Agent Management
 

doc/31-Changelog.md

@@ -15,6 +15,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 
 * [#193](https://github.com/Icinga/icinga-powershell-framework/pull/193) Adds optional support for adding milliseconds to `Get-IcingaUnixTime` with the `-Milliseconds` argument for more detailed time comparison
 * [#198](https://github.com/Icinga/icinga-powershell-framework/pull/198) Adds support to flush the content of the Icinga Agent API directory with a single Cmdlet `Clear-IcingaAgentApiDirectory`
+* [#203](https://github.com/Icinga/icinga-powershell-framework/pull/203) Removes experimental state of the Icinga PowerShell Framework code caching and adds docs on how to use the feature
 
 ## 1.3.1 (2021-02-04)
 

doc/frameworkusage/05-Enable-Framework-Code-Caching.md

@@ -0,0 +1,45 @@
+# Enable Framework Code Caching
+
+On certain systems with fewer CPU cores, there might be an impact while running Icinga for Windows because of long loading times for the Icinga PowerShell Framework. To mitigate this issue, we added the possibility to create a code cache file for the entire Icinga PowerShell Framework.
+
+What it does is to load every single module and content file into one single `cache.psm1` file which is loaded in case the caching is enabled.
+
+## Pre-Cautions
+
+By enabling this feature, you will have to generate a new cache file whenever you apply changes to any code for the Icinga PowerShell Framework. This can be done by running the Cmdlet
+
+```powershell
+Write-IcingaFrameworkCodeCache
+```
+
+Please note that the code cache feature must be enabled first.
+
+In case you upgrade to a newer version of the Icinga PowerShell Framework, you will only require to manually proceed in case the code cache feature was disabled beforehand. In case the code cache feature is enabled during the upgrade, the cache file will be generated and updated automatically.
+
+## Enable Icinga Framework Code Cache
+
+To enable the Icinga PowerShell Framework code cache, simply run the following command within an Icinga Shell:
+
+```powershell
+Enable-IcingaFrameworkCodeCache
+```
+
+Once activated, you should make sure to generate a new cache file before using the Framework:
+
+```powershell
+Write-IcingaFrameworkCodeCache
+```
+
+If you leave the code caching feature enabled, future updates of the Framework will automatically generate a new cache file. If you disabled the feature in-between, please write the cache file manually.
+
+In case no cache file is present while the feature is activated, a cache file is generated on the first use of `Use-Icinga` or `icinga`.
+
+## Disable Icinga Framework Code Cache
+
+To disable the code caching feature again, you can simply run
+
+```powershell
+Disable-IcingaFrameworkCodeCache
+```
+
+Please note that even though the cache file is no longer loaded it still remains. Therefor you will have to manually use `Write-IcingaFrameworkCodeCache` in case you activate the feature later again. This is especially required if you update the Icinga PowerShell Framework while the feature was disabled.

icinga-powershell-framework.psm1

@@ -93,7 +93,7 @@ function Write-IcingaFrameworkCodeCache()
     if (Get-IcingaFrameworkCodeCache) {
         Import-IcingaLib '\' -Init -CompileCache;
     } else {
-        Write-IcingaConsoleNotice 'The experimental code caching feature is currently not enabled. You can enable it with "Enable-IcingaFrameworkCodeCache"';
+        Write-IcingaConsoleNotice 'The code caching feature is currently not enabled. You can enable it with "Enable-IcingaFrameworkCodeCache"';
     }
 }
 
@@ -332,7 +332,7 @@ function Invoke-IcingaCommand()
         Write-Output ([string]::Format('** Copyright {0}', $IcingaFrameworkData.Copyright));
         Write-Output ([string]::Format('** User environment {0}\{1}', $env:USERDOMAIN, $env:USERNAME));
         if (Get-IcingaFrameworkCodeCache) {
-            Write-Output ([string]::Format('** Warning: Icinga Framework Code Caching is enabled'));
+            Write-Output ([string]::Format('** Note: Icinga Framework Code Caching is enabled'));
         }
         Write-Output '******************************************************';
     }

lib/core/framework/Disable-IcingaFrameworkCodeCache.psm1

@@ -1,12 +1,12 @@
 <#
 .SYNOPSIS
-   Disables the experimental feature to cache all functions into a single file,
+   Disables the feature to cache all functions into a single file,
    allowing quicker loading times of the Icinga PowerShell Framework
 .DESCRIPTION
-   Disables the experimental feature to cache all functions into a single file,
+   Disables the feature to cache all functions into a single file,
    allowing quicker loading times of the Icinga PowerShell Framework
 .FUNCTIONALITY
-   Experimental: Disables the Icinga for Windows code caching
+   Disables the Icinga for Windows code caching
 .EXAMPLE
    PS>Disable-IcingaFrameworkCodeCache;
 .LINK
@@ -15,5 +15,5 @@
 
 function Disable-IcingaFrameworkCodeCache()
 {
-    Set-IcingaPowerShellConfig -Path 'Framework.Experimental.CodeCaching' -Value $FALSE;
+    Set-IcingaPowerShellConfig -Path 'Framework.CodeCaching' -Value $FALSE;
 }

lib/core/framework/Enable-IcingaFrameworkCodeCache.psm1

@@ -1,12 +1,12 @@
 <#
 .SYNOPSIS
-   Enables the experimental feature to cache all functions into a single file,
+   Enables the feature to cache all functions into a single file,
    allowing quicker loading times of the Icinga PowerShell Framework
 .DESCRIPTION
-   Enables the experimental feature to cache all functions into a single file,
+   Enables the feature to cache all functions into a single file,
    allowing quicker loading times of the Icinga PowerShell Framework
 .FUNCTIONALITY
-   Experimental: Enables the Icinga for Windows code caching
+   Enables the Icinga for Windows code caching
 .EXAMPLE
    PS>Enable-IcingaFrameworkCodeCache;
 .LINK
@@ -15,7 +15,7 @@
 
 function Enable-IcingaFrameworkCodeCache()
 {
-    Set-IcingaPowerShellConfig -Path 'Framework.Experimental.CodeCaching' -Value $TRUE;
+    Set-IcingaPowerShellConfig -Path 'Framework.CodeCaching' -Value $TRUE;
 
-    Write-IcingaConsoleWarning 'This is an experimental feature and might cause some side effects during usage. Please use this function with caution. Please run "Write-IcingaFrameworkCodeCache" in addition to ensure your cache is updated. This should be done after each update of the Framework in case the feature was disabled during the update run.';
+    Write-IcingaConsoleWarning 'Please run "Write-IcingaFrameworkCodeCache" in addition to ensure your cache is updated. This should be done after each update of the Framework in case the feature was disabled during the update run.';
 }

lib/core/framework/Get-IcingaFrameworkCodeCache.psm1

@@ -1,12 +1,12 @@
 <#
 .SYNOPSIS
-   Fetches the current enable/disable state of the experimental feature
+   Fetches the current enable/disable state of the feature
    for caching the Icinga PowerShell Framework code
 .DESCRIPTION
-   Fetches the current enable/disable state of the experimental feature
+   Fetches the current enable/disable state of the feature
    for caching the Icinga PowerShell Framework code
 .FUNCTIONALITY
-   Experimental: Get the current code caching configuration of the
+   Get the current code caching configuration of the
    Icinga PowerShell Framework
 .EXAMPLE
    PS>Get-IcingaFrameworkCodeCache;
@@ -18,7 +18,7 @@
 
 function Get-IcingaFrameworkCodeCache()
 {
-    $CodeCaching = Get-IcingaPowerShellConfig -Path 'Framework.Experimental.CodeCaching';
+    $CodeCaching = Get-IcingaPowerShellConfig -Path 'Framework.CodeCaching';
 
     if ($null -eq $CodeCaching) {
         return $FALSE;