#region Copyright notice and license // Copyright 2019 The gRPC Authors // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #endregion using Grpc.Core; using Grpc.Net.Client.Configuration; using Grpc.Net.Compression; using Microsoft.Extensions.Logging; namespace Grpc.Net.Client; /// /// An options class for configuring a . /// public sealed class GrpcChannelOptions { #if SUPPORT_LOAD_BALANCING private TimeSpan _initialReconnectBackoff; private TimeSpan? _maxReconnectBackoff; #endif /// /// Gets or sets the credentials for the channel. This setting is used to set for /// a channel. Connection transport layer security (TLS) is determined by the address used to create the channel. /// /// /// /// The channel credentials you use must match the address TLS setting. Use /// for an "http" address and for "https". /// /// /// The underlying used by the channel automatically loads root certificates /// from the operating system certificate store. /// Client certificates should be configured on HttpClient. See for details. /// /// public ChannelCredentials? Credentials { get; set; } /// /// Gets or sets the maximum message size in bytes that can be sent from the client. Attempting to send a message /// that exceeds the configured maximum message size results in an exception. /// /// A null value removes the maximum message size limit. Defaults to null. /// /// public int? MaxSendMessageSize { get; set; } /// /// Gets or sets the maximum message size in bytes that can be received by the client. If the client receives a /// message that exceeds this limit, it throws an exception. /// For compressed messages, the limit applies to both the compressed and decompressed message sizes. /// /// A null value removes the maximum message size limit. Defaults to 4,194,304 (4 MB). /// /// public int? MaxReceiveMessageSize { get; set; } /// /// Gets or sets the maximum retry attempts. This value limits any retry and hedging attempt values specified in /// the service config. /// /// Setting this value alone doesn't enable retries. Retries are enabled in the service config, which can be done /// using . /// /// /// A null value removes the maximum retry attempts limit. Defaults to 5. /// /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public int? MaxRetryAttempts { get; set; } /// /// Gets or sets the maximum buffer size in bytes that can be used to store sent messages when retrying /// or hedging calls. If the buffer limit is exceeded, then no more retry attempts are made and all /// hedging calls but one will be canceled. This limit is applied across all calls made using the channel. /// /// Setting this value alone doesn't enable retries. Retries are enabled in the service config, which can be done /// using . /// /// /// A null value removes the maximum retry buffer size limit. Defaults to 16,777,216 (16 MB). /// /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public long? MaxRetryBufferSize { get; set; } /// /// Gets or sets the maximum buffer size in bytes that can be used to store sent messages when retrying /// or hedging calls. If the buffer limit is exceeded, then no more retry attempts are made and all /// hedging calls but one will be canceled. This limit is applied to one call. /// /// Setting this value alone doesn't enable retries. Retries are enabled in the service config, which can be done /// using . /// /// /// A null value removes the maximum retry buffer size limit per call. Defaults to 1,048,576 (1 MB). /// /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public long? MaxRetryBufferPerCallSize { get; set; } /// /// Gets or sets a collection of compression providers. /// public IList? CompressionProviders { get; set; } /// /// Gets or sets the logger factory used by the channel. If no value is specified then the channel /// attempts to resolve an from the . /// public ILoggerFactory? LoggerFactory { get; set; } /// /// Gets or sets the used by the channel to make HTTP calls. /// /// /// /// By default a specified here will not be disposed with the channel. /// To dispose the with the channel you must set /// to true. /// /// /// Only one HTTP caller can be specified for a channel. An error will be thrown if this is configured /// together with . /// /// public HttpClient? HttpClient { get; set; } /// /// Gets or sets the used by the channel to make HTTP calls. /// /// /// /// By default a specified here will not be disposed with the channel. /// To dispose the with the channel you must set /// to true. /// /// /// Only one HTTP caller can be specified for a channel. An error will be thrown if this is configured /// together with . /// /// public HttpMessageHandler? HttpHandler { get; set; } /// /// Gets or sets a value indicating whether the underlying or /// should be disposed when the instance is disposed. /// The default value is false. /// /// /// This setting is used when a or value is specified. /// If they are not specified then the channel will create an internal HTTP caller that is always disposed /// when the channel is disposed. /// public bool DisposeHttpClient { get; set; } /// /// Gets or sets a value indicating whether clients will throw for a call when its /// is triggered or its is exceeded. /// The default value is false. /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public bool ThrowOperationCanceledOnCancellation { get; set; } /// /// Gets or sets a value indicating whether a gRPC call's are used by an insecure channel. /// The default value is false. /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// /// /// /// The default value for this property is false, which causes an insecure channel to ignore a gRPC call's . /// Sending authentication headers over an insecure connection has security implications and shouldn't be done in production environments. /// /// /// If this property is set to true, call credentials are always used by a channel. /// /// public bool UnsafeUseInsecureChannelCallCredentials { get; set; } /// /// Gets or sets the service config for a gRPC channel. A service config allows service owners to publish parameters /// to be automatically used by all clients of their service. A service config can also be specified by a client /// using this property. /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public ServiceConfig? ServiceConfig { get; set; } #if SUPPORT_LOAD_BALANCING /// /// Gets or sets a value indicating whether resolving a service config from the /// is disabled. /// The default value is false. /// /// A hint is provided to the resolver that it shouldn't fetch a service config. /// If a service config is returned by then resolver then it is ignored. /// /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public bool DisableResolverServiceConfig { get; set; } /// /// Gets or sets the the maximum time between subsequent connection attempts. /// /// The reconnect backoff starts at an initial backoff and then exponentially increases between attempts, up to the maximum reconnect backoff. /// Reconnect backoff adds a jitter to randomize the backoff. This is done to avoid spikes of connection attempts. /// /// /// A null value removes the maximum reconnect backoff limit. The default value is 120 seconds. /// /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public TimeSpan? MaxReconnectBackoff { get => _maxReconnectBackoff; set { if (value <= TimeSpan.Zero) { throw new ArgumentException("Maximum reconnect backoff must be greater than zero."); } _maxReconnectBackoff = value; } } /// /// Gets or sets the time between the first and second connection attempts. /// /// The reconnect backoff starts at an initial backoff and then exponentially increases between attempts, up to the maximum reconnect backoff. /// Reconnect backoff adds a jitter to randomize the backoff. This is done to avoid spikes of connection attempts. /// /// /// Defaults to 1 second. /// /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public TimeSpan InitialReconnectBackoff { get => _initialReconnectBackoff; set { if (value <= TimeSpan.Zero) { throw new ArgumentException("Initial reconnect backoff must be greater than zero."); } _initialReconnectBackoff = value; } } #endif /// /// Gets or sets the the channel uses to resolve types. /// /// Note: Experimental API that can change or be removed without any prior notice. /// /// public IServiceProvider? ServiceProvider { get; set; } /// /// Gets or sets the HTTP version to use when making gRPC calls. /// /// When a is specified the value will be set on /// as gRPC calls are made. Changing this property allows the HTTP version of gRPC calls to /// be overridden. /// /// /// A null value doesn't override the HTTP version of gRPC calls. Defaults to 2.0. /// /// public Version? HttpVersion { get; set; } #if NET5_0_OR_GREATER /// /// Gets or sets the HTTP policy to use when making gRPC calls. /// /// When a is specified the value will be set on /// as gRPC calls are made. The policy determines how is interpreted when /// the final HTTP version is negotiated with the server. Changing this property allows the HTTP /// version of gRPC calls to be overridden. /// /// /// A null value doesn't override the HTTP policy of gRPC calls. Defaults to . /// /// public HttpVersionPolicy? HttpVersionPolicy { get; set; } #endif internal T ResolveService(T defaultValue) { return (T?)ServiceProvider?.GetService(typeof(T)) ?? defaultValue; } /// /// Initializes a new instance of the class. /// public GrpcChannelOptions() { MaxReceiveMessageSize = GrpcChannel.DefaultMaxReceiveMessageSize; #if SUPPORT_LOAD_BALANCING _maxReconnectBackoff = TimeSpan.FromTicks(GrpcChannel.DefaultMaxReconnectBackoffTicks); _initialReconnectBackoff = TimeSpan.FromTicks(GrpcChannel.DefaultInitialReconnectBackoffTicks); #endif MaxRetryAttempts = GrpcChannel.DefaultMaxRetryAttempts; MaxRetryBufferSize = GrpcChannel.DefaultMaxRetryBufferSize; MaxRetryBufferPerCallSize = GrpcChannel.DefaultMaxRetryBufferPerCallSize; } }