One of the goals of the Azure SDK is to provide a unified developer experience across Azure. That means that basic capabilities\u2014like authenticating with a service or retrieving a value from service\u2014should work the same way, regardless of what Azure service you’re working with. To achieve this, Azure SDK client libraries use common patterns that you can learn once, and then use with any library. Many of the types used in these common patterns live in a foundational library called Azure Core.<\/p>\n
This post gives an introduction to the .NET This article is primarily focused on the .NET Other language libraries are also available on our Azure SDK Releases<\/a> page.<\/p>\n To get started, let’s look at the standard usage pattern for a typical Azure SDK for .NET client. This sample uses the When you write an application using the Azure SDK for .NET, you start by creating an instance of a service client<\/em><\/a>. You then invoke a service method<\/em><\/a> on the client to call its corresponding Azure service. The service method returns a model type<\/em><\/a>, that you can then use in your application. In our example, we simply print the sentiment inferred from the text to the console.<\/p>\n So how does In this example, We’ll look more closely at these and other As we mentioned earlier, the goal of At a high level, we think of the library as having two groups of users:<\/p>\n In general, types that are intended for consumers have simpler APIs and usage patterns. Types in the specialized namespaces may be more complex since they’re intended for use with more advanced scenarios.<\/p>\n One specialized namespace worth noting is the For the rest of this post, we’ll look more closely at some of the types that appear in Azure SDK clients public APIs.<\/p>\n As mentioned before, Azure SDK clients for HTTP-based services have service methods you can call to invoke an operation on the service. When the service sends back a response, the service method returns it to you as one of the response types defined in the Most service methods for operations on HTTP-based services return The only other member defined on You can also access HTTP headers from Some service operations let you retrieve a collection of resources held on the service. Many of these service APIs let you request the elements of the collection in separate groups, called pages<\/a>, to prevent the response size from becoming too large. Managing paged requests is relatively complex, and we wanted .NET users to be able to treat these collections like any other .NET collection type. The At its simplest, you can take the Under the hood, Further details regarding how to use Some service operations take a long time to process, so the service isn’t able to return a response immediately. Azure services use long-running operations (LROs)<\/a> to model these “service asynchronous” operations. Like managing paged requests, handling the sequence of calls needed to start an LRO, poll for updates, and then retrieve the result once the operation has completed can require writing complex code. The The following example shows how In this example, the As a developer working with Service methods that start an LRO on the service are named the same way as other service methods\u2014with the name of the operation. In our example, the service method is called More details of the Sometimes a service needs to notify you of an error, either because of a problem with the input it received or because of a problem on the service side. In .NET, when an error occurs, we throw an exception<\/a>. Today in Like other common types appearing in our public APIs, This makes the code you write to handle service errors work the same way as exception handling code in any .NET application. For example, to request a secret from Azure Key Vault, you might write:<\/p>\n More details of the So far, we’ve covered some of the most common types in Most of the time, you construct an Azure SDK client by passing the service endpoint and authentication details as we showed in the first example in this post. Sometimes, however, you might need to do something specialized, like work with a specific version of a service, or log the content of HTTP messages sent and received by the client. To do this, you need to pass special configuration options to the client using its The following example shows how to create an instance of an Azure Key Vault Notice that we created an instance of The set of things you can configure using The configurable options for diagnostics are defined on the If you need to make changes to the client’s HTTP pipeline, We hope this overview of the Learn about the Azure Core library and how it enables consistent usage patterns across the Azure SDK.<\/p>\n","protected":false},"author":41096,"featured_media":2816,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[701,734,706,703,920,161],"class_list":["post-2807","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-azure-sdk","tag-net","tag-azure","tag-azuresdk","tag-clientlibraries","tag-core","tag-dotnet"],"acf":[],"blog_post_summary":" Learn about the Azure Core library and how it enables consistent usage patterns across the Azure SDK.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/2807","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/users\/41096"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/comments?post=2807"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/2807\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media\/2816"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media?parent=2807"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/categories?post=2807"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/tags?post=2807"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Azure.Core<\/code> library and some of the most common types in it. We’ll start with a sample that introduces the standard usage pattern for an Azure SDK client, and show how Azure.Core<\/code> enables consistent use of that pattern across .NET clients. Then, we’ll give an overview of the library’s namespaces and how they organize the types that the library holds. Finally, we’ll go through some of the types you would use when building applications with the Azure SDK.<\/p>\nAzure.Core<\/code> library, but every Azure SDK language has an Azure Core library that implements similar patterns. The main features of the Azure Core libraries are described in the Azure SDK General Guidelines<\/a>, and the guidance regarding how client libraries should use them in each of the SDK languages are linked from there. Language-specific libraries can be found at the following links:<\/p>\n\n
azure-core-cpp<\/code><\/a><\/li>\nazcore<\/code><\/a><\/li>\nazure-core<\/code><\/a><\/li>\n@azure\/core-client<\/code><\/a><\/li>\nAzure.Core<\/code><\/a><\/li>\nazure-core<\/code><\/a><\/li>\n<\/ul>\nThe Azure SDK for .NET client pattern<\/h2>\n
Azure.AI.TextAnalytics<\/code> library to analyze the sentiment of some text with the Azure Text Analytics service.<\/p>\nusing Azure.AI.TextAnalytics;\r\nusing Azure.Identity;\r\n\r\nTextAnalyticsClient client = new TextAnalyticsClient(\r\n new Uri(\"https:\/\/example.com\"), \r\n new DefaultAzureCredential());\r\n\r\nDocumentSentiment analysis = client.AnalyzeSentiment(\"Today was great!\");\r\n\r\nConsole.WriteLine($\"Text sentiment is {analysis.Sentiment}.\");<\/code><\/pre>\nAzure.Core<\/code> support this pattern?<\/p>\nAzure.Core<\/code> types are used in both the client constructor and the service method. In the client constructor, we pass a DefaultAzureCredential<\/code><\/a> that is defined in the Azure.Identity<\/code> library, but it inherits from Azure.Core<\/code>‘s TokenCredential<\/code><\/a> type. Many Azure SDK clients take DefaultAzureCredential<\/code> or another subtype of TokenCredential<\/code> to authenticate with the service. The service method AnalyzeSentiment<\/code><\/a> returns a templated type Response<T><\/code><\/a> that is also defined in Azure.Core<\/code>. Response<T><\/code> has an implicit cast<\/a>)-t) to T<\/code>, which represents the value you retrieve from the service. In this case, our T<\/code> is the DocumentSentiment<\/code><\/a> model type.<\/p>\nAzure.Core<\/code> types in the following sections. But before we do, let’s talk about how the library is organized and what it’s doing at a high level.<\/p>\nWhat’s in
Azure.Core<\/code>?<\/h2>\nAzure.Core<\/code> is to help ensure consistency across Azure SDK libraries. That means it provides types that are used in the common patterns the client libraries implement. Some of these types are used in the client libraries’ public APIs, and some of them are used to implement common behaviors without being visible externally.<\/p>\n\n
Response<T><\/code> that appear in clients’ public APIs. Broadly speaking, types for end-user developers can be found in Azure.Core<\/code>‘s Azure<\/code> namespace<\/a>.<\/li>\nAzure.Core<\/code> namespace<\/a> or one of the specialized namespaces like Azure.Core.Serialization<\/code><\/a>.<\/li>\n<\/ol>\nAzure.Core.Pipeline<\/code> namespace<\/a>. Clients for HTTP-based Azure services use an HTTP pipeline<\/a> to exchange messages with the service, and Azure.Core<\/code> implements this pipeline and related types. The pipeline is composed of a sequence of policies that implement functionality common to all libraries, such as authentication, retry-handling logic, logging, and tracing. Requests flow through from the first policy to the transport, and responses travel back through them in the opposite direction. Details of the pipeline architecture are described in Jeffrey Richter’s article Inside the Azure SDK Architecture<\/a>, so we won’t go into many of those details here. Types that implement the pipeline are defined in the Azure.Core.Pipeline<\/code> namespace.<\/p>\nResponse types<\/h2>\n
Azure<\/code> namespace. The most common of these types are Response<T><\/code>, Pageable<T><\/code>, and Operation<T><\/code>.<\/p>\nResponse<T><\/h3>\n
Response<T><\/code>, like the AnalyzeSentiment<\/code> method shown at the start of this post. The T<\/code> in Response<T><\/code> is typically a model type\u2014a strongly typed representation of a resource defined by the service you’re working with. The model value can be accessed by using the implicit cast to T<\/code>, as shown in the sample, or by using Response<T><\/code>‘s Value<\/code> property. For example, the earlier sample could be rewritten to access the DocumentSentiment<\/code> model like this:<\/p>\nResponse<DocumentSentiment> response = client.AnalyzeSentiment(\"Today was great!\");\r\nDocumentSentiment analysis = response.Value;<\/code><\/pre>\nResponse<T><\/code> is the GetRawResponse<\/code> method. Calling GetRawResponse<\/code> returns a Response<\/code> object, which holds many of the raw details of the service’s HTTP response. Response<\/code> is considered a more advanced type and\u2014since the response’s payload has been abstracted into the strongly typed model\u2014it shouldn’t be needed for most common scenarios. This means you as a developer can focus on the application logic that uses the resource, without having to reason about the details of the messaging protocol. If you have a more advanced use case and need access to details that aren’t exposed on the model type, you can always get to those by calling GetRawResponse<\/code> on Response<T><\/code>. For example, if you needed to read the HTTP status code that the service returned, you might write:<\/p>\nResponse<DocumentSentiment> response = client.AnalyzeSentiment(\"Today was great!\");\r\nResponse httpResponse = response.GetRawResponse();\r\nConsole.WriteLine($\"HTTP status code is {httpResponse.Status}.\");<\/code><\/pre>\nResponse<\/code>. For example, if you needed more information about the response message’s content, you might write:<\/p>\nResponse<DocumentSentiment> response = client.AnalyzeSentiment(\"Today was great!\");\r\nResponse httpResponse = response.GetRawResponse();\r\nConsole.WriteLine(\"Content-Length is \" + httpResponse.Headers.ContentLength);\r\nConsole.WriteLine(\"Content-Type is \" + httpResponse.Headers.ContentType);<\/code><\/pre>\nPageable<T><\/h3>\n
Pageable<T><\/code> type lets you do this.<\/p>\nPageable<T><\/code> object returned from a service method that returns a collection, and foreach<\/code> over it to iterate through the items in the collection. For example, to retrieve a collection of ConfigurationSetting<\/code> values from the Azure App Configuration service and print them to the screen, you might write:<\/p>\nPageable<ConfigurationSetting> settings = client.GetConfigurationSettings();\r\nforeach (ConfigurationSetting setting in settings)\r\n{\r\n Console.WriteLine(setting.Value);\r\n}<\/code><\/pre>\nPageable<T><\/code> handles all the requests needed to obtain the first page, keep track of the most recent collection item you’ve seen, and request subsequent pages as needed. As a user, you just see an IEnumerable<\/code> that returns each element of the collection as you iterate through the enumeration.<\/p>\nPageable<T><\/code> and its async<\/code> counterpart AsyncPageable<T><\/code> can be found in the article Pagination with the Azure SDK for .NET<\/a>.<\/p>\nOperation<T><\/h3>\n
Operation<T><\/code> type is designed to make handling LROs a little easier.<\/p>\nOperation<T><\/code> is used when you search for addresses with the Azure Maps client.<\/p>\nList<SearchAddressQuery> queries = new List<SearchAddressQuery>\r\n{\r\n new SearchAddressQuery(\"One Microsoft Way, Redmond, WA 98052\"),\r\n new SearchAddressQuery(\"15010 NE 36th St, Redmond, WA 98052\")\r\n};\r\n\r\nSearchAddressBatchOperation operation = client.SearchAddressBatch(WaitUntil.Started, queries);\r\nResponse<SearchAddressBatchResult> result = operation.WaitForCompletion();<\/code><\/pre>\nSearchAddressBatch<\/code> method returns a SearchAddressBatchOperation<\/code><\/a> object, which inherits from Operation<T><\/code>. The T<\/code> in this example is a SearchAddressBatchResult<\/code>, and this is the model type that’s returned when the operation completes. Calling SearchAddressBatch<\/code> sends a message to the service telling it to begin the LRO. After that, the Operation<T><\/code> type internally polls the service to find out whether the service has finished computing the result. When the operation has completed, Operation<T><\/code> does the work to collect the output resource from the appropriate service endpoint and make it available on the client.<\/p>\nOperation<T><\/code>, you obtain the output value of the operation as a Response<T><\/code> from the WaitForCompletion<\/code> method, or from its async<\/code> counterpart, WaitForCompletionAsync<\/code>. Once the operation has successfully completed, you can also retrieve the result object from the operation’s Value<\/code> property, which is similar to the Value<\/code> property on Response<T><\/code>.<\/p>\nSearchAddressBatch<\/code>. You can change how the control flow returns from the service method by passing a WaitUntil<\/code> enum value. If you pass WaitUntil.Started<\/code>, the method will return after the first message is sent to the service telling it to start the operation. If you pass WaitUntil.Completed<\/code>, the method returns when the operation completes on the service and the result is available. For example, we could rewrite the previous example without the call to WaitForCompletion<\/code> by doing the following:<\/p>\nSearchAddressBatchOperation operation = client.SearchAddressBatch(WaitUntil.Completed, queries);\r\nResponse<SearchAddressBatchResult> result = operation.Value;<\/code><\/pre>\nOperation<T><\/code> API can be found in the documentation for the Operation<T><\/code> class<\/a>.<\/p>\nError types<\/h2>\n
Azure.Core<\/code>, we have only one exception type to indicate that a service request failed, and that is RequestFailedException<\/code><\/a>.<\/p>\nRequestFailedException<\/code> lives in the Azure<\/code> namespace. A few of the details of the error response are available as properties on the exception, including the response status code and the Azure-standard error code<\/a>. Beyond that, the client parses details from the error message returned by the service and makes them available in the exception’s Message<\/code> property. If details of the HTTP response are needed programmatically at runtime, they can be accessed from the Response<\/code> returned by calling the exception’s GetRawResponse<\/code> method, the same way you access these from Response<T><\/code>.<\/p>\ntry\r\n{\r\n KeyVaultSecret secret = client.GetSecret(\"NonexistentSecret\");\r\n}\r\ncatch (RequestFailedException e) when (e.Status == 404)\r\n{\r\n Console.WriteLine(\"ErrorCode \" + e.ErrorCode);\r\n}<\/code><\/pre>\nRequestFailedException<\/code> API can be found in the documentation for the RequestFailedException<\/code> class<\/a>.<\/p>\nClient configuration<\/h2>\n
Azure.Core<\/code>, types in the Azure<\/code> namespace that you could expect to see in any application built using the Azure SDK. The last type we’ll cover in this post is in the Azure.Core<\/code> namespace, and as you might expect from that, enables more advanced scenarios.<\/p>\nClientOptions<\/code> type.<\/p>\nSecretClient<\/code> that logs the content of request and response messages:<\/p>\nSecretClientOptions options = new SecretClientOptions()\r\n{\r\n Diagnostics =\r\n {\r\n IsLoggingContentEnabled = true\r\n }\r\n};\r\n\r\nSecretClient client = new SecretClient(Uri(\"https:\/\/example.com\"), new DefaultAzureCredential(), options);<\/code><\/pre>\nSecretClientOptions<\/code> and set its DiagnosticOptions<\/code> property IsLoggingContentEnabled<\/code> to true<\/code>. Every Azure SDK for .NET client constructor for an HTTP-based Azure service has an overload that takes a subtype of ClientOptions<\/code><\/a>. For the Key Vault SecretClient<\/code>, the client options type is called SecretClientOptions<\/code>. Every client-specific options type inherits from the ClientOptions<\/code> type in Azure.Core<\/code>. Some client options types add configuration options specific to the service, but deriving from Azure.Core<\/code>‘s ClientOptions<\/code><\/a> type means they all implement the same core set of functionality.<\/p>\nClientOptions<\/code> fall into four main buckets:<\/p>\n\n
DiagnosticOptions<\/code><\/a> type, and primarily control client logging and distributed tracing. How the client retries HTTP requests can be configured using the client options RetryOptions<\/code><\/a>, which let you configure the pipeline’s default retry policy, and change values like the time between retries and the maximum number of retries to send. Alternatively, you can take complete control of how retries are sent by replacing the default retry policy with your own RetryPolicy<\/code><\/a> implementation.<\/p>\nClientOptions<\/code> lets you insert your own policy implementations into the pipeline using the AddPolicy<\/code><\/a> method. And at the lowest level, you can replace the pipeline’s HttpPipelineTransport<\/code> with your own implementation using the client options Transport<\/code><\/a> property. To succeed at reconfiguring the client pipeline requires a good knowledge of types in the Azure.Core.Pipeline<\/code> namespace, and is a topic for a later blog post about Azure.Core<\/code>.<\/p>\nWhat else?<\/h2>\n
Azure.Core<\/code> library helps explain a little about the library and the types it contains, as well as patterns you’ll see across all our Azure SDK clients. We’re always looking for ways to make our products great for your specific needs, so leave suggestions and feedback in our GitHub repo<\/a>. If there are topics you’d like to dive into in more depth in a later blog post on Azure.Core<\/code>, let us know by posting in the comments, or leaving feedback for us on GitHub. We look forward to hearing from you about your experiences, and even more, to working with you to improve the Azure SDK!<\/p>\n","protected":false},"excerpt":{"rendered":"