Adds wrapper command for easier testing of code

Fixes #87

doc/04-Developer-Guide.md

@@ -21,6 +21,7 @@ There are some general guidelines, functions and toolsets available making the d
 
 * [Cim-Instance/Wmi-Object fetching](developerguide/50-Fetching-Cim_and_Wmi_Data.md)
 * [Working with Performance Counters](developerguide/51-Working-with-Performance-Counters.md)
+* [Testing of Commands](developerguide/52-Testing-of-Commands.md)
 
 Example Usage
 ---

doc/31-Changelog.md

@@ -19,6 +19,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 
 * Adds new Cmdlet `Show-IcingaPerformanceCounterInstances` to display all available instances for Performance Counters
 * [#76](https://github.com/Icinga/icinga-powershell-framework/issues/76) Adds support to test for required .NET Framework Version 4.6.0 or above before trying to install the Icinga Agent
+* [#87](https://github.com/Icinga/icinga-powershell-framework/issues/87) Adds wrapper command to test new code or functionality of Framework and/or plugins
 
 ### Bugfixes
 

doc/developerguide/52-Testing-of-Commands.md

@@ -0,0 +1,65 @@
+# Developer Guide: Testing of Commands
+
+Actively developing new code for the Framework will result in core files to be changed or new functionality added. To load the Framework we use in general `Use-Icinga`, which does how ever not cover changes we made afterwards. To keep track of the changes for new features or while testing something, we always have to open a new PowerShell instance.
+
+To make things more usable, we can of course run a PowerShell command directly from our shell:
+
+```powershell
+powershell -C { Use-Icinga; <# your code #> }
+```
+
+While this is straight forward and easy to use, the idea is to make this way simpler.
+
+## Invoke-IcingaCommand or simply icinga
+
+Instead of having to write a long command for testing, you can use the newly introduced Cmdlet `Invoke-IcingaCommand` with PowerShell Framework 1.2.0. To make it even easier, we created an alias for this: `icinga`
+
+To test new commands, features or to simply troubleshoot you can now simply type `icinga` followed by `{ }` containing your code:
+
+```powershell
+icinga { <# your code #> }
+```
+
+One easy example is to simply print console output;
+
+```powershell
+icinga { Write-IcingaConsoleError 'Hello from Icinga' }
+```
+
+```text
+[Error]: Hello from Icinga
+```
+
+The command will load the entire Framework and all components and output the result of your code.
+
+## Improved Shell handling
+
+In addition to above mentioned example, you can not only execute code snippets but also start a new PowerShell with the entire Framework loaded. The benefit of this is, that while mostly an `exit` should be handled, it might still cause your shell to close. With the `icinga` command, you will only close an additional shell and keep your own shell open:
+
+```powershell
+C:\Users> icinga
+icinga>
+```
+
+Now you can type in your commands as you would on any other PowerShell - how ever, this is a new instance so in case we close it, we still have our shell open:
+
+```powershell
+icinga> Exit-IcingaThrowException -Force -CustomMessage 'Force Exit of our Shell with an exception';
+[UNKNOWN]: Icinga Unhandled Error was thrown: Unhandled Exception: Force Exit of our Shell with an exception
+
+Unhandled exception occured:
+```
+
+Instead of our own shell closing, we still have our previous one open and can start another shell by using `icinga` with the entire Framework loaded.
+
+This also works for code we directly invoke to the `icinga` alias:
+
+```powershell
+icinga { Exit-IcingaThrowException -Force -CustomMessage 'Force Exit of our Shell with an exception'; }
+```
+
+```text
+[UNKNOWN]: Icinga Unhandled Error was thrown: Unhandled Exception: Force Exit of our Shell with an exception
+
+Unhandled exception occured:
+```

icinga-powershell-framework.psd1

@@ -7,10 +7,10 @@
     Copyright = '(c) 2020 Icinga GmbH | MIT'
     Description = 'Icinga for Windows module which allows to entirely monitor the Windows Host system.'
     PowerShellVersion = '4.0'
-    FunctionsToExport = @( 'Use-Icinga', 'Import-IcingaLib', 'Publish-IcingaModuleManifests', 'Publish-IcingaEventlogDocumentation', 'Get-IcingaPluginDir', 'Get-IcingaCustomPluginDir', 'Get-IcingaCacheDir', 'Get-IcingaPowerShellConfigDir', 'Get-IcingaFrameworkRootPath', 'Get-IcingaPowerShellModuleFile' )
+    FunctionsToExport = @( 'Use-Icinga', 'Invoke-IcingaCommand', 'Import-IcingaLib', 'Publish-IcingaModuleManifests', 'Publish-IcingaEventlogDocumentation', 'Get-IcingaPluginDir', 'Get-IcingaCustomPluginDir', 'Get-IcingaCacheDir', 'Get-IcingaPowerShellConfigDir', 'Get-IcingaFrameworkRootPath', 'Get-IcingaPowerShellModuleFile' )
     CmdletsToExport = @()
     VariablesToExport = '*'
-    AliasesToExport = @()
+    AliasesToExport = @( 'icinga' )
     PrivateData = @{
         PSData = @{
             Tags = @( 'icinga','icinga2','IcingaPowerShellFramework','IcingaPowerShell','IcingaforWindows','IcingaWindows')

icinga-powershell-framework.psm1

@@ -260,3 +260,29 @@ function Get-IcingaPowerShellModuleFile()
 {
     return (Join-Path -Path $PSScriptRoot -ChildPath 'icinga-powershell-framework.psm1');
 }
+
+function Invoke-IcingaCommand()
+{
+    [CmdletBinding()]
+    param (
+        $ScriptBlock
+    );
+
+    powershell.exe -NoExit -Command {
+        $Script = $args[0]
+        Use-Icinga;
+
+        if ([string]::IsNullOrEmpty($Script) -eq $FALSE) {
+            Invoke-Command -ScriptBlock ([Scriptblock]::Create($Script));
+            exit $LASTEXITCODE;
+        }
+        # Set our "path" to something different so we know that we loaded the Framework
+        function prompt {
+            Write-Host -Object "icinga" -NoNewline;
+            return "> "
+        }
+
+    } -Args $ScriptBlock;
+}
+
+Set-Alias icinga Invoke-IcingaCommand -Description "Execute Icinga Framework commands in a new PowerShell instance for testing or quick access to data";