Start commenting code and help messages

2019-02-22 22:17:47 -05:00
parent 9fd116b36f
commit 5e2e4a0c1b
6 changed files with 124 additions and 32 deletions
@@ -1,18 +1,24 @@
 function Get-ZertoApiFilter {
    [cmdletbinding()]
    param(
-        [Parameter( Mandatory = $true )]
+        [Parameter( Mandatory = $true,
+            HelpMessage = "Hashtable that contains filter keys and values"
+        )]
        [hashtable]$filterTable
    )
+    # Define the start of the return string
    [string]$returnString = "?"

+    #Foreach item in the table, process each item
    foreach ( $key in $filterTable.Keys ) {
+        #If this is not the first item added to the string, add the ampersand and filter
        if ($returnString.Length -gt 1) {
            $returnString = "{0}&{1}={2}" -f $returnString, $key, $filterTable[$key]
        } else {
+            #If it is the first item, just add the first item
            $returnString = "{0}{1}={2}" -f $returnString, $key, $filterTable[$key]
        }
    }
-
+    # Return the built query String
    return $returnString
 }
@@ -11,24 +11,34 @@ function Invoke-ZertoRestRequest {
        [switch]$returnHeaders
    )
    $callerErrorActionPreference = $ErrorActionPreference
+    # If the ZVM server and Port not defined, Stop Call
    if ( -not ((Test-Path variable:script:zvmServer) -and (Test-Path variable:script:zvmPort)) ) {
        Write-Error -Message "Zerto Connection does not Exist. Please run Connect-ZertoServer first to establish a connection"
        break
    }
