Project

SdnDiagnostics is a PowerShell module that is designed to simplify the diagnostic troubleshooting and data collection process when troubleshooting issues related to Microsoft Software Defined Network.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

When contributing to this project, ensure you:

1. Review existing functions already available and reuse where possible.
2. Return native .NET objects whenever possible.
3. Rarely should you return from a function with format-table, format-list, etc.. If they do, they should use the PowerShell verb Show.
4. Environments that this module run on may be in a broken or inconcistent state, so defensive coding techniques should be leveraged.
5. Leverage $Global:SdnDiagnostics for caching when appropriate.

Creating Core Modules

When creating core functions:

1. Functions should be placed under src\modules\[ModuleName]\[Private | Public]\Verb-FunctionName.ps1.
   • Function name should match the file name.
   • Limit one function per file.
   • Ensure that the file name is added to src\SDNDiagnostics.psm1 so it is dot sourced on module import.
   • Use Approved Verbs for PowerShell Commands.
2. If your function should be exported and available after module import, be sure to add your function to the export list in src\SdnDiagnostics.psd1 under FunctionsToExport.

To help ensure consistency, leverage .build\utilities\create-function.ps1 to help create your functions. This will create a .ps1 file off the specified template and place into the appropriate module directory. Example:

.\create-core-function.ps1 -FunctionName 'Disable-RasGatewayTracing' -Module Gateway -Template basic_template.ps1 -IsPublic

Creating Health Validation Tests

When creating a health validation test, ensure you:

1. Create the ps1 file under src\health\[role]\ as the name of the validation test. e.g. Test-SdnServerHealth.ps1
2. Function should return a PSCustomObject that contains the following format:

   # $status should contain either 'Success' or 'Failure'
   # $properties will contain any related information in scenario of 'Failure' status 
   else {
       return [PSCustomObject]@{
           Status = $status
           Properties = $arrayList
       }
   }
   

3. Health validation tests are executed using Debug-SdnFabricInfrastructure or executing the cmdlet directly.
   • Debug-SdnFabricInfrastructure will automatically pick up tests under the src\health directory.
4. The infrastructure information can be retrieved from global cache at $Global:SdnDiagnostics

To help ensure consistency, leverage .build\utilities\create-health-function.ps1 to help create your functions. This will create a .ps1 file off the specified template and place into the appropriate module under src\health. Example:

.\create-health-function.ps1 -FunctionName 'Test-SdnLoadBalancerMuxOnline' -Module SoftwareLoadBalancer -Template basic_health_template.ps1

Creating Known Issue Tests

1. Create the ps1 file under src\knownIssues as the name of the validation test. e.g. Test-SdnKIVfpDuplicatePort.ps1
   • Ensure that you prefix your function name as Test-SdnKI.
2. Function should return a PSCustomObject that contains the following format:

   # $issueIdentified should either be $true or $false depending on if issue was detected
   # $properties will contain any related information in scenario of $true status 
   else {
       return [PSCustomObject]@{
           Result = $issueIdentified
           Properties = $arrayList
       }
   }
   

3. Known Issue tests are executed using Test-SdnKnownIssues or executing the cmdlet directly.
   • Test-SdnKnownIssues will automatically pick up tests under the src\knownIssues directory.
4. The infrastructure information can be retrieved from global cache at $Global:SdnDiagnostics

To help ensure consistency, leverage .build\utilities\create-knownissue-function.ps1 to help create your functions. This will create a .ps1 file off the specified template and place into the appropriate module under src\knownIssues. Example:

.\create-knownissue-function.ps1 -FunctionName 'Test-SdnKIVfpDuplicatePort' -Template basic_knownIssue_template.ps1

Build Validation and Testing

1. To generate a local build of the module, run .\.build\build.ps1 which will generate an SdnDiagnostics module package to ~\out\build\SdnDiagnostics.
2. Copy the module to C:\Program Files\WindowsPowerShell\Modules.
3. Import the module using Import-Module -Name SdnDiagnostics -Force.
4. Install the modules to the SDN nodes in the dataplane.

$uri = 'https://NcURI'
$netController = 'NC ComputerName'

$nodes = @()
$nodes += (Get-SdnServer -NcUri $uri -ManagementAddress)
$nodes += (Get-SdnGateway -NcUri $uri -ManagementAddress)
$nodes += (Get-SdnLoadBalancerMux -NcUri $uri -ManagementAddress)
$nodes += (Get-SdnNetworkController -NetworkController $netController -ServerNameOnly)

Install-SdnDiagnostic -ComputerName $nodes -Force

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.