When using Azure SDK .NET client libraries in high throughput applications, it’s important to know how to maximize performance and avoid extra allocations while preventing bugs that could be introduced by accessing data from multiple threads. This article covers the best practices for using clients and models efficiently.<\/p>\n
The main rule of Azure SDK client lifetime management is: treat clients as singletons.<\/strong><\/p>\n There is no need to keep more than one instance of a client for a given set of constructor parameters or client options. This can be implemented in many ways: creating an instance once and passing it around as a parameter, storing an instance in a field, or registering it as a singleton in a dependency injection container of your choice.<\/p>\n \u274c Bad (extra allocations and initialization):<\/p>\n \u2714\ufe0f Good:<\/p>\n \u2714\ufe0f Also good:<\/p>\n We guarantee that all client instance methods are thread-safe and independent of each other (guideline<\/a>). This ensures that the recommendation of reusing client instances is always safe, even across threads.<\/p>\n \u2714\ufe0f Good:<\/p>\n Because most model use-cases involve a single thread and to avoid incurring an extra synchronization cost the input and output models of the client methods are non-thread-safe and can only be accessed by one thread at a time. The following sample illustrates a bug where accessing a model from multiple threads might cause an undefined behavior.<\/p>\n \u274c Bad:<\/p>\n If you need to access the model from different threads use a synchronization primitive.<\/p>\n \u2714\ufe0f Good:<\/p>\n Clients are immutable after being created, which also makes them safe to share and reuse safely (guideline<\/a>). This means that after the client is constructed, you cannot change the endpoint it connects to, the credential, and other values passed via the client options.<\/p>\n \u274c Bad (configuration changes are ignored):<\/p>\n NOTE:<\/strong> An important exception from this rule are credential type implementations that are required to support rolling the key after the client was created (guideline<\/a>). Examples of such types include AzureKeyCredential<\/a> and StorageSharedKeyCredential<\/a>. This feature is to enable long-running applications while using limited-time keys that need to be rolled periodically without requiring application restart or client re-creation.<\/p>\n One question that comes up often is why aren’t HTTP-based Azure clients implementing If you provide a custom instance of If you are using Azure SDK clients in an ASP.NET Core application, client lifetime management can be simplified with the Microsoft.Extensions.Azure package that provides seamless integration of Azure clients with the ASP.NET Core dependency injection and configuration systems. See the Best practices for using Azure SDK with ASP.NET Core<\/a> blog post or Microsoft.Extensions.Azure package readme<\/a> for details.<\/p>\n","protected":false},"excerpt":{"rendered":" When using Azure SDK .NET client libraries in high throughput applications, it’s important to know how to maximize performance and avoid extra allocations while preventing bugs that could be introduced by accessing data from multiple threads. This article covers the best practices for using clients and models efficiently. Client lifetime The main rule of Azure […]<\/p>\n","protected":false},"author":31981,"featured_media":388,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[701,706,703,707,702,705,704],"class_list":["post-233","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-azure-sdk","tag-net","tag-azuresdk","tag-clientlibraries","tag-clientlifetime","tag-clients","tag-sdk","tag-threadsafety"],"acf":[],"blog_post_summary":" When using Azure SDK .NET client libraries in high throughput applications, it’s important to know how to maximize performance and avoid extra allocations while preventing bugs that could be introduced by accessing data from multiple threads. This article covers the best practices for using clients and models efficiently. Client lifetime The main rule of Azure […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/233","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\/31981"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/comments?post=233"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/233\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media\/388"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media?parent=233"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/categories?post=233"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/tags?post=233"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}foreach (var secretName in secretNames)\r\n{\r\n var client = new SecretClient(\r\n new Uri(\"<secrets_endpoint>\"), \r\n new DefaultAzureCredential());\r\n KeyVaultSecret secret = client.GetSecret(secretName);\r\n \/\/ code omitted for brevity\r\n}\r\n<\/code><\/pre>\nvar client = new SecretClient(\r\n new Uri(\"<secrets_endpoint>\"),\r\n new DefaultAzureCredential());\r\nforeach (var secretName in secretNames)\r\n{\r\n KeyVaultSecret secret = client.GetSecret(secretName);\r\n \/\/ code omitted for brevity\r\n}\r\n<\/code><\/pre>\npublic class Program\r\n{\r\n internal static SecretClient Client;\r\n\r\n public static void Main()\r\n {\r\n Client = new SecretClient(\r\n new Uri(\"<secrets_endpoint>\"), \r\n new DefaultAzureCredential());\r\n }\r\n}\r\n\r\npublic class OtherClass\r\n{\r\n public string DoWork()\r\n {\r\n KeyVaultSecret secret = Program.Client.GetSecret(settingName);\r\n \/\/ code omitted for brevity\r\n }\r\n}\r\n<\/code><\/pre>\nThread-safety: Clients are thread-safe<\/h2>\n
var client = new SecretClient(\r\n new Uri(\"<secrets_endpoint>\"),\r\n new DefaultAzureCredential());\r\n\r\nforeach (var secretName in secretNames)\r\n{\r\n \/\/ Using clients from parallel threads\r\n Task.Run(() => {\r\n \/\/ code that uses client here\r\n });\r\n}\r\n<\/code><\/pre>\nThread-safety: Models are not thread-safe<\/h2>\n
KeyVaultSecret newSecret = client.SetSecret(\"secret\", \"value\");\r\n\r\nforeach (var tag in tags)\r\n{\r\n \/\/ Don't use model type from parallel threads\r\n Task.Run(() => newSecret.Properties.Tags[tag] = CalculateTagValue(tag));\r\n}\r\n\r\nclient.UpdateSecretProperties(newSecret.Properties);\r\n<\/code><\/pre>\nKeyVaultSecret newSecret = client.SetSecret(\"secret\", \"value\");\r\n\r\nforeach (var tag in tags)\r\n{\r\n Task.Run(() =>\r\n {\r\n lock (newSecret)\r\n {\r\n newSecret.Properties.Tags[tag] = CalculateTagValue(tag);\r\n }\r\n );\r\n}\r\n\r\nclient.UpdateSecretProperties(newSecret.Properties);\r\n<\/code><\/pre>\nClients are immutable<\/h2>\n
var secretClientOptions = new SecretClientOptions()\r\n{\r\n Retry = \r\n {\r\n Delay = TimeSpan.FromSeconds(5)\r\n }\r\n};\r\n\r\nvar mySecretClient = new SecretClient(\r\n new Uri(\"<...>\"),\r\n new DefaultAzureCredential(),\r\n secretClientOptions);\r\n\r\n\/\/ This has no effect on the mySecretClient instance\r\nsecretClientOptions.Retry.Delay = TimeSpan.FromSeconds(100);\r\n<\/code><\/pre>\nClients are not disposable: Shared HttpClient as default<\/h2>\n
IDisposable<\/code> while internally using an HttpClient<\/code> that is disposable? All Azure SDK clients, by default, use a single shared HttpClient<\/code> instance and don’t create any other resources that need to be actively freed. The shared client instance persists throughout the entire application lifetime.<\/p>\n\/\/ Both clients reuse the shared HttpClient and don't need to be disposed\r\nvar blobClient = new BlobClient(new Uri(sasUri));\r\nvar blobClient2 = new BlobClient(new Uri(sasUri2));\r\n<\/code><\/pre>\nExplicitly disposing customer provided HttpClient instances<\/h2>\n
HttpClient<\/code> to an Azure client, you become responsible for managing the HttpClient<\/code> lifetime and disposing it at the right time. We recommend following HttpClient<\/code> best practices<\/a> when customizing the transport.<\/p>\nvar httpClient = new HttpClient();\r\n\r\nvar clientOptions = new BlobClientOptions()\r\n{\r\n Transport = new HttpClientTransport(httpClient)\r\n}\r\n\r\n\/\/ Both client would use the HttpClient instance provided in clientOptions\r\nvar blobClient = new BlobClient(new Uri(sasUri), clientOptions);\r\nvar blobClient2 = new BlobClient(new Uri(sasUri2), clientOptions);\r\n\r\n\/\/...\r\n\r\n\/\/ some time later\r\nhttpClient.Dispose();\r\n<\/code><\/pre>\nUsing ASP.NET Core<\/h2>\n