+
+    # If the Headers exist and the Last action was more than 30 minutes ago, Session is Expired
    if ( (Test-Path variable:script:zvmHeaders) -and $([datetime]$script:zvmLastAction).addMinutes(30) -lt $(get-date) ) {
        Write-Error -Message "Authorization Token has Expired. Please re-authorize to the Zerto Virtual Manager"
        break
    } else {
+
+        # Build the URI to be submitted
        $submittedURI = "https://{0}:{1}/{2}/{3}" -f $script:zvmServer, $script:zvmPort, $apiVersion, $uri
        try {
+            # Set the zvmLastAction time and try to submit the REST Request
            $script:zvmLastAction = (get-date).Ticks
            $apiRequestResults = Invoke-RestMethod -Uri $submittedURI -Headers $script:zvmHeaders -Method $method -Body $body -ContentType $contentType -Credential $credential -SkipCertificateCheck -ResponseHeadersVariable responseHeaders -TimeoutSec 100
        } catch {
+            # If an error is encountered, Catch
            Write-Error -ErrorRecord $_ -ErrorAction $callerErrorActionPreference
        }
+
+        # If the calling function does not need the headers (Default Action) return the results of the API Call
        if (-not $returnHeaders) {
            return $apiRequestResults
        } else {
+            #If Headers are required, build a PS Custom Object with the Results and the Headers
            $apiRequestAndHeaderResults = New-Object -TypeName psobject
            $apiRequestAndHeaderResults | Add-Member -MemberType NoteProperty -Name "apiRequestResults" -Value $apiRequestResults
            $apiRequestAndHeaderResults | Add-Member -MemberType NoteProperty -Name "Headers" -Value $responseHeaders
@@ -1,7 +1,5 @@
 function Connect-ZertoServer {
-    [cmdletbinding(
-        SupportsShouldProcess = $false
-    )]
+    [cmdletbinding()]
    param(
        [Parameter(
            Mandatory = $true,
@@ -9,7 +7,9 @@ function Connect-ZertoServer {
        )]
        [ValidateNotNullOrEmpty()]
        [string]$zertoServer,
-        [Parameter( HelpMessage = "Zerto Virtual Manager management port. Default value is 9669." )]
+        [Parameter(
+            HelpMessage = "Zerto Virtual Manager management port. Default value is 9669."
+        )]
        [string]$zertoPort = "9669",
        [Parameter(
            Mandatory = $true,
@@ -19,17 +19,34 @@ function Connect-ZertoServer {
        $credential,
        [switch]$returnHeaders
    )
-    Set-Variable -Name zvmServer -Scope Script -Value $zertoServer
-    Set-Variable -Name zvmPort -Scope Script -Value $zertoPort
-    Set-Variable -Name zvmLastAction -Scope Script -Value $(get-date).Ticks
-    Set-Variable -Name zvmHeaders -Scope Script -Value $null
-    $body = '{"AuthenticationMethod": "1"}'
-    $uri = "session/add"
-    $results = Invoke-ZertoRestRequest -uri $uri -credential $credential -returnHeaders -body $body -method POST
-    $zertoAuthorizationHeaders = @{"x-zerto-session" = $results.Headers['x-zerto-session'][0].ToString(); "Accept" = "application/json"}
-    Set-Variable -Name zvmHeaders -Scope Script -Value $zertoAuthorizationHeaders
-    Set-Variable -Name zvmLocalInfo -Scope Script -Value (Get-ZertoLocalSite)
-    if ($returnHeaders) {
-        return $zertoAuthorizationHeaders
+
+    begin {
+        $body = '{"AuthenticationMethod": "1"}'
+        $uri = "session/add"
+        # Set Script Scope Variables for Use in all functions in the module; Server and Port Information
+        Set-Variable -Name zvmServer -Scope Script -Value $zertoServer
+        Set-Variable -Name zvmPort -Scope Script -Value $zertoPort
+        # Set zvmLastAction Variable to keep track when the API token expires
+        Set-Variable -Name zvmLastAction -Scope Script -Value $(get-date).Ticks
+        # Set / Clear the zvmHeaders to clear any existing token
+        Set-Variable -Name zvmHeaders -Scope Script -Value $null
+    }
+
+    process {
+        # Send authorization request to the function and send back the results including headers
+        $results = Invoke-ZertoRestRequest -uri $uri -credential $credential -returnHeaders -body $body -method POST
+    }
+
+    end {
+        # Build Headers Hashtable with Authorization Token
+        $zertoAuthorizationHeaders = @{"x-zerto-session" = $results.Headers['x-zerto-session'][0].ToString(); "Accept" = "application/json"}
+        # Set common Script Scope Variables to be used other functions (Headers and Local Site Info)
+        Set-Variable -Name zvmHeaders -Scope Script -Value $zertoAuthorizationHeaders
+        Set-Variable -Name zvmLocalInfo -Scope Script -Value (Get-ZertoLocalSite)
+
+        # Have the option to return the headers to a variable
+        if ($returnHeaders) {
+            return $zertoAuthorizationHeaders
+        }
    }
 }
@@ -1,7 +1,11 @@
 function Disconnect-ZertoServer {
    [cmdletbinding()]
    $uri = "session"
+
+    # Delete API Authorization
    Invoke-ZertoRestRequest -uri $uri -method DELETE
+
+    # Remove all variables used
    Remove-Variable -Name zvmServer -Scope Script
    Remove-Variable -Name zvmPort -Scope Script
    Remove-Variable -Name zvmLastAction -Scope Script
@@ -1,31 +1,76 @@
 function Get-ZertoAlert {
    [cmdletbinding( defaultParameterSetName = "main" )]
    param(
-        [Parameter( ParameterSetName = "alertId", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true )]
+        [Parameter(
+            ParameterSetName = "alertId",
+            Mandatory = $true,
+            ValueFromPipeline = $true,
+            ValueFromPipelineByPropertyName = $true ,
+            HelpMessage = "AlertId or array of AlertIds to be queried"
+        )]
        [string[]]$alertId,
-        [Parameter( ParameterSetName = "entities", Mandatory = $true )]
+        [Parameter(
+            ParameterSetName = "entities",
+            Mandatory = $true,
+            HelpMessage = "Switch to return the entities information from the API"
+        )]
        [switch]$entities,
-        [Parameter( ParameterSetName = "helpIdentifiers", Mandatory = $true )]
+        [Parameter(
+            ParameterSetName = "helpIdentifiers",
+            Mandatory = $true,
+            HelpMessage = "Switch to get the Help Identifiers information from the API"
+        )]
        [switch]$helpIdentifiers,
-        [Parameter( ParameterSetName = "levels", Mandatory = $true )]
+        [Parameter(
+            ParameterSetName = "levels",
+            Mandatory = $true,
+            HelpMessage = "Switch to return Alert Levels information from the API"
+        )]
        [switch]$levels,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage = "Returns Alerts after the Start Date. Provide the string in the format of 'yyyy-MM-ddTHH:mm:ss.fff'"
+        )]
        [string]$startDate,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage = "Returns Alerts before the End Date. Provide the string in the format of 'yyyy-MM-ddTHH:mm:ss.fff'"
+        )]
        [string]$endDate,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage "Returns alerts for the specified vraIdentifier"
+        )]
        [string]$vpgIdentifier,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage = "Returns alerts for the specified siteIdentifier"
+        )]
        [string]$siteIdentifier,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage = "Returns alerts for the specified zorgIdentifier"
+        )]
        [string]$zorgIdentifier,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage = "Returns alerts for the specified level"
