Table of Contents

Class ClientConfig

Namespace
Amazon.Runtime
Assembly
AWSSDK.Core.dll

This class is the base class of all the configurations settings to connect to a service.

[CLSCompliant(false)]
public abstract class ClientConfig : IClientConfig
Inheritance
ClientConfig
Implements
Inherited Members
Extension Methods

Constructors

ClientConfig() 

public ClientConfig()

ClientConfig(IDefaultConfigurationProvider) 

protected ClientConfig(IDefaultConfigurationProvider defaultConfigurationProvider)

Parameters

defaultConfigurationProvider IDefaultConfigurationProvider

Fields

MaxTimeout 

public static readonly TimeSpan MaxTimeout

Field Value

TimeSpan

Properties

AWSTokenProvider 

public IAWSTokenProvider AWSTokenProvider { get; set; }

Property Value

IAWSTokenProvider

AllowAutoRedirect

This flag controls if .NET HTTP infrastructure should follow redirection responses (e.g. HTTP 307 - temporary redirect).

public bool AllowAutoRedirect { get; set; }

Property Value

bool

AuthenticationRegion

Gets and sets the AuthenticationRegion property. Used in AWS4 request signing, this is an optional property; change it only if the region cannot be determined from the service endpoint.

public string AuthenticationRegion { get; set; }

Property Value

string

AuthenticationServiceName

Gets and sets the AuthenticationServiceName property. Used in AWS4 request signing, this is the short-form name of the service being called.

public string AuthenticationServiceName { get; set; }

Property Value

string

BufferSize

Gets and Sets the BufferSize property. The BufferSize controls the buffer used to read in from input streams and write out to the request.

public int BufferSize { get; set; }

Property Value

int

CacheHttpClient

This is a switch used for performance testing and is not intended for production applications to change. This switch may be removed in a future version of the SDK as the .NET Core platform matures.

If true, the HttpClient is cached and reused for every request made by the service client and shared with other service clients.

For the .NET Core platform this is default to true because the HttpClient manages the connection pool. 

public bool CacheHttpClient { get; set; }

Property Value

bool

ClockOffset

The calculated clock skew correction for a specific endpoint, if there is one. This field will be set if a service call resulted in an exception and the SDK has determined that there is a difference between local and server times.

If is set to true, this value will still be set to the correction, but it will not be used by the SDK and clock skew errors will not be retried.

public TimeSpan ClockOffset { get; }

Property Value

TimeSpan

CorrectedUtcNow

Returns the current UTC now after clock correction for this endpoint.

[Obsolete("Please use CorrectClockSkew.GetCorrectedUtcNowForEndpoint(string endpoint) instead.", false)]
public DateTime CorrectedUtcNow { get; }

Property Value

DateTime

DefaultConfiguration 

protected IDefaultConfiguration DefaultConfiguration { get; }

Property Value

IDefaultConfiguration

DefaultConfigurationMode

Specify a DefaultConfigurationMode to use.

Returns the DefaultConfigurationMode that will be used. If none is specified, than the correct one is computed by IDefaultConfigurationProvider. 
public DefaultConfigurationMode DefaultConfigurationMode { get; set; }

Property Value

DefaultConfigurationMode

DisableHostPrefixInjection

Gets and sets the DisableHostPrefixInjection flag. If true, host prefix injection will be disabled for this client, the default value of this flag is false. Host prefix injection prefixes the service endpoint with request members from APIs which use this feature. Example: for a hostPrefix of "foo-name." and a endpoint of "service.region.amazonaws.com" the default behavior is to prefix the endpoint with the hostPrefix resulting in a final endpoint of "foo-name.service.region.amazonaws.com". Setting DisableHostPrefixInjection to true will disable hostPrefix injection resulting in a final endpoint of "service.region.amazonaws.com" regardless of the value of hostPrefix. E.g. You may want to disable host prefix injection for testing against a local mock endpoint.

