Class ClientBuilderBase<TClient>

public abstract class ClientBuilderBase<TClient>

Base class for API-specific builders.

Inheritance

Object > ClientBuilderBase<TClient>

Namespace

Google.Api.Gax.Grpc

Assembly

Google.Api.Gax.Grpc.dll

Type Parameter

NameDescription
TClient

The type of client created by this builder.

Constructors

ClientBuilderBase()

protected ClientBuilderBase()

Creates a new instance with no settings.

Properties

CallInvoker

public CallInvoker CallInvoker { get; set; }

The call invoker to use, or null to create the call invoker when the client is built.

Property Value
TypeDescription
CallInvoker

CanUseChannelPool

protected virtual bool CanUseChannelPool { get; }

Returns whether or not a channel pool can be used if a channel is required. The default behavior is to return true if and only if no quota project, scopes, credentials or token access method have been specified. Derived classes should override this property if there are other reasons why the channel pool should not be used.

Property Value
TypeDescription
Boolean

ChannelCredentials

public ChannelCredentials ChannelCredentials { get; set; }

The channel credentials to use, or null if credentials are being provided in a different way.

Property Value
TypeDescription
ChannelCredentials

CredentialsPath

public string CredentialsPath { get; set; }

The path to the credentials file to use, or null if credentials are being provided in a different way.

Property Value
TypeDescription
String

DefaultGrpcAdapter

protected abstract GrpcAdapter DefaultGrpcAdapter { get; }

Returns the default GrpcAdapter to use if GrpcAdapter is not set.

Property Value
TypeDescription
GrpcAdapter

EmulatorDetection

protected EmulatorDetection EmulatorDetection { get; set; }

The emulator detection policy to apply when building a client. Derived classes which support emulators should create public properties which delegate to this one. The default value is None.

Property Value
TypeDescription
EmulatorDetection

Endpoint

public string Endpoint { get; set; }

The endpoint to connect to, or null to use the default endpoint.

Property Value
TypeDescription
String

GrpcAdapter

public GrpcAdapter GrpcAdapter { get; set; }

The gRPC implementation to use, or null to use the default implementation.

Property Value
TypeDescription
GrpcAdapter

JsonCredentials

public string JsonCredentials { get; set; }

The credentials to use as a JSON string, or null if credentials are being provided in a different way.

Property Value
TypeDescription
String

QuotaProject

public string QuotaProject { get; set; }

The GCP project ID that should be used for quota and billing purposes. May be null.

Property Value
TypeDescription
String

Scopes

public IReadOnlyList<string> Scopes { get; set; }

The scopes to use, or null to use the default scopes.

Property Value
TypeDescription
IReadOnlyList<String>

TokenAccessMethod

public Func<string, CancellationToken, Task<string>> TokenAccessMethod { get; set; }

The token access method to use, or null if credentials are being provided in a different way.

Property Value
TypeDescription
Func<String, CancellationToken, Task<String>>
Remarks

To use a GoogleCredential for credentials, set this property using a method group conversion, e.g. TokenAccessMethod = credential.GetAccessTokenForRequestAsync

UserAgent

public string UserAgent { get; set; }

A custom user agent to specify in the channel metadata, or null if no custom user agent is required.

Property Value
TypeDescription
String

Methods

Build()

public abstract TClient Build()

Builds the resulting client.

Returns
TypeDescription
TClient

BuildAsync(CancellationToken)

public abstract Task<TClient> BuildAsync(CancellationToken cancellationToken = default(CancellationToken))

Builds the resulting client asynchronously.

Parameter
TypeNameDescription
CancellationTokencancellationToken
Returns
TypeDescription
Task<TClient>

CopyCommonSettings<TOther>(ClientBuilderBase<TOther>)

protected void CopyCommonSettings<TOther>(ClientBuilderBase<TOther> source)

Copies common settings from the specified builder into this one. This is a shallow copy.

Parameter
TypeNameDescription
ClientBuilderBase<TOther>source

The builder to copy from.

Type Parameter
NameDescription
TOther

The other client type

CreateCallInvoker()

protected virtual CallInvoker CreateCallInvoker()

Creates a call invoker synchronously. Override this method in a concrete builder type if more call invoker mechanisms are supported. This implementation calls GetChannelCredentials() if no call invoker is specified.

Returns
TypeDescription
CallInvoker

CreateCallInvokerAsync(CancellationToken)

protected virtual Task<CallInvoker> CreateCallInvokerAsync(CancellationToken cancellationToken)