+        )]
        [string]$level,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage = "Returns alerts for the specified helpIdentifier"
+        )]
        [string]$helpIdentifier,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage = "Returns alerts for the specified entity"
+        )]
        [string]$entity,
-        [Parameter( ParameterSetName = "filter" )]
+        [Parameter(
+            ParameterSetName = "filter",
+            HelpMessage = "Returns alerts that are dismissed"
+        )]
        [switch]$isDismissed
    )

@@ -35,12 +80,15 @@ function Get-ZertoAlert {
    }

    process {
+        # Select the operation based on the ParameterSetName
        switch ( $PSCmdlet.ParameterSetName ) {
+            # If called without any parameters, return all alerts
            "main" {
                $uri = "{0}" -f $baseUri
                $returnObject = Invoke-ZertoRestRequest -uri $uri
            }

+            # If called with the alertId ParameterSetName, build an object that contains all alerts for alertIds specified
            "alertId" {
                $returnObject = foreach ( $id in $alertId ) {
                    $uri = "{0}/{1}" -f $baseUri, $alertId
@@ -48,12 +96,14 @@ function Get-ZertoAlert {
                }
            }

+            # If called with the filter ParameterSetName, get a filter string and get results from API.
            "filter" {
                $filter = Get-ZertoApiFilter -filterTable $PSBoundParameters
                $uri = "{0}{1}" -f $baseUri, $filter
                $returnObject = Invoke-ZertoRestRequest -uri $uri
            }

+            # If any other ParameterSetName is called, build URI based on ParameterSetName and submit
            default {
                $uri = "{0}/{1}" -f $baseUri, $PSCmdlet.ParameterSetName.ToLower()
                $returnObject = Invoke-ZertoRestRequest -uri $uri
@@ -1,7 +1,10 @@
 function Get-ZertoDatastore {
    [cmdletbinding( DefaultParameterSetName = "main" )]
    param(
-        [Parameter( ParameterSetName = "datastoreIdentifier" )]
+        [Parameter(
+            ParameterSetName = "datastoreIdentifier",
+            HelpMessage = "datastoreIdentifier or array of datastoreIdentifiers to be queried"
+        )]
        [string[]]$datastoreIdentifier
    )

@@ -11,10 +14,12 @@ function Get-ZertoDatastore {
    }

    process {
+        # If command is called without parameters, return all datastores
        if ( $PSCmdlet.ParameterSetName -eq "main" ) {
            $uri = "{0}" -f $baseUri
            $returnObject = Invoke-ZertoRestRequest -uri $uri
        } else {
+            # Return information for datastoreIdentifiers requested
            $returnObject = foreach ( $id in $datastoreIdentifier ) {
                $uri = "{0}/{1}" -f $baseUri, $id
                Invoke-ZertoRestRequest -uri $uri