From 74bdc02628f33e18908e8de76faa02a9f4a0f278 Mon Sep 17 00:00:00 2001 From: Alex Wolf Date: Wed, 25 Sep 2024 14:10:39 -0400 Subject: [PATCH 1/8] code and content updates --- .../azure/sdk/protocol-convenience-methods.md | 19 ++++++++++++++- .../Convenience/AzureCoreConvenience.csproj | 2 +- .../AzureCoreConvenience.csproj | 15 ++++++++++++ .../AzureCore/ExceptionHandling/Program.cs | 23 +++++++++++++++++++ .../Protocol/AzureCoreProtocol.csproj | 2 +- .../SCM/ExceptionHandling/Program.cs | 20 ++++++++++++++++ .../ExceptionHandling/SCMConvenience.csproj | 14 +++++++++++ .../SCM/Protocol/Program.cs | 11 +++++---- .../SCM/Protocol/SCMProtocol.csproj | 2 +- 9 files changed, 100 insertions(+), 8 deletions(-) create mode 100644 docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj create mode 100644 docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs create mode 100644 docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs create mode 100644 docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/SCMConvenience.csproj diff --git a/docs/azure/sdk/protocol-convenience-methods.md b/docs/azure/sdk/protocol-convenience-methods.md index 3124bb39a6867..25d8381a09609 100644 --- a/docs/azure/sdk/protocol-convenience-methods.md +++ b/docs/azure/sdk/protocol-convenience-methods.md @@ -95,7 +95,7 @@ The preceding code demonstrates the following `System.ClientModel` convenience m The following code uses a `ChatClient` to call the `CompleteChat` protocol method: -:::code source="snippets/protocol-convenience-methods/SCM/Protocol/Program.cs" highlight="26-31"::: +:::code source="snippets/protocol-convenience-methods/SCM/Protocol/Program.cs" highlight="31-34"::: The preceding code demonstrates the following `System.ClientModel` protocol method patterns: @@ -129,6 +129,23 @@ PipelineResponse response = result.GetRawResponse(); --- +## Handling exceptions + +When a service call fails, service clients throw an exception that exposes the HTTP status code and the details of the service response if available. + +- `System.ClientModel` dependant libraries throw a [`ClientResultException`](https://learn.microsoft.com/en-us/dotnet/api/system.clientmodel.clientresultexception). +- `Azure.Core` dependant libraries throw a [`RequestFailedException`](https://learn.microsoft.com/en-us/dotnet/api/azure.requestfailedexception). + +# [System.ClientModel exceptions](#tab/system-clientmodel) + +:::code source="snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs" highlight="9-23"::: + +# [Azure.Core exceptions](#tab/azure-core) + +:::code source="snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs" highlight="9-20"::: + +--- + ## Protocol and convenience method usage guidance Although the Azure SDK for .NET client libraries provide the option to use either protocol or convenience methods, prioritize using convenience methods in most scenarios. Convenience methods are designed to improve the development experience and provide flexibility for authoring requests and handling responses. However, both method types can be used in your app as needed. Consider the following criteria when deciding which type of method to use. diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/Convenience/AzureCoreConvenience.csproj b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/Convenience/AzureCoreConvenience.csproj index 4afa8435d8c1d..502b14e17d179 100644 --- a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/Convenience/AzureCoreConvenience.csproj +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/Convenience/AzureCoreConvenience.csproj @@ -2,7 +2,7 @@ Exe - net9.0 + net8.0 enable enable diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj new file mode 100644 index 0000000000000..4afa8435d8c1d --- /dev/null +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj @@ -0,0 +1,15 @@ + + + + Exe + net9.0 + enable + enable + + + + + + + + diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs new file mode 100644 index 0000000000000..0c43e2bb63dcf --- /dev/null +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs @@ -0,0 +1,23 @@ +using Azure.AI.ContentSafety; +using Azure.Identity; + +// Create the client +ContentSafetyClient client = new( + new Uri("https://contentsafetyai.cognitiveservices.azure.com/"), + new DefaultAzureCredential()); + +try +{ + // Call the convenience method + AnalyzeTextResult result = client.AnalyzeText("What is Microsoft Azure?"); + + // Display the results + foreach (TextCategoriesAnalysis item in result.CategoriesAnalysis) + { + Console.WriteLine($"{item.Category}: {item.Severity}"); + } +} +catch (RequestFailedException ex) +{ + Console.WriteLine($"Error: {ex.Message}"); +} diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/Protocol/AzureCoreProtocol.csproj b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/Protocol/AzureCoreProtocol.csproj index 4afa8435d8c1d..502b14e17d179 100644 --- a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/Protocol/AzureCoreProtocol.csproj +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/Protocol/AzureCoreProtocol.csproj @@ -2,7 +2,7 @@ Exe - net9.0 + net8.0 enable enable diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs new file mode 100644 index 0000000000000..8b0ddd37fe723 --- /dev/null +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs @@ -0,0 +1,20 @@ +using OpenAI.Chat; + +// Create the client +ChatClient client = new( + model: "gpt-4o-mini", + credential: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!); + +try +{ + // Call the convenience method + ChatCompletion completion = client.CompleteChat("What is Microsoft Azure?"); + + // Display the results + Console.WriteLine($"[{completion.Role}]: {completion}"); +} +catch (ClientResultException ex) +{ + Console.WriteLine($"Error: {ex.Message}"); +} + diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/SCMConvenience.csproj b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/SCMConvenience.csproj new file mode 100644 index 0000000000000..8fd07dc7dde67 --- /dev/null +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/SCMConvenience.csproj @@ -0,0 +1,14 @@ + + + + Exe + net8.0 + enable + enable + + + + + + + diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/Protocol/Program.cs b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/Protocol/Program.cs index bd5a0e3bf0d2c..63f2cca9c91e0 100644 --- a/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/Protocol/Program.cs +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/Protocol/Program.cs @@ -22,13 +22,16 @@ """u8.ToArray()); using BinaryContent content = BinaryContent.Create(input); +var requestOptions = new RequestOptions(); + +requestOptions.AddHeader("CustomHeader", "CustomHeaderValue"); +requestOptions.ErrorOptions = ClientErrorBehaviors.NoThrow; + // Call the protocol method ClientResult result = client.CompleteChat( content, - new RequestOptions - { - ErrorOptions = ClientErrorBehaviors.NoThrow, - }); + requestOptions +); PipelineResponse response = result.GetRawResponse(); diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/Protocol/SCMProtocol.csproj b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/Protocol/SCMProtocol.csproj index a3b95e116d1c7..8fd07dc7dde67 100644 --- a/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/Protocol/SCMProtocol.csproj +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/Protocol/SCMProtocol.csproj @@ -2,7 +2,7 @@ Exe - net9.0 + net8.0 enable enable From e0cb5687b51dc59dacef098c3261e04d6fee371c Mon Sep 17 00:00:00 2001 From: Alex Wolf Date: Wed, 25 Sep 2024 14:12:36 -0400 Subject: [PATCH 2/8] fix version --- .../AzureCore/ExceptionHandling/AzureCoreConvenience.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj index 4afa8435d8c1d..502b14e17d179 100644 --- a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj @@ -2,7 +2,7 @@ Exe - net9.0 + net8.0 enable enable From e3184441fd0f25e8bb57bae481314a165223e4da Mon Sep 17 00:00:00 2001 From: Alex Wolf Date: Wed, 25 Sep 2024 14:22:28 -0400 Subject: [PATCH 3/8] build fixes --- .../AzureCore/ExceptionHandling/Program.cs | 1 + .../SCM/ExceptionHandling/Program.cs | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs index 0c43e2bb63dcf..3cd408919df02 100644 --- a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs @@ -1,5 +1,6 @@ using Azure.AI.ContentSafety; using Azure.Identity; +using Azure.Core // Create the client ContentSafetyClient client = new( diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs index 8b0ddd37fe723..ddbcd377e9481 100644 --- a/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs @@ -1,4 +1,5 @@ using OpenAI.Chat; +using System.ClientModel; // Create the client ChatClient client = new( From 8d89d0f45a1de2f549e3ea5c2a5f2cf6df940aee Mon Sep 17 00:00:00 2001 From: Alex Wolf Date: Wed, 25 Sep 2024 15:06:52 -0400 Subject: [PATCH 4/8] fix build --- .../AzureCore/ExceptionHandling/Program.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs index 3cd408919df02..00c7fb2e3596a 100644 --- a/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs @@ -1,6 +1,6 @@ using Azure.AI.ContentSafety; using Azure.Identity; -using Azure.Core +using Azure; // Create the client ContentSafetyClient client = new( From acb39a4c138731b030e514cd4ff5b51b83aa2e74 Mon Sep 17 00:00:00 2001 From: Alex Wolf Date: Wed, 25 Sep 2024 15:44:35 -0400 Subject: [PATCH 5/8] fix links --- docs/azure/sdk/protocol-convenience-methods.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/azure/sdk/protocol-convenience-methods.md b/docs/azure/sdk/protocol-convenience-methods.md index 25d8381a09609..21b3a2eea3202 100644 --- a/docs/azure/sdk/protocol-convenience-methods.md +++ b/docs/azure/sdk/protocol-convenience-methods.md @@ -133,8 +133,8 @@ PipelineResponse response = result.GetRawResponse(); When a service call fails, service clients throw an exception that exposes the HTTP status code and the details of the service response if available. -- `System.ClientModel` dependant libraries throw a [`ClientResultException`](https://learn.microsoft.com/en-us/dotnet/api/system.clientmodel.clientresultexception). -- `Azure.Core` dependant libraries throw a [`RequestFailedException`](https://learn.microsoft.com/en-us/dotnet/api/azure.requestfailedexception). +- `System.ClientModel` dependant libraries throw a [`ClientResultException`](/dotnet/api/system.clientmodel.clientresultexception). +- `Azure.Core` dependant libraries throw a [`RequestFailedException`](/dotnet/api/azure.requestfailedexception). # [System.ClientModel exceptions](#tab/system-clientmodel) From b8f01c1b4968cc9e79b7355c96ef42d1cc564005 Mon Sep 17 00:00:00 2001 From: alexwolfmsft <93200798+alexwolfmsft@users.noreply.github.com> Date: Thu, 26 Sep 2024 10:02:11 -0400 Subject: [PATCH 6/8] Apply suggestions from code review Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- docs/azure/sdk/protocol-convenience-methods.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/azure/sdk/protocol-convenience-methods.md b/docs/azure/sdk/protocol-convenience-methods.md index 21b3a2eea3202..88344504bd31a 100644 --- a/docs/azure/sdk/protocol-convenience-methods.md +++ b/docs/azure/sdk/protocol-convenience-methods.md @@ -129,16 +129,16 @@ PipelineResponse response = result.GetRawResponse(); --- -## Handling exceptions +## Handle exceptions -When a service call fails, service clients throw an exception that exposes the HTTP status code and the details of the service response if available. +When a service call fails, service clients throw an exception that exposes the HTTP status code and the details of the service response, if available. -- `System.ClientModel` dependant libraries throw a [`ClientResultException`](/dotnet/api/system.clientmodel.clientresultexception). -- `Azure.Core` dependant libraries throw a [`RequestFailedException`](/dotnet/api/azure.requestfailedexception). +- `System.ClientModel`-dependent libraries throw a . +- `Azure.Core`-dependent libraries throw a . # [System.ClientModel exceptions](#tab/system-clientmodel) -:::code source="snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs" highlight="9-23"::: +:::code source="snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs" highlight="10-24"::: # [Azure.Core exceptions](#tab/azure-core) From d77fa01003005f9433eee73168ef3887a88be470 Mon Sep 17 00:00:00 2001 From: alexwolfmsft <93200798+alexwolfmsft@users.noreply.github.com> Date: Thu, 26 Sep 2024 13:12:08 -0400 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- docs/azure/sdk/protocol-convenience-methods.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/azure/sdk/protocol-convenience-methods.md b/docs/azure/sdk/protocol-convenience-methods.md index 88344504bd31a..513eea1bf621c 100644 --- a/docs/azure/sdk/protocol-convenience-methods.md +++ b/docs/azure/sdk/protocol-convenience-methods.md @@ -131,10 +131,7 @@ PipelineResponse response = result.GetRawResponse(); ## Handle exceptions -When a service call fails, service clients throw an exception that exposes the HTTP status code and the details of the service response, if available. - -- `System.ClientModel`-dependent libraries throw a . -- `Azure.Core`-dependent libraries throw a . +When a service call fails, the service client throws an exception that exposes the HTTP status code and the details of the service response, if available. A `System.ClientModel`-dependent library throws a , while an `Azure.Core`-dependent library throws a . # [System.ClientModel exceptions](#tab/system-clientmodel) From ba76e85967fe62f3c930b0293a897f311cfa5cea Mon Sep 17 00:00:00 2001 From: Alex Wolf Date: Thu, 26 Sep 2024 13:17:41 -0400 Subject: [PATCH 8/8] highlights --- docs/azure/sdk/protocol-convenience-methods.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/azure/sdk/protocol-convenience-methods.md b/docs/azure/sdk/protocol-convenience-methods.md index 513eea1bf621c..86b5500c5f9b7 100644 --- a/docs/azure/sdk/protocol-convenience-methods.md +++ b/docs/azure/sdk/protocol-convenience-methods.md @@ -135,11 +135,11 @@ When a service call fails, the service client throws an exception that exposes t # [System.ClientModel exceptions](#tab/system-clientmodel) -:::code source="snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs" highlight="10-24"::: +:::code source="snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs" highlight="21-24"::: # [Azure.Core exceptions](#tab/azure-core) -:::code source="snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs" highlight="9-20"::: +:::code source="snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs" highlight="17-20"::: ---