Creates a call invoker asynchronously. Override this method in a concrete builder type if more call invoker mechanisms are supported. This implementation calls GetChannelCredentialsAsync(CancellationToken) if no call invoker is specified.

Parameter
TypeNameDescription
CancellationTokencancellationToken
Returns
TypeDescription
Task<CallInvoker>

GetChannelCredentials()

protected virtual ChannelCredentials GetChannelCredentials()

Obtains channel credentials synchronously. Override this method in a concrete builder type if more credential mechanisms are supported.

Returns
TypeDescription
ChannelCredentials

GetChannelCredentialsAsync(CancellationToken)

protected virtual Task<ChannelCredentials> GetChannelCredentialsAsync(CancellationToken cancellationToken)

Obtains channel credentials asynchronously. Override this method in a concrete builder type if more credential mechanisms are supported.

Parameter
TypeNameDescription
CancellationTokencancellationToken
Returns
TypeDescription
Task<ChannelCredentials>

GetChannelOptions()

protected virtual GrpcChannelOptions GetChannelOptions()

Returns the options to use when creating a channel.

Returns
TypeDescription
GrpcChannelOptions

The options to use when creating a channel.

GetChannelPool()

protected abstract ChannelPool GetChannelPool()

Returns the channel pool to use when no other options are specified. This method is not called unless CanUseChannelPool returns true, so if a channel pool is unavailable, override that property to return false and throw an exception from this method.

Returns
TypeDescription
ChannelPool

GetDefaultEndpoint()

protected abstract string GetDefaultEndpoint()

Returns the endpoint for this builder type, used if no endpoint is otherwise specified.

Returns
TypeDescription
String

GetDefaultScopes()

protected abstract IReadOnlyList<string> GetDefaultScopes()

Returns the default scopes for this builder type, used if no scopes are otherwise specified.

Returns
TypeDescription
IReadOnlyList<String>

GetEmulatorEnvironment(IEnumerable<String>, IEnumerable<String>, Func<String, String>)

protected Dictionary<string, string> GetEmulatorEnvironment(IEnumerable<string> requiredEmulatorEnvironmentVariables, IEnumerable<string> allEmulatorEnvironmentVariables, Func<string, string> environmentVariableProvider = null)

Performs basic emulator detection and validation based on the given environment variables. This method is expected to be called by a derived class that supports emulators, in order to perform the common work of checking whether the emulator is configured in the environment.

Parameters
TypeNameDescription
IEnumerable<String>requiredEmulatorEnvironmentVariables

Required emulator environment variables.

IEnumerable<String>allEmulatorEnvironmentVariables

All emulator environment variables.

Func<String, String>environmentVariableProvider

The provider used to retrieve environment variables. This is used to faciliate testing, and defaults to using GetEnvironmentVariable(String).

Returns
TypeDescription
Dictionary<String, String>

A key/value mapping of the emulator environment variables to their values, or null if the emulator should not be used.

Remarks

If the emulator should not be used, either due to being disabled in EmulatorDetection or the appropriate environment variables not being set, this method returns null.

Otherwise, a dictionary is returned mapping every value in allEmulatorEnvironmentVariables to the value in the environment. Any missing, empty or whitespace-only values are mapped to a null reference in the returned dictionary, but the entry will still be present (so callers can use an indexer with the returned dictionary for every environment variable passed in).

Exceptions
TypeCondition
InvalidOperationException

The configuration is inconsistent, e.g. due to some environment variables being set but not all the required ones, or any environment variables being set in a production-only environment.

Validate()

protected virtual void Validate()

Validates that the builder is in a consistent state for building. For example, it's invalid to call Build() on an instance which has both JSON credentials and a credentials path specified.

Exceptions
TypeCondition
InvalidOperationException

The builder is in an invalid state.

ValidateAtMostOneNotNull(String, Object[])

protected void ValidateAtMostOneNotNull(string message, params object[] values)

Validates that at most one of the given values is not null.

Parameters
TypeNameDescription
Stringmessage

The message if the condition is violated.

Object[]values

The values to check for nullity.

Exceptions
TypeCondition
InvalidOperationException

More than one value is null.

ValidateOptionExcludesOthers(String, Object, Object[])

protected void ValidateOptionExcludesOthers(string message, object controlling, params object[] values)

Validates that if controlling is not null, then every value in values is null.

Parameters
TypeNameDescription
Stringmessage

The message if the condition is violated.

Objectcontrolling

The value controlling whether or not any other value can be non-null.

Object[]values

The values checked for non-nullity if controlling is non-null.