diff --git a/doc/04-Developer-Guide.md b/doc/04-Developer-Guide.md index e49a12f..0d7d290 100644 --- a/doc/04-Developer-Guide.md +++ b/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 --- diff --git a/doc/31-Changelog.md b/doc/31-Changelog.md index 035f8de..a41413b 100644 --- a/doc/31-Changelog.md +++ b/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 diff --git a/doc/developerguide/52-Testing-of-Commands.md b/doc/developerguide/52-Testing-of-Commands.md new file mode 100644 index 0000000..d7e19f4 --- /dev/null +++ b/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: +``` diff --git a/icinga-powershell-framework.psd1 b/icinga-powershell-framework.psd1 index 9ecc0f0..09b8606 100644 --- a/icinga-powershell-framework.psd1 +++ b/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') diff --git a/icinga-powershell-framework.psm1 b/icinga-powershell-framework.psm1 index 27b0b7d..d3c2ed9 100644 --- a/icinga-powershell-framework.psm1 +++ b/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";