Improves error handling for Framework initialising and plugin execution

Fixes #95

doc/30-upgrading-framework.md

@@ -4,7 +4,19 @@ Upgrading Icinga PowerShell Framework is usually quite straightforward.
 
 Specific version upgrades are described below. Please note that version updates are incremental.
 
-## Upgrading to v1.1.0 (pending)
+## Upgrading to v1.2.0 (pending)
+
+### Behavior changes
+
+#### Changes on check command execution
+
+As mentioned in [#95](https://github.com/Icinga/icinga-powershell-framework/issues/95) we should make sure that in case the Framework itself is not installed on a system or plugins are missing the user is informed about this. We do how ever not intend to print huge stack traces of PowerShell errors into the console, but inform in a minimalistic way about this.
+
+For this reason we will cover with a Try-Catch statement if the `Use-Icinga` command is executed and return a proper message and error code on failures. In addition we will now check of a plugin is installed before the execution of it, ensuring that in case it is not present on the system we receive an `Unknown` message that a certain plugin is not installed or present.
+
+To apply this new behaviour you will have to generate a new check command basket file for the Icinga Director by using `Get-IcingaCheckCommandConfig` and import the new version. Once imported and deployed, the new handling will be in effect.
+
+## Upgrading to v1.1.0 (2020-06-02)
 
 ### Behavior changes
 

doc/31-Changelog.md

@@ -11,6 +11,10 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 
 [Issue and PRs](https://github.com/Icinga/icinga-powershell-framework/milestone/7?closed=1)
 
+### Upgrading Notes
+
+* To properly catch errors on check execution you will have to import check commands as Director basket again by using `Get-IcingaCheckCommandConfig`. Further details can be found in the [upgrading docs](30-upgrading-framework.md)
+
 ### Notes
 
 * [#80](https://github.com/Icinga/icinga-powershell-framework/issues/80) Adds wrapper function `Get-IcingaWindowsInformation` for WMI and CIM calls to properly handle config/permission errors
@@ -22,6 +26,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 * [#87](https://github.com/Icinga/icinga-powershell-framework/issues/87) Adds wrapper command to test new code or functionality of Framework and/or plugins
 * [#88](https://github.com/Icinga/icinga-powershell-framework/issues/88) Adds Start/Stop timer functionality for performance analysis
 * [#94](https://github.com/Icinga/icinga-powershell-framework/issues/94) Adds `Namespace` argument for Get-IcingaWindowsInformation for additional filtering
+* [#95](https://github.com/Icinga/icinga-powershell-framework/issues/95) Improves error handling for issues by using `Use-Icinga` initialising or by calling plugins which are not installed
 
 ### Bugfixes
 

lib/core/tools/Get-IcingaCheckCommandConfig.psm1

@@ -114,7 +114,7 @@ function Get-IcingaCheckCommandConfig()
                 'arguments'   = @{
                     # Set the Command handling for every check command
                     '-C' = @{
-                        'value' = [string]::Format('Use-Icinga; exit {0}', $Data.Name);
+                        'value' = [string]::Format('try {{ Use-Icinga; }} catch {{ Write-Output {1}The Icinga PowerShell Framework is either not installed on the system or not configured properly. Please check https://icinga.com/docs/windows for further details{1}; exit 3; }}; Exit-IcingaPluginNotInstalled {1}{0}{1}; exit {0}', $Data.Name, "'");
                         'order' = '0';
                     }
                 }

lib/icinga/exception/Exit-IcingaPluginNotInstalled.psm1

@@ -0,0 +1,37 @@
+<#
+.SYNOPSIS
+    Tests if a provided command is available on the system and exists
+    the shell with an Unknown error and a message. Required to properly
+    handle Icinga checks and possible error displaying inside Icinga Web 2
+.DESCRIPTION
+    Tests if a provided command is available on the system and exists
+    the shell with an Unknown error and a message. Required to properly
+    handle Icinga checks and possible error displaying inside Icinga Web 2
+.FUNCTIONALITY
+    Tests if a provided command is available on the system and exists
+    the shell with an Unknown error and a message. Required to properly
+    handle Icinga checks and possible error displaying inside Icinga Web 2
+.EXAMPLE
+    PS>Exit-IcingaPluginNotInstalled -Command 'Invoke-IcingaCheckCPU';
+.PARAMETER Command
+    The name of the check command to test for
+.INPUTS
+    System.String
+.LINK
+    https://github.com/Icinga/icinga-powershell-framework
+#>
+
+function Exit-IcingaPluginNotInstalled()
+{
+    param (
+        $Command
+    );
+
+    if ([string]::IsNullOrEmpty($Command)) {
+        Exit-IcingaThrowException -CustomMessage 'Null-Command' -ExceptionType 'Configuration' -ExceptionThrown $IcingaExceptions.Configuration.PluginNotAssigned -Force;
+    }
+
+    if ($null -eq (Get-Command $Command -ErrorAction SilentlyContinue)) {
+        Exit-IcingaThrowException -CustomMessage $Command -ExceptionType 'Configuration' -ExceptionThrown $IcingaExceptions.Configuration.PluginNotInstalled -Force;
+    }
+}

lib/icinga/exception/Icinga_IcingaExceptionEnums.psm1

@@ -22,7 +22,9 @@
 
 [hashtable]$Configuration = @{
     PluginArgumentConflict = 'Your plugin argument configuration is causing a conflict. Mostly this error is caused by missmatching configurations by enabling multiple switch arguments which are resulting in a conflicting configuration for the plugin.';
-    PluginArgumentmissing  = 'Your plugin argument configuration is missing mandatory arguments. This is error is caused when mandatory or required arguments are missing from a plugin call and the operation is unable to process without them.';
+    PluginArgumentMissing  = 'Your plugin argument configuration is missing mandatory arguments. This is error is caused when mandatory or required arguments are missing from a plugin call and the operation is unable to process without them.';
+    PluginNotInstalled     = 'The plugin assigned to this service check seems not to be installed on this machine. Please review your service check configuration for spelling errors and check if the plugin is installed and executable on this machine by PowerShell.';
+    PluginNotAssigned      = 'Your check for this service could not be processed because it seems like no valid Cmdlet was assigned to the check command. Please review your check command to ensure that a valid Cmdlet is assigned and executed by a PowerShell call.';
 }
 
 <#