Improve output generated for Debug-SdnFabricInfrastructure - 2 (#535)

This pull request introduces several improvements and refinements to the
SDN health diagnostics PowerShell module, focusing on severity handling,
summary display flexibility, and transcript management. The most
significant changes are the addition of a new severity level, improved
parameterization for summary output, and adjustments to transcript
handling for clarity and correctness.

**Severity and Health State Handling:**
* Added 'FAILURE' as a valid severity value alongside 'FAIL',
standardized severity mapping to use 'Failure' internally, and updated
all related logic to treat 'FAILURE' as the primary failure state
throughout the health validation and summary reporting.
[[1]](diffhunk://#diff-15898640fc68e07afa836ad8d93af4f22a4442978d9c233f39d48d44d85cfb60L296-R310)
[[2]](diffhunk://#diff-15898640fc68e07afa836ad8d93af4f22a4442978d9c233f39d48d44d85cfb60L583-R595)
[[3]](diffhunk://#diff-15898640fc68e07afa836ad8d93af4f22a4442978d9c233f39d48d44d85cfb60L595-R604)

**Summary Display Control:**
* Introduced a new `SkipSummaryDisplay` switch parameter to the
`Debug-SdnFabricInfrastructure` function, allowing users to optionally
suppress the summary output in the console. Logic was updated to respect
this flag when displaying results.
[[1]](diffhunk://#diff-15898640fc68e07afa836ad8d93af4f22a4442978d9c233f39d48d44d85cfb60R361-R362)
[[2]](diffhunk://#diff-15898640fc68e07afa836ad8d93af4f22a4442978d9c233f39d48d44d85cfb60L388-R400)
[[3]](diffhunk://#diff-15898640fc68e07afa836ad8d93af4f22a4442978d9c233f39d48d44d85cfb60L560-R572)

**Transcript Management:**
* Improved transcript handling by capturing the result of
`Start-Transcript` and `Stop-Transcript` to `$null` to avoid unnecessary
output, and moved the transcript stop and summary message to execute
after all processing, ensuring the transcript captures the entire
session.
[[1]](diffhunk://#diff-15898640fc68e07afa836ad8d93af4f22a4442978d9c233f39d48d44d85cfb60L398-R410)
[[2]](diffhunk://#diff-15898640fc68e07afa836ad8d93af4f22a4442978d9c233f39d48d44d85cfb60R655-R657)

These changes enhance the flexibility, clarity, and reliability of the
SDN diagnostics script, making it easier to interpret results and
control output during automated or manual runs.

# Change type
- [x] Bug fix (non-breaking change)
- [ ] Code style update (formatting, local variables)
- [ ] New Feature (non-breaking change that adds new functionality
without impacting existing)
- [ ] Breaking change (fix or feature that may cause functionality
impact)
- [ ] Other

# Checklist:
- [x] My code follows the style and contribution guidelines of this
project.
- [x] I have tested and validated my code changes.

Author: arudell

src/modules/SdnDiag.Health.psm1

@@ -293,15 +293,21 @@ function Write-HealthValidationInfo {
         [String[]]$Remediation,
 
         [Parameter(Mandatory = $false)]
-        [ValidateSet('WARNING', 'FAIL')]
+        [ValidateSet('WARNING', 'FAIL', 'FAILURE', IgnoreCase = $true)]
         [string]$Severity
     )
 
     switch ($Severity) {
         'WARNING' { 
+            $Severity = 'Warning'
             $foregroundColor = 'Yellow'
         }
         'FAIL' { 
+            $Severity = 'Failure'
+            $foregroundColor = 'Red'
+        }
+        'FAILURE' { 
+            $Severity = 'Failure'
             $foregroundColor = 'Red'
         }
     }
@@ -352,6 +358,8 @@ function Debug-SdnFabricInfrastructure {
         Enter a variable that contains a certificate or a command or expression that gets the certificate.
     .PARAMETER NcRestCredential
         Specifies a user account that has permission to perform this action against the Network Controller REST API. The default is the current user.
+    .PARAMETER SkipSummaryDisplay
+        Switch parameter to skip displaying the summary of results to the console.
     .EXAMPLE
         PS> Debug-SdnFabricInfrastructure
     .EXAMPLE
@@ -385,7 +393,11 @@ function Debug-SdnFabricInfrastructure {
 
         [Parameter(Mandatory = $false, ParameterSetName = 'Role')]
         [Parameter(Mandatory = $false, ParameterSetName = 'ComputerName')]
-        [X509Certificate]$NcRestCertificate
+        [X509Certificate]$NcRestCertificate,
+
+        [Parameter(Mandatory = $false, ParameterSetName = 'Role')]
+        [Parameter(Mandatory = $false, ParameterSetName = 'ComputerName')]
+        [switch]$SkipSummaryDisplay
     )
 
     $script:SdnDiagnostics_Health.Cache = $null
@@ -395,7 +407,7 @@ function Debug-SdnFabricInfrastructure {
 
     $transcriptDirectory = Get-WorkingDirectory
     $transcriptPath = "{0}\SdnFabricHealthReport_{1}.txt" -f $transcriptDirectory, $dateTimeNow
-    Start-Transcript -Path $transcriptPath -Force
+    $null = Start-Transcript -Path $transcriptPath -Force
     "Starting SDN Fabric Infrastructure health validation at {0}" -f $dateTimeNowFormatted | Trace-Output -Level:Information
 
     if (Test-ComputerNameIsLocal -ComputerName $NetworkController) {
@@ -557,10 +569,7 @@ function Debug-SdnFabricInfrastructure {
         $_ | Write-Error
     }
     finally {
-        Stop-Transcript
-        "Transcript saved to {0}" -f $transcriptPath | Trace-Output -Level:Information
-
-        if ($aggregateHealthReport) {
+        if ($aggregateHealthReport -and (-not $SkipSummaryDisplay)) {
 
             # Display SDN Health Validation Report Header
             $reportHeader = @"
@@ -580,10 +589,10 @@ function Debug-SdnFabricInfrastructure {
             $overallState = 'PASS'
             foreach ($report in $aggregateHealthReport) {
                 if ($report.Result -ieq 'FAIL') {
-                    $overallState = 'FAIL'
+                    $overallState = 'FAILURE'
                     break
                 }
-                elseif ($report.Result -ieq 'WARNING' -and $overallState -ne 'FAIL') {
+                elseif ($report.Result -ieq 'WARNING' -and $overallState -ne 'FAILURE') {
                     $overallState = 'WARNING'
                 }
             }
@@ -592,7 +601,7 @@ function Debug-SdnFabricInfrastructure {
             $stateColor = switch ($overallState) {
                 'PASS' { 'Green' }
                 'WARNING' { 'Yellow' }
-                'FAIL' { 'Red' }
+                'FAILURE' { 'Red' }
             }
 
             # Display summary
@@ -643,6 +652,9 @@ function Debug-SdnFabricInfrastructure {
         }
     }
 
+    $null = Stop-Transcript
+    "Transcript saved to {0}" -f $transcriptPath | Trace-Output -Level:Information
+
     if ($script:SdnDiagnostics_Health.Cache) {
         "Results for fabric health have been saved to cache for further analysis. Use 'Get-SdnFabricInfrastructureResult' to examine the results." | Trace-Output
         return $script:SdnDiagnostics_Health.Cache