From 00990c52e1f9e32a18cbdfb1f98ec04cc25180eb Mon Sep 17 00:00:00 2001 From: Lord Hepipud Date: Tue, 28 Apr 2020 14:06:43 +0200 Subject: [PATCH] Adds documentation for several Cmdlets --- lib/core/cache/Get-IcingaCacheData.psm1 | 26 ++++++++++++++ lib/core/cache/Set-IcingaCacheData.psm1 | 27 ++++++++++++++ lib/core/framework/Copy-ItemSecure.psm1 | 27 ++++++++++++++ .../framework/Expand-IcingaZipArchive.psm1 | 21 +++++++++++ .../Get-IcingaFrameworkServiceBinary.psm1 | 26 ++++++++++++++ .../Get-IcingaPowerShellModuleArchive.psm1 | 36 +++++++++++++++++++ .../Get-IcingaPowerShellModuleVersion.psm1 | 21 +++++++++++ 7 files changed, 184 insertions(+) diff --git a/lib/core/cache/Get-IcingaCacheData.psm1 b/lib/core/cache/Get-IcingaCacheData.psm1 index 27b09d9..19225a2 100644 --- a/lib/core/cache/Get-IcingaCacheData.psm1 +++ b/lib/core/cache/Get-IcingaCacheData.psm1 @@ -1,3 +1,29 @@ +<# +.SYNOPSIS + Reads data from a cache file of the Framework and returns its content +.DESCRIPTION + Allows a developer to read data from certain cache files to either speed up + loading procedures, to store content to not lose data on restarts of a daemon + or to build data tables over time +.FUNCTIONALITY + Returns cached data for specific content +.EXAMPLE + PS>Get-IcingaCacheData -Space 'sc_daemon' -CacheStore 'checkresult_store' -KeyName 'Invoke-IcingaCheckCPU'; +.PARAMETER Space + The individual space to read from. This is targeted to a folder the cache data is written to under icinga-powershell-framework/cache/ +.PARAMETER CacheStore + This is targeted to a sub-folder under icinga-powershell-framework/cache// +.PARAMETER KeyName + This is the actual cache file located under icinga-powershell-framework/cache///.json + Please note to only provide the name without the '.json' apendix. This is done by the module itself +.INPUTS + System.String +.OUTPUTS + System.Object +.LINK + https://github.com/Icinga/icinga-powershell-framework +.NOTES +#> function Get-IcingaCacheData() { param( diff --git a/lib/core/cache/Set-IcingaCacheData.psm1 b/lib/core/cache/Set-IcingaCacheData.psm1 index bdf3a36..bb6c81b 100644 --- a/lib/core/cache/Set-IcingaCacheData.psm1 +++ b/lib/core/cache/Set-IcingaCacheData.psm1 @@ -1,3 +1,30 @@ +<# +.SYNOPSIS + Writes data to a cache file for the Framework +.DESCRIPTION + Allows a developer to write data to certain cache files to either speed up + loading procedures, to store content to not lose data on restarts of a daemon + or to build data tables over time +.FUNCTIONALITY + Writes data for specific value to a cache file +.EXAMPLE + PS>Set-IcingaCacheData -Space 'sc_daemon' -CacheStore 'checkresult_store' -KeyName 'Invoke-IcingaCheckCPU' -Value @{ 'CachedData' = 'MyValue' }; +.PARAMETER Space + The individual space to write to. This is targeted to a folder the cache data is written to under icinga-powershell-framework/cache/ +.PARAMETER CacheStore + This is targeted to a sub-folder under icinga-powershell-framework/cache// +.PARAMETER KeyName + This is the actual cache file located under icinga-powershell-framework/cache///.json + Please note to only provide the name without the '.json' apendix. This is done by the module itself +.PARAMETER Value + The actual value to store within the cache file. This can be any kind of value, as long as it is convertable to JSON +.INPUTS + System.String +.LINK + https://github.com/Icinga/icinga-powershell-framework +.NOTES +#> + function Set-IcingaCacheData() { param( diff --git a/lib/core/framework/Copy-ItemSecure.psm1 b/lib/core/framework/Copy-ItemSecure.psm1 index 9641a29..3085785 100644 --- a/lib/core/framework/Copy-ItemSecure.psm1 +++ b/lib/core/framework/Copy-ItemSecure.psm1 @@ -1,3 +1,30 @@ +<# +.SYNOPSIS + A more secure way to copy items from one location to another including error handling +.DESCRIPTION + Wrapper for the Copy-Item Cmdlet to more securely copy items with error + handling to prevent interuptions during actions +.FUNCTIONALITY + Copies items from a source to a destination location +.EXAMPLE + PS>Copy-ItemSecure -Path 'C:\users\public\test.txt' -Destination 'C:\users\public\text2.txt'; +.EXAMPLE + PS>Copy-ItemSecure -Path 'C:\users\public\testfolder\' -Destination 'C:\users\public\testfolder2\' -Recurse; +.PARAMETER Path + The location you wish to copy from. Can either be a file or a directory +.PARAMETER Destination + The target destination to copy to. Can either be a file or a directory +.PARAMETER Recurse + Include possible sub-folders +.PARAMETER Force + Overwrite already existing files/folders +.INPUTS + System.String +.OUTPUTS + System.Boolean +.LINK + https://github.com/Icinga/icinga-powershell-framework +#> function Copy-ItemSecure() { param( diff --git a/lib/core/framework/Expand-IcingaZipArchive.psm1 b/lib/core/framework/Expand-IcingaZipArchive.psm1 index 658e63a..dfde53a 100644 --- a/lib/core/framework/Expand-IcingaZipArchive.psm1 +++ b/lib/core/framework/Expand-IcingaZipArchive.psm1 @@ -1,3 +1,24 @@ +<# +.SYNOPSIS + Extracts a ZIP-Archive to a certain location +.DESCRIPTION + Unzips a ZIP-Archive on to a certain location +.FUNCTIONALITY + Unzips a ZIP-Archive on to a certain location +.EXAMPLE + PS>Expand-IcingaZipArchive -Path 'C:\users\public\test.zip' -Destination 'C:\users\public\'; +.PARAMETER Path + The location of your ZIP-Archive +.PARAMETER Destination + The target destination to extract the ZIP-Archive to +.INPUTS + System.String +.OUTPUTS + System.Boolean +.LINK + https://github.com/Icinga/icinga-powershell-framework +#> + function Expand-IcingaZipArchive() { param( diff --git a/lib/core/framework/Get-IcingaFrameworkServiceBinary.psm1 b/lib/core/framework/Get-IcingaFrameworkServiceBinary.psm1 index 96552b8..cdc34f1 100644 --- a/lib/core/framework/Get-IcingaFrameworkServiceBinary.psm1 +++ b/lib/core/framework/Get-IcingaFrameworkServiceBinary.psm1 @@ -1,3 +1,29 @@ +<# +.SYNOPSIS + Downloads a ZIP-Archive for the Icinga for Windows Service Binary + and installs it into a specified directory +.DESCRIPTION + Wizard function to download the Icinga for Windows Service binary from + a public ressource or from a local webstore / webshare and extract + the ZIP-Archive into a target destination +.FUNCTIONALITY + Downloads and unzips the Icinga for Windows service binary ZIP-Archive +.EXAMPLE + PS>Get-IcingaFrameworkServiceBinary -FrameworkServiceUrl 'https://github.com/Icinga/icinga-powershell-service/releases/download/v1.0.0/icinga-service-v1.0.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service'; +.EXAMPLE + PS>Get-IcingaFrameworkServiceBinary -FrameworkServiceUrl 'C:/users/public/icinga-service-v1.0.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service'; +.PARAMETER FrameworkServiceUrl + The URL / Source for downloading the ZIP-Archive from. +.PARAMETER Destination + The target destination to extract the ZIP-Archive to and to place the service binary +.INPUTS + System.String +.OUTPUTS + System.Hashtable +.LINK + https://github.com/Icinga/icinga-powershell-framework +#> + function Get-IcingaFrameworkServiceBinary() { param( diff --git a/lib/core/framework/Get-IcingaPowerShellModuleArchive.psm1 b/lib/core/framework/Get-IcingaPowerShellModuleArchive.psm1 index 4f6025d..221aefd 100644 --- a/lib/core/framework/Get-IcingaPowerShellModuleArchive.psm1 +++ b/lib/core/framework/Get-IcingaPowerShellModuleArchive.psm1 @@ -1,3 +1,39 @@ +<# +.SYNOPSIS + Download a PowerShell Module from a custom source or from GitHub + by providing a repository and the user space +.DESCRIPTION + Download a PowerShell Module from a custom source or from GitHub + by providing a repository and the user space +.FUNCTIONALITY + Download and install a PowerShell module from a custom or GitHub source +.EXAMPLE + PS>Get-IcingaPowerShellModuleArchive -ModuleName 'Plugins' -Repository 'icinga-powershell-plugins' -Stable 1; +.EXAMPLE + PS>Get-IcingaPowerShellModuleArchive -ModuleName 'Plugins' -Repository 'icinga-powershell-plugins' -Stable 1 -DryRun 1; +.PARAMETER DownloadUrl + The Url to a ZIP-Archive to download from (skips the wizard) +.PARAMETER ModuleName + The name which is used inside output messages +.PARAMETER Repository + The repository to download the ZIP-Archive from +.PARAMETER GitHubUser + The user from which a repository is downloaded from +.PARAMETER Stable + Download the latest stable release +.PARAMETER Snapshot + Download the latest package from the master branch +.PARAMETER DryRun + Only return the finished build Url including the version to install but + do not modify the system in any way +.INPUTS + System.String +.OUTPUTS + System.Hashtable +.LINK + https://github.com/Icinga/icinga-powershell-framework +#> + function Get-IcingaPowerShellModuleArchive() { param( diff --git a/lib/core/framework/Get-IcingaPowerShellModuleVersion.psm1 b/lib/core/framework/Get-IcingaPowerShellModuleVersion.psm1 index 14d9d4c..7a9e74e 100644 --- a/lib/core/framework/Get-IcingaPowerShellModuleVersion.psm1 +++ b/lib/core/framework/Get-IcingaPowerShellModuleVersion.psm1 @@ -1,3 +1,24 @@ +<# +.SYNOPSIS + Get the version of an installed PowerShell Module +.DESCRIPTION + Get the version of an installed PowerShell Module +.FUNCTIONALITY + Get the version of an installed PowerShell Module +.EXAMPLE + PS>Get-IcingaPowerShellModuleVersion -ModuleName 'icinga-powershell-framework'; +.EXAMPLE + PS>Get-IcingaPowerShellModuleVersion -ModuleName 'icinga-powershell-plugins'; +.PARAMETER ModuleName + The PowerShell module to fetch the installed version from +.INPUTS + System.String +.OUTPUTS + System.String +.LINK + https://github.com/Icinga/icinga-powershell-framework +#> + function Get-IcingaPowerShellModuleVersion() { param(