Dive into the Amazon SDK for .NET’s Runtime Pipeline and Client Configuration

{"value":"We often hear from customers that optimizing the AWS SDK for .NET’s behavior when making API calls is an important feature. To make requests to Amazon Web Services, the SDK provides service clients for each AWS service. Configuration settings are used to enable features such as maximum length to wait for a request to complete, or specify API request retry behavior. These settings can improve your application’s performance and make your application more resilient to transient errors.\n\nIn this blog post, we will take a deep dive into three ways to configure the AWS service clients that are part of the AWS SDK for .NET. We will start by looking at the ClientConfig class, move onto subclassing AWS service clients, and end with how you can inject custom behavior into the AWS SDK for .NET’s runtime pipeline.\n\n### **Runtime pipeline overview**\nThe AWS SDK for .NET implements a consistent pattern for making API calls across all AWS services, as shown below.\n\nC#\n```\nusing Amazon.servicename;\nusing Amazon.servicename.Model;\n\nvar client = new AmazonservicenameClient();\noperationnameResponse response = await client.operationname(new operationnameRequest\n{\n RequestProperty1 = \"some data\"\n});\n```\nThe colored text represents placeholders that will vary per service. For example, for Amazon S3, “servicename” would be replaced with “S3”, making the service’s root namespace “Amazon.S3”. Each service operation (i.e., API call) has classes which model the request and response payloads. These classes reside in the “Amazon.servicename.Model” namespace – “Amazon.S3.Model” in this case. Service client classes also have a very consistent naming convention. Following our example, the service client class for S3 is AmazonS3Client. Looking at the S3 service’s operation of GetObject, the S3 client’s method signature is:\n\nC#\n```\nAmazon.S3.Model.GetObjectResponse GetObject(Amazon.S3.Model.GetObjectRequest request)\n```\nAs service operations execute, each request flows through a pipeline, known as the runtime pipeline, where it is processed by components known as pipeline handlers. The response received from the AWS service is also processed by the pipeline handlers, only in reverse order.\n\n\nFigure 1 – AWS SDK for .NET’s Runtime Pipeline and Handlers\n\nEach of these pipeline handlers provide specific behaviors. Some of the key pipeline handlers used by the AWS SDK for .NET are:\n- Metrics Handler – Logs API call execution times.\n- Retry Handler – Implements support for retry operations with support from Retry Policies.\n- Error Handler – Processes exceptions encountered as part of processing the request.\n- Http Handler – Contains logic for issuing an HTTP request that is independent of the underlying HTTP infrastructure.\n\nWhile all of the types mentioned in this blog post are currently public, those related to the runtime pipeline are in the Amazon.Runtime.Internal namespace and so are subject to change or removal. As of now, the runtime pipeline is the only means of modifying the behavior of AWS service requests in a centralized way.\n\nTwo options exist for customizing the runtime pipeline – setting configuration options for the pipeline handlers used by the SDK, or changing the pipeline handler list – either by modifying an existing pipeline handler or adding your own custom pipeline handler. Each of these can be achieved as noted in the below table.\n\n\nFigure 2 – AWS SDK for .NET Runtime Pipeline Customization Options\n\nIn the rest of this blog post, we will walkthrough how to use each of these approaches.\n\n### **Modifying Pipeline Handler Behavior**\nIf the only settings you need to change are available in the [ClientConfig class](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html), using this class is the easiest approach to configure the behavior of the SDK’s pipeline handlers. When a service client object is created, an instance of the ClientConfig class can be provided. If one is not provided, the service client will create an instance with default values. One of the easiest ways to create a ClientConfig instance is to use the [AWSSDK.Extensions.NETCore.Setup](https://www.nuget.org/packages/AWSSDK.Extensions.NETCore.Setup)NuGet package. This package provides extension methods that create the ClientConfig instance and populates it using a [.NET configuration provider](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-6.0) (e.g., JSON configuration provider). For example, if you had an appsettings.json file with this content\n\nJSON\n```\n{\n \"AWS\": {\n \"MaxErrorRetry\": 5,\n \"Timeout\": \"15000\"\n }\n}\n```\nYou could create a service client instance with these settings using the below code.\n\nC#\n```\npublic Startup(IConfiguration configuration) {\n var awsOptions = configuration.GetAWSOptions();\n var s3Client = awsOptions.CreateServiceClient<IAmazonS3>();\n}\n```\nWhen using the [AWSOptions class](https://github.com/aws/aws-sdk-net/blob/master/extensions/src/AWSSDK.Extensions.NETCore.Setup/AWSOptions.cs), the ClientConfig is copied to each instance of a service client created by the CreateServiceClient method. You can read more in the [Configuring AWS SDK with .NET Core](https://aws.amazon.com/cn/blogs/developer/configuring-aws-sdk-with-net-core/) blog post.\n\nIf you need specific service client instances to either have a unique set of pipeline handlers, or unique settings, subclassing would be a good option.\n\n### **Modifying Pipeline Handler List**\nAs mentioned earlier, pipeline handlers are a series of objects which process every request made to a service client. This implementation offers a decoupled design that allows for easy customization and extension of the request handling process. In this section, we will cover two ways with which you can customize the runtime pipeline’s list of pipeline handlers 1) subclassing each service client, and 2) using a centralized list of objects known as pipeline customizers.\n#### **Service Client Subclassing**\nThe first option to modify the pipeline is by subclassing the specific service client that you would like to customize. Each of the service specific clients provided by the Amazon SDK for .NET (e.g. AmazonS3Client) inherit some base functionality from AmazonServiceClient. In addition to providing the service specific operations, these subclasses can further extend the pipeline by overriding the CustomizeRuntimePipeline method to add/remove/replace pipeline handlers.\n\nIf your use case calls for additional modifications to a specific service client class, such as adding custom processing before or after a service request, you can accomplish this by subclassing a particular service client class, such as AmazonS3Client or AmazonDynamoDBClient. Doing so allows you to override the CustomizeRuntimePipeline and add your custom pipeline handler, as depicted below:\n\nC#\n```\npublic class CustomAmazonS3Client : AmazonS3Client {\n ...\n\n protected override void CustomizeRuntimePipeline(RuntimePipeline pipeline) {\n base.CustomizeRuntimePipeline(pipeline);\n pipeline.AddHandler(new MyCustomHandler());\n }\n}\n```\nIn addition to overriding and modifying the pipeline with your custom handler, you can also modify the configuration settings that get injected with your custom configuration when you subclass. This may be ideal when you would like your subclassed service client to utilize different settings than the rest of the service clients, because the latter will use the default application settings. You can create a customized client for a specific service that also contains some specific settings such as this example:\n\nC#\n```\npublic class CustomAmazonS3Client : AmazonS3Client {\n public CustomAmazonS3Client() : \n base(FallbackCredentialsFactory.GetCredentials(), \n new AmazonS3Config { MaxErrorRetry = 5, UseDualstackEndpoint = true, UseAccelerateEndpoint = true }) { }\n}\n```\nThe example above works fine when your use case only requires pipeline modifications for a specific service client, along with the advantage of updating the settings for only your custom service client. If your use case requires a customization that applies to all service clients, then accessing the RuntimePipelineCustomizerRegistry directly is be the best option.\n#### **Using the RuntimePipelineCustomizerRegistry**\nIn the Amazon.Runtime.Internal namespace resides the RuntimePipelineCustomizerRegistry class which allows you to modify the runtime pipeline for all service clients created. As of now, this is the only means of modifying the runtime pipeline for all service clients in a centralized way.\n\nAs each instance of a service client is created, any implementation of the IRuntimePipelineCustomizer interface registered with the RuntimePipelineCustomizerRegistry is called and can modify the runtime pipeline. The following is a sample implementation of IRuntimePipelineCustomizer.\n\nC#\n```\npublic class MyPipelineCustomizer : IRuntimePipelineCustomizer {\n public string UniqueName { get; } = nameof(MyPipelineCustomizer);\n\n /// <summary>\n /// Called on service clients as they are being constructed to customize their runtime pipeline.\n /// </summary>\n /// <param name=\"pipeline\">Runtime pipeline for newly created service clients.</param>\n /// <param name=\"type\">Type object for the service client being created</param>\n public void Customize(Type type, RuntimePipeline pipeline) {\n pipeline.AddHandler(new CustomHandler());\n }\n}\n```\nNow that the pipeline customizer is created, the next step is to register the instance with the RuntimePipeilneCustomizerRegistry Singleton.\n\nC#\n```\nRuntimePipelineCustomizerRegistry.Instance.Register(new MyPipelineCustomizer());\n```\nWith registration taken place, the MyPipelineCustomizer will be called every time a new service client is created so that the CustomHandler is added to its runtime pipeline.\n### **Conclusion**\nIn this post, we covered how you can optimize the behavior of the AWS SDK for .NET, and customize it according to your needs. We dove deep into the three ways to configure the AWS service clients available through the AWS SDK for .NET. We started by showing you how you can apply custom configuration by using the ClientConfig class, then we moved on to subclassing of AWS service clients, and lastly, we reviewed how to customize the behavior that can apply to all service clients.\n\n\n::: hljs-left\n\n**Carlos Santos**\n\n:::\n\nCarlos Santos is a Microsoft Specialist Solutions Architect with Amazon Web Services (AWS). In his role, Carlos helps customers through their cloud journey, leveraging his experience with application architecture, and distributed system design.\n\n\n::: hljs-left\n\n**JP Velasco**\n\n:::\n\nJP Velasco is a Technical Account Manager with Amazon Web Services (AWS) Enterprise Support. JP helps customers in their AWS journey by solving scaling and optimization challenges to deliver operational excellence in the cloud through the practice of continuous improvement and delivery.","render":"<p>We often hear from customers that optimizing the AWS SDK for .NET’s behavior when making API calls is an important feature. To make requests to Amazon Web Services, the SDK provides service clients for each AWS service. Configuration settings are used to enable features such as maximum length to wait for a request to complete, or specify API request retry behavior. These settings can improve your application’s performance and make your application more resilient to transient errors.</p>\n<p>In this blog post, we will take a deep dive into three ways to configure the AWS service clients that are part of the AWS SDK for .NET. We will start by looking at the ClientConfig class, move onto subclassing AWS service clients, and end with how you can inject custom behavior into the AWS SDK for .NET’s runtime pipeline.</p>\n<h3><a id=\"Runtime_pipeline_overview_4\"></a><strong>Runtime pipeline overview</strong></h3>\n<p>The AWS SDK for .NET implements a consistent pattern for making API calls across all AWS services, as shown below.</p>\n<p>C#</p>\n<pre><code class=\"lang-\">using Amazon.servicename;\nusing Amazon.servicename.Model;\n\nvar client = new AmazonservicenameClient();\noperationnameResponse response = await client.operationname(new operationnameRequest\n{\n RequestProperty1 = &quot;some data&quot;\n});\n</code></pre>\n<p>The colored text represents placeholders that will vary per service. For example, for Amazon S3, “servicename” would be replaced with “S3”, making the service’s root namespace “Amazon.S3”. Each service operation (i.e., API call) has classes which model the request and response payloads. These classes reside in the “Amazon.servicename.Model” namespace – “Amazon.S3.Model” in this case. Service client classes also have a very consistent naming convention. Following our example, the service client class for S3 is AmazonS3Client. Looking at the S3 service’s operation of GetObject, the S3 client’s method signature is:</p>\n<p>C#</p>\n<pre><code class=\"lang-\">Amazon.S3.Model.GetObjectResponse GetObject(Amazon.S3.Model.GetObjectRequest request)\n</code></pre>\n<p>As service operations execute, each request flows through a pipeline, known as the runtime pipeline, where it is processed by components known as pipeline handlers. The response received from the AWS service is also processed by the pipeline handlers, only in reverse order.</p>\n<p><img src=\"https://dev-media.amazoncloud.cn/91ddd299e7f744ac88381da8406aa9a6_image.png\" alt=\"image.png\" /><br />\nFigure 1 – AWS SDK for .NET’s Runtime Pipeline and Handlers</p>\n<p>Each of these pipeline handlers provide specific behaviors. Some of the key pipeline handlers used by the AWS SDK for .NET are:</p>\n<ul>\n<li>Metrics Handler – Logs API call execution times.</li>\n<li>Retry Handler – Implements support for retry operations with support from Retry Policies.</li>\n<li>Error Handler – Processes exceptions encountered as part of processing the request.</li>\n<li>Http Handler – Contains logic for issuing an HTTP request that is independent of the underlying HTTP infrastructure.</li>\n</ul>\n<p>While all of the types mentioned in this blog post are currently public, those related to the runtime pipeline are in the Amazon.Runtime.Internal namespace and so are subject to change or removal. As of now, the runtime pipeline is the only means of modifying the behavior of AWS service requests in a centralized way.</p>\n<p>Two options exist for customizing the runtime pipeline – setting configuration options for the pipeline handlers used by the SDK, or changing the pipeline handler list – either by modifying an existing pipeline handler or adding your own custom pipeline handler. Each of these can be achieved as noted in the below table.</p>\n<p><img src=\"https://dev-media.amazoncloud.cn/9fd141187744408393fbe48ff24a8060_image.png\" alt=\"image.png\" /><br />\nFigure 2 – AWS SDK for .NET Runtime Pipeline Customization Options</p>\n<p>In the rest of this blog post, we will walkthrough how to use each of these approaches.</p>\n<h3><a id=\"Modifying_Pipeline_Handler_Behavior_44\"></a><strong>Modifying Pipeline Handler Behavior</strong></h3>\n<p>If the only settings you need to change are available in the <a href=\"https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html\" target=\"_blank\">ClientConfig class</a>, using this class is the easiest approach to configure the behavior of the SDK’s pipeline handlers. When a service client object is created, an instance of the ClientConfig class can be provided. If one is not provided, the service client will create an instance with default values. One of the easiest ways to create a ClientConfig instance is to use the <a href=\"https://www.nuget.org/packages/AWSSDK.Extensions.NETCore.Setup\" target=\"_blank\">AWSSDK.Extensions.NETCore.Setup</a>NuGet package. This package provides extension methods that create the ClientConfig instance and populates it using a <a href=\"https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-6.0\" target=\"_blank\">.NET configuration provider</a> (e.g., JSON configuration provider). For example, if you had an appsettings.json file with this content</p>\n<p>JSON</p>\n<pre><code class=\"lang-\">{\n &quot;AWS&quot;: {\n &quot;MaxErrorRetry&quot;: 5,\n &quot;Timeout&quot;: &quot;15000&quot;\n }\n}\n</code></pre>\n<p>You could create a service client instance with these settings using the below code.</p>\n<p>C#</p>\n<pre><code class=\"lang-\">public Startup(IConfiguration configuration) {\n var awsOptions = configuration.GetAWSOptions();\n var s3Client = awsOptions.CreateServiceClient&lt;IAmazonS3&gt;();\n}\n</code></pre>\n<p>When using the <a href=\"https://github.com/aws/aws-sdk-net/blob/master/extensions/src/AWSSDK.Extensions.NETCore.Setup/AWSOptions.cs\" target=\"_blank\">AWSOptions class</a>, the ClientConfig is copied to each instance of a service client created by the CreateServiceClient method. You can read more in the <a href=\"https://aws.amazon.com/cn/blogs/developer/configuring-aws-sdk-with-net-core/\" target=\"_blank\">Configuring AWS SDK with .NET Core</a> blog post.</p>\n<p>If you need specific service client instances to either have a unique set of pipeline handlers, or unique settings, subclassing would be a good option.</p>\n<h3><a id=\"Modifying_Pipeline_Handler_List_69\"></a><strong>Modifying Pipeline Handler List</strong></h3>\n<p>As mentioned earlier, pipeline handlers are a series of objects which process every request made to a service client. This implementation offers a decoupled design that allows for easy customization and extension of the request handling process. In this section, we will cover two ways with which you can customize the runtime pipeline’s list of pipeline handlers 1) subclassing each service client, and 2) using a centralized list of objects known as pipeline customizers.</p>\n<h4><a id=\"Service_Client_Subclassing_71\"></a><strong>Service Client Subclassing</strong></h4>\n<p>The first option to modify the pipeline is by subclassing the specific service client that you would like to customize. Each of the service specific clients provided by the Amazon SDK for .NET (e.g. AmazonS3Client) inherit some base functionality from AmazonServiceClient. In addition to providing the service specific operations, these subclasses can further extend the pipeline by overriding the CustomizeRuntimePipeline method to add/remove/replace pipeline handlers.</p>\n<p>If your use case calls for additional modifications to a specific service client class, such as adding custom processing before or after a service request, you can accomplish this by subclassing a particular service client class, such as AmazonS3Client or AmazonDynamoDBClient. Doing so allows you to override the CustomizeRuntimePipeline and add your custom pipeline handler, as depicted below:</p>\n<p>C#</p>\n<pre><code class=\"lang-\">public class CustomAmazonS3Client : AmazonS3Client {\n ...\n\n protected override void CustomizeRuntimePipeline(RuntimePipeline pipeline) {\n base.CustomizeRuntimePipeline(pipeline);\n pipeline.AddHandler(new MyCustomHandler());\n }\n}\n</code></pre>\n<p>In addition to overriding and modifying the pipeline with your custom handler, you can also modify the configuration settings that get injected with your custom configuration when you subclass. This may be ideal when you would like your subclassed service client to utilize different settings than the rest of the service clients, because the latter will use the default application settings. You can create a customized client for a specific service that also contains some specific settings such as this example:</p>\n<p>C#</p>\n<pre><code class=\"lang-\">public class CustomAmazonS3Client : AmazonS3Client {\n public CustomAmazonS3Client() : \n base(FallbackCredentialsFactory.GetCredentials(), \n new AmazonS3Config { MaxErrorRetry = 5, UseDualstackEndpoint = true, UseAccelerateEndpoint = true }) { }\n}\n</code></pre>\n<p>The example above works fine when your use case only requires pipeline modifications for a specific service client, along with the advantage of updating the settings for only your custom service client. If your use case requires a customization that applies to all service clients, then accessing the RuntimePipelineCustomizerRegistry directly is be the best option.</p>\n<h4><a id=\"Using_the_RuntimePipelineCustomizerRegistry_98\"></a><strong>Using the RuntimePipelineCustomizerRegistry</strong></h4>\n<p>In the Amazon.Runtime.Internal namespace resides the RuntimePipelineCustomizerRegistry class which allows you to modify the runtime pipeline for all service clients created. As of now, this is the only means of modifying the runtime pipeline for all service clients in a centralized way.</p>\n<p>As each instance of a service client is created, any implementation of the IRuntimePipelineCustomizer interface registered with the RuntimePipelineCustomizerRegistry is called and can modify the runtime pipeline. The following is a sample implementation of IRuntimePipelineCustomizer.</p>\n<p>C#</p>\n<pre><code class=\"lang-\">public class MyPipelineCustomizer : IRuntimePipelineCustomizer {\n public string UniqueName { get; } = nameof(MyPipelineCustomizer);\n\n /// &lt;summary&gt;\n /// Called on service clients as they are being constructed to customize their runtime pipeline.\n /// &lt;/summary&gt;\n /// &lt;param name=&quot;pipeline&quot;&gt;Runtime pipeline for newly created service clients.&lt;/param&gt;\n /// &lt;param name=&quot;type&quot;&gt;Type object for the service client being created&lt;/param&gt;\n public void Customize(Type type, RuntimePipeline pipeline) {\n pipeline.AddHandler(new CustomHandler());\n }\n}\n</code></pre>\n<p>Now that the pipeline customizer is created, the next step is to register the instance with the RuntimePipeilneCustomizerRegistry Singleton.</p>\n<p>C#</p>\n<pre><code class=\"lang-\">RuntimePipelineCustomizerRegistry.Instance.Register(new MyPipelineCustomizer());\n</code></pre>\n<p>With registration taken place, the MyPipelineCustomizer will be called every time a new service client is created so that the CustomHandler is added to its runtime pipeline.</p>\n<h3><a id=\"Conclusion_125\"></a><strong>Conclusion</strong></h3>\n<p>In this post, we covered how you can optimize the behavior of the AWS SDK for .NET, and customize it according to your needs. We dove deep into the three ways to configure the AWS service clients available through the AWS SDK for .NET. We started by showing you how you can apply custom configuration by using the ClientConfig class, then we moved on to subclassing of AWS service clients, and lastly, we reviewed how to customize the behavior that can apply to all service clients.</p>\n<p><img src=\"https://dev-media.amazoncloud.cn/2f931bfc61d64a6abc3366bdb8cafbe6_image.png\" alt=\"image.png\" /></p>\n<div class=\"hljs-left\">\n<p><strong>Carlos Santos</strong></p>\n</div>\n<p>Carlos Santos is a Microsoft Specialist Solutions Architect with Amazon Web Services (AWS). In his role, Carlos helps customers through their cloud journey, leveraging his experience with application architecture, and distributed system design.</p>\n<p><img src=\"https://dev-media.amazoncloud.cn/080f925087b64c37bbd29ac80d5dddc7_image.png\" alt=\"image.png\" /></p>\n<div class=\"hljs-left\">\n<p><strong>JP Velasco</strong></p>\n</div>\n<p>JP Velasco is a Technical Account Manager with Amazon Web Services (AWS) Enterprise Support. JP helps customers in their AWS journey by solving scaling and optimization challenges to deliver operational excellence in the cloud through the practice of continuous improvement and delivery.</p>\n"}