public bool DisableHostPrefixInjection { get; set; }

Property Value

bool

DisableLogging

Gets and sets the DisableLogging. If true logging for this client will be disabled.

public bool DisableLogging { get; set; }

Property Value

bool

EndpointDiscoveryCacheLimit

Returns the maximum number of discovered endpoints that can be stored within the cache for the client. The default limit is 1000 cache entries.

public int EndpointDiscoveryCacheLimit { get; set; }

Property Value

int

EndpointDiscoveryEnabled

Returns the flag indicating if endpoint discovery should be enabled or disabled for operations that are not required to use endpoint discovery.

public bool EndpointDiscoveryEnabled { get; set; }

Property Value

bool

EndpointProvider

Gets and sets of the EndpointProvider property. This property is used for endpoints resolution. During service client creation it is set to service's default generated EndpointProvider, but can be changed to use custom user supplied EndpointProvider.

public IEndpointProvider EndpointProvider { get; set; }

Property Value

IEndpointProvider

FastFailRequests

Under Adaptive retry mode, this flag determines if the client should wait for a send token to become available or don't block and fail the request immediately if a send token is not available.

public bool FastFailRequests { get; set; }

Property Value

bool

HttpClientCacheSize

If CacheHttpClient is set to true then HttpClientCacheSize controls the number of HttpClients cached.

The default value is 1 which is suitable for Windows and for all other platforms that have HttpClient implementations using SocketsHttpHandler (.NET Core 2.1 and higher). 

public int HttpClientCacheSize { get; set; }

Property Value

int

HttpClientFactory 

public HttpClientFactory HttpClientFactory { get; set; }

Property Value

HttpClientFactory

IsMaxErrorRetrySet

Determines if MaxErrorRetry has been manually set.

public bool IsMaxErrorRetrySet { get; }

Property Value

bool

LogMetrics

Flag on whether to log metrics for service calls.

This can be set in the application's configs, as below:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <appSettings>
        <add key="AWSLogMetrics" value"true"/>
    </appSettings>
</configuration>
public bool LogMetrics { get; set; }

Property Value

bool

LogResponse

Gets and sets the LogResponse property. If this property is set to true, the service response is logged. The size of response being logged is controlled by the AWSConfigs.LoggingConfig.LogResponsesSizeLimit property.

public bool LogResponse { get; set; }

Property Value

bool

MaxConnectionsPerServer

Get or set the value to use for MaxConnectionsPerServer on requests. If this property is null, MaxConnectionsPerServer will be left at its default value of MaxValue.

public int? MaxConnectionsPerServer { get; set; }

Property Value

int?

MaxErrorRetry

Returns the flag indicating how many retry HTTP requests an SDK should make for a single SDK operation invocation before giving up. This flag will return 4 when the RetryMode is set to "Legacy" which is the default. For RetryMode values of "Standard" or "Adaptive" this flag will return 2. In addition to the values returned that are dependent on the RetryMode, the value can be set to a specific value by using the AWS_MAX_ATTEMPTS environment variable, max_attempts in the shared configuration file, or by setting a value directly on this property. When using AWS_MAX_ATTEMPTS or max_attempts the value returned from this property will be one less than the value entered because this flag is the number of retry requests, not total requests. To learn more about the RetryMode property that affects the values returned by this flag, see RetryMode.

public int MaxErrorRetry { get; set; }

Property Value

int

ProgressUpdateInterval

Gets or sets the interval at which progress update events are raised for upload operations. By default, the progress update events are raised at every 100KB of data transferred.

If the value of this property is set less than ClientConfig.BufferSize, progress updates events will be raised at the interval specified by ClientConfig.BufferSize. 

public long ProgressUpdateInterval { get; set; }

Property Value

long

ProxyCredentials

Credentials to use with a proxy.

public ICredentials ProxyCredentials { get; set; }

Property Value

ICredentials

ProxyHost

Gets and sets of the ProxyHost property.

public string ProxyHost { get; set; }

