diff --git a/docs/azure/sdk/protocol-convenience-methods.md b/docs/azure/sdk/protocol-convenience-methods.md index 3124bb39a6867..86b5500c5f9b7 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,20 @@ PipelineResponse response = result.GetRawResponse(); --- +## Handle exceptions + +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) + +:::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="17-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..502b14e17d179 --- /dev/null +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/AzureCoreConvenience.csproj @@ -0,0 +1,15 @@ + + + + Exe + net8.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..00c7fb2e3596a --- /dev/null +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/AzureCore/ExceptionHandling/Program.cs @@ -0,0 +1,24 @@ +using Azure.AI.ContentSafety; +using Azure.Identity; +using Azure; + +// 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..ddbcd377e9481 --- /dev/null +++ b/docs/azure/sdk/snippets/protocol-convenience-methods/SCM/ExceptionHandling/Program.cs @@ -0,0 +1,21 @@ +using OpenAI.Chat; +using System.ClientModel; + +// 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