Skip to content

Commit f61c26c

Browse files
YanaXuYanaXu
authored
add doc for Azure PowerShell Exceptions (#22724)
1 parent 77b1e37 commit f61c26c

File tree

2 files changed

+128
-26
lines changed

2 files changed

+128
-26
lines changed

‎documentation/development-docs/azure-powershell-developer-guide.md

Lines changed: 36 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,43 +2,48 @@
22

33
The Azure PowerShell Developer Guide was created to help with the development and testing of Azure PowerShell cmdlets. This guide contains information on how to set up your environment, create a new project, implement cmdlets, record and run tests, and more.
44

5-
**Note: Except for the way described in this page, There is a new way to generate PowerShell modules through AutoRest PowerShell generator. And related links are attached in the end.**
5+
**Note: Except for the way described in this page, There is a new way to generate PowerShell modules through AutoRest PowerShell generator. Refer to [Autorest PowerShell Generator](#autorest-powershell-generator).**
66

77
# Table of Contents
88

9+
- [Azure PowerShell Developer Guide](#azure-powershell-developer-guide)
10+
- [Table of Contents](#table-of-contents)
911
- [Prerequisites](#prerequisites)
1012
- [Environment Setup](#environment-setup)
11-
- [GitHub Basics](#github-basics)
12-
- [Building the Environment](#building-the-environment)
13-
- [Generating Help](#generating-help)
14-
- [Running Static Analysis](#running-static-analysis)
15-
- [Running Tests](#running-tests)
13+
- [GitHub Basics](#github-basics)
14+
- [Building the Environment](#building-the-environment)
15+
- [Generating Help](#generating-help)
16+
- [Running Static Analysis](#running-static-analysis)
17+
- [Running Tests](#running-tests)
1618
- [Before Adding a New Project](#before-adding-a-new-project)
17-
- [.NET SDK](#net-sdk)
18-
- [Design Review](#design-review)
19-
- [Contact](#point-of-contact)
19+
- [.NET SDK](#net-sdk)
20+
- [Design Review](#design-review)
21+
- [Point of Contact](#point-of-contact)
2022
- [Setting Up a New Project](#setting-up-a-new-project)
21-
- [Getting Started](#getting-started)
22-
- [Creating the Project](#creating-the-project)
23-
- [Adding Project References](#adding-project-references)
23+
- [Getting Started](#getting-started)
24+
- [Creating the Project](#creating-the-project)
25+
- [Adding Project References](#adding-project-references)
2426
- [Creating Cmdlets](#creating-cmdlets)
25-
- [PowerShell Cmdlet Design Guidelines](#powershell-cmdlet-design-guidelines)
26-
- [Enable Running PowerShell when Debugging](#enable-running-powershell-when-debugging)
27-
- [Importing Modules](#importing-modules)
28-
- [Adding Help Content](#adding-help-content)
27+
- [PowerShell Cmdlet Design Guidelines](#powershell-cmdlet-design-guidelines)
28+
- [Exceptions Guidelines](#exceptions-guidelines)
29+
- [Enable Running PowerShell when Debugging](#enable-running-powershell-when-debugging)
30+
- [Set a StartUp Project](#set-a-startup-project)
31+
- [Setup a Debug Profile](#setup-a-debug-profile)
32+
- [Adding Help Content](#adding-help-content)
2933
- [Adding Tests](#adding-tests)
30-
- [Using Azure TestFramework](#using-azure-testframework)
31-
- [Scenario Tests](#scenario-tests)
32-
- [Adding Scenario Tests](#adding-scenario-tests)
33-
- [Using Common Code](#using-common-code)
34-
- [Using Active Directory](#using-active-directory)
35-
- [Using Certificate](#using-certificate)
36-
- [AD Scenario Tests](#ad-scenario-tests)
37-
- [Recording/Running Tests](#recordingrunning-tests)
34+
- [Using Azure TestFramework](#using-azure-testframework)
35+
- [Scenario Tests](#scenario-tests)
36+
- [Adding Test Project](#adding-test-project)
37+
- [Adding Scenario Tests](#adding-scenario-tests)
38+
- [Use local files in test](#use-local-files-in-test)
39+
- [Using Active Directory](#using-active-directory)
40+
- [AD Scenario Tests](#ad-scenario-tests)
41+
- [Recording/Running Tests](#recordingrunning-tests)
3842
- [After Development](#after-development)
43+
- [Change Log](#change-log)
3944
- [Misc](#misc)
40-
- [Publish to PowerShell Gallery](#publish-to-powershell-gallery)
41-
- [Autorest PowerShell Generator](#autorest-powershell-generator)
45+
- [Publish to PowerShell Gallery](#publish-to-powershell-gallery)
46+
- [AutoRest PowerShell Generator](#autorest-powershell-generator)
4247

4348
# Prerequisites
4449

@@ -213,6 +218,11 @@ There are a few existing projects that need to be added before developing any cm
213218

214219
Please check out the [_Cmdlet Best Practices_](./design-guidelines/cmdlet-best-practices.md) document for more information on how to create cmdlets that follow the PowerShell guidelines.
215220

221+
## Exceptions Guidelines
222+
223+
Azure PowerShell defines most commonly used exceptions. Developers working on Azure PowerShell should use these exceptions during development, rather than other more generic exceptions.
224+
Refer to [_Azure PowerShell Exceptions_](./design-guidelines/azure-powershell-exceptions.md) for more information on Azure PowerShell Exceptions.
225+
216226
## Enable Running PowerShell when Debugging
217227
To import modules automatically when debug has started, follow the below steps:
218228
### Set a StartUp Project

‎documentation/development-docs/design-guidelines/azure-powershell-exceptions.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Azure PowerShell Exceptions
2+
3+
## What are Azure PowerShell Exceptions?
4+
5+
Azure PowerShell defines most commonly used exceptions, all of which inherit from the *[IContainsAzPSErrorData](https://learn.microsoft.com/dotnet/api/microsoft.azure.commands.common.icontainsazpserrordata?view=az-ps-latest)* interface. This interface includes telemetry data. Developers working on Azure PowerShell should use these exceptions during development, rather than other more generic exceptions.
6+
7+
8+
| Azure PowerShell Exception Type | Default Error Kind | Mandatory Properties | When to Use it? |
9+
|--|--|--|--|
10+
| AzPSCloudException | Service | HttpStatusCode | This exception should be thrown for getting incorrect http response from Azure service. |
11+
| AzPSAuthenticationFailedException | Internal | AuthErrorCode | This exception should be thrown for authentication failures in Azure PowerShell. |
12+
| AzPSResourceNotFoundCloudException | User | | This exception should be thrown when the resource is not found by Azure service. |
13+
| AzPsArgumentException | User | ParamName | This exception should be thrown for errors in an arithmetic, casting, or conversion operation. |
14+
| AzPSArgumentNullException | User | ParamName | This exception should be thrown when a null reference (Nothing in Visual Basic) is passed to a method that does not accept it as a valid argument. |
15+
| AzPSArgumentOutOfRangeException | User | ParamName | This exception should be thrown when the argument is out of range. |
16+
| AzPSException | N/A | | This exception should be thrown when errors occur during application execution. |
17+
| AzPSInvalidOperationException | Internal | | This exception should be thrown when a method call is invalid for the object's current state. |
18+
| AzPSIOException | User | | This exception should be thrown when an I/O error occurs. |
19+
| AzPSKeyNotFoundException | Internal | MapKeyName | This exception should be thrown when the key specified for accessing an element in a collection does not match any key in the collection. |
20+
| AzPSApplicationException | Internal | | This exception is representive of ApplicationException in Azure PowerShell. |
21+
| AzPSFileNotFoundException | User | FileName (Not full path) | This exception should be thrown when accessing a file that does not exist. |
22+
23+
There are three types of errors in Azure PowerShell.
24+
- **User Error**: The error is caused by user.
25+
- **Service Error**: The error is caused by Azure services.
26+
- **Internal Error**: other errors.
27+
28+
## How to use Azure PowerShell Exception?
29+
30+
- An code example for *AzPSArgumentException*
31+
32+
The source code is from [NewAzureRmAks.cs](https://github.com/Azure/azure-powershell/blob/77b1e37e11179e59333edd825b2459435cab8726/src/Aks/Aks/Commands/NewAzureRmAks.cs).
33+
34+
```csharp
35+
throw new AzPSArgumentException(
36+
Resources.AksNodePoolAutoScalingParametersMustAppearTogether,
37+
nameof(EnableNodeAutoScaling),
38+
desensitizedMessage: Resources.AksNodePoolAutoScalingParametersMustAppearTogether);
39+
``````
40+
41+
- An code example for from *AzPSCloudException*
42+
43+
The source code is [KubeCmdletBase.cs](https://github.com/Azure/azure-powershell/blob/77b1e37e11179e59333edd825b2459435cab8726/src/Aks/Aks/Commands/KubeCmdletBase.cs).
44+
45+
```csharp
46+
var newEx = new AzPSCloudException(Resources.K8sVersionNotSupported, Resources.K8sVersionNotSupported, ex)
47+
{
48+
Request = ex.Request,
49+
Response = ex.Response,
50+
Body = ex.Body,
51+
};
52+
throw newEx;
53+
``````
54+
55+
- An code example for *AzPSResourceNotFoundCloudException*
56+
57+
The source code is from [KubeCmdletBase.cs](https://github.com/Azure/azure-powershell/blob/77b1e37e11179e59333edd825b2459435cab8726/src/Aks/Aks/Commands/KubeCmdletBase.cs).
58+
59+
```csharp
60+
var newEx = new AzPSResourceNotFoundCloudException(ex.Message, innerException: ex)
61+
{
62+
Request = ex.Request,
63+
Response = ex.Response,
64+
Body = ex.Body,
65+
};
66+
throw newEx;
67+
``````
68+
69+
## Why to use Azure PowerShell Exception?
70+
71+
Providing detailed error information is helpful for developers to pinpoint the root cause of errors. However, due to GDPR (General Data Protection Regulation), we do not record client's detailed error messages in telemetry data. To assist developers in more efficiently locating errors, we define unified exception interfaces that includes additional error details without containing any sensitive information.
72+
73+
### Azure PowerShell Exception Telemetry Data
74+
75+
- An exception telemetry example for *AzPSArgumentException*
76+
77+
```json
78+
{
79+
"exception-data": "ParamName=context.Account;ErrorKind=User;ErrorLineNumber=289;ErrorFileName=AuthenticationFactory",
80+
"exception-type": "Microsoft.Azure.Commands.Common.Exceptions.AzPSArgumentException"
81+
}
82+
``````
83+
84+
- An exception telemetry example for generic *ArgumentException*
85+
86+
```json
87+
{
88+
"exception-type": "System.ArgumentException"
89+
}
90+
``````
91+
92+
Refer to [Azure PowerShell Telemetry](https://eng.ms/docs/cloud-ai-platform/azure-core/azure-management-and-platforms/control-plane-bburns/azure-cli-tools-azure-cli-powershell-and-terraform/azure-cli-tools/teams_docs/azps_docs/telemetry#client-side-telemetry) for more telemetry details.

0 commit comments

Comments
 (0)