Property Value

string

ProxyPort

Gets and sets of the ProxyPort property.

public int ProxyPort { get; set; }

Property Value

int

ReadEntireResponse

Gets and sets the ReadEntireResponse property. NOTE: This property does not effect response processing and is deprecated. To enable response logging, the ClientConfig.LogResponse and AWSConfigs.LoggingConfig properties can be used.

[Obsolete("This property does not effect response processing and is deprecated.To enable response logging, the ClientConfig.LogResponse and AWSConfigs.LoggingConfig.LogResponses properties can be used.")]
public bool ReadEntireResponse { get; set; }

Property Value

bool

ReadWriteTimeout

Overrides the default read-write timeout value.

[Obsolete("ReadWriteTimeout is not consumed in asynchronous HTTP requests. Please use a cancellation token to handle stream read/write timeouts.")]
public TimeSpan? ReadWriteTimeout { get; set; }

Property Value

TimeSpan?

Remarks

If the value is set, the value is assigned to the ReadWriteTimeout property of the HttpWebRequest object used to send requests.

The timeout specified is null. The timeout specified is less than or equal to zero and is not Infinite.
See Also

RegionEndpoint

Gets and sets the RegionEndpoint property. The region constant that determines the endpoint to use.

Setting this property to null will force the SDK to recalculate the RegionEndpoint value based on App/WebConfig, environment variables, profile, etc.

RegionEndpoint and ServiceURL are mutually exclusive properties. Whichever property is set last will cause the other to automatically be reset to null. 

public RegionEndpoint RegionEndpoint { get; set; }

Property Value

RegionEndpoint

RegionEndpointServiceName

The constant used to lookup in the region hash the endpoint.

public abstract string RegionEndpointServiceName { get; }

Property Value

string

ResignRetries

Flag on whether to resign requests on retry or not. For Amazon S3 and Amazon Glacier this value will always be set to true.

public bool ResignRetries { get; set; }

Property Value

bool

RetryMode

Returns the flag indicating the current mode in use for request retries and influences the value returned from MaxErrorRetry. The default value is RequestRetryMode.Legacy. This flag can be configured by using the AWS_RETRY_MODE environment variable, retry_mode in the shared configuration file, or by setting this value directly.

public RequestRetryMode RetryMode { get; set; }

Property Value

RequestRetryMode

ServiceURL

Gets and sets of the ServiceURL property. This is an optional property; change it only if you want to try a different service endpoint.

RegionEndpoint and ServiceURL are mutually exclusive properties. Whichever property is set last will cause the other to automatically be reset to null. 

public string ServiceURL { get; set; }

Property Value

string

ServiceVersion

Gets Service Version

public abstract string ServiceVersion { get; }

Property Value

string

SignatureMethod

Gets and sets of the signatureMethod property.

public SigningAlgorithm SignatureMethod { get; set; }

Property Value

SigningAlgorithm

SignatureVersion

Gets and sets of the SignatureVersion property.

Note: This property exists for backward compatibility but is no longer used by any service other than S3.

public string SignatureVersion { get; set; }

Property Value

string

ThrottleRetries

Enable or disable the Retry Throttling feature by setting the ThrottleRetries flag to True/False respectively. Retry Throttling is a feature that intelligently throttles retry attempts when a large percentage of requests are failing and retries are unsuccessful as well. In such situations the allotted retry capacity for the service URL will be drained until requests start to succeed again. Once the requisite capacity is available, retries would be permitted again. When retries are throttled, the service enters a fail-fast behaviour as the traditional retry attempt for the request would be circumvented. Hence, errors will resurface quickly. This will result in a greater number of exceptions but prevents requests being tied up in unsuccessful retry attempts. Note: Retry Throttling is enabled by default. Set the ThrottleRetries flag to false to switch off this feature.

public bool ThrottleRetries { get; set; }

Property Value

bool

Timeout 

public TimeSpan? Timeout { get; set; }

Property Value

TimeSpan?

Remarks

If the value is set, the value is assigned to the Timeout property of the HttpWebRequest/HttpClient object used to send requests.

Please specify a timeout value only if the operation will not complete within the default intervals specified for an HttpWebRequest/HttpClient.

Exceptions

ArgumentNullException

The timeout specified is null.

ArgumentOutOfRangeException

The timeout specified is less than or equal to zero and is not Infinite.

See Also

UseAlternateUserAgentHeader

When set to true, the service client will use the x-amz-user-agent header instead of the User-Agent header to report version and environment information to the AWS service.

Note: This is especially useful when using a platform like WebAssembly which doesn't allow to specify the User-Agent header.

public bool UseAlternateUserAgentHeader { get; set; }

Property Value

bool

UseDualstackEndpoint

Configures the endpoint calculation for a service to go to a dual stack (ipv6 enabled) endpoint for the configured region.

public bool UseDualstackEndpoint { get; set; }

Property Value

bool

Remarks

Note: AWS services are enabling dualstack endpoints over time. It is your responsibility to check that the service actually supports a dualstack endpoint in the configured region before enabling this option for a service.

UseFIPSEndpoint

Configures the endpoint calculation to go to a FIPS (https://aws.amazon.com/compliance/fips/) endpoint for the configured region.

public bool UseFIPSEndpoint { get; set; }

Property Value

bool

UseHttp

Gets and sets the UseHttp. If this property is set to true, the client attempts to use HTTP protocol, if the target endpoint supports it. By default, this property is set to false.

public bool UseHttp { get; set; }

Property Value

bool

Remarks

This does not apply if an explicit ServiceURL is specified.

UserAgent

Gets and sets of the UserAgent property.

public abstract string UserAgent { get; }

Property Value

string

Methods

DetermineDnsSuffix()

Given this client configuration, return a DNS suffix for service endpoint url.

[Obsolete("This operation is obsoleted because as of version 3.7.100 endpoint is resolved using a newer system that uses request level parameters to resolve the endpoint.")]
public virtual string DetermineDnsSuffix()

Returns

string

DetermineServiceURL()

Given this client configuration, return a string form ofthe service endpoint url.

[Obsolete("This operation is obsoleted because as of version 3.7.100 endpoint is resolved using a newer system that uses request level parameters to resolve the endpoint.")]
public virtual string DetermineServiceURL()

Returns

string

GetTimeoutValue(TimeSpan?, TimeSpan?)

Returns the request timeout value if its value is set, else returns client timeout value.

public static TimeSpan? GetTimeoutValue(TimeSpan? clientTimeout, TimeSpan? requestTimeout)

Parameters

clientTimeout TimeSpan?
requestTimeout TimeSpan?

Returns

TimeSpan?

GetWebProxy()

Returns a WebProxy instance configured to match the proxy settings in the client configuration.

public IWebProxy GetWebProxy()

Returns

IWebProxy

Initialize() 

protected virtual void Initialize()

SetUseNagleIfAvailable(bool)

Enable or disable the Nagle algorithm on the underlying http client.

This method is not intended to be called by consumers of the AWS SDK for .NET

public void SetUseNagleIfAvailable(bool useNagle)

Parameters

useNagle bool

SetWebProxy(IWebProxy)

Unpacks the host, port and any credentials info into the instance's proxy-related fields. Unlike the SetWebProxy implementation on .NET 3.5/4.5,the Host and the Port are not reconstructed from the input proxyuri

public void SetWebProxy(IWebProxy proxy)

Parameters

proxy IWebProxy

The proxy details

Validate()

Performs validation on this config object. Throws exception if any of the required values are missing/invalid.

public virtual void Validate()

ValidateTimeout(TimeSpan?)

Throw an exception if the boxed TimeSpan parameter doesn't have a value or is out of range.

public static void ValidateTimeout(TimeSpan? timeout)

Parameters

timeout TimeSpan?