Class ClientBuilderBase<TClient> (3.2.0) 

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
Name Description
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
Type Description
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
Type Description
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
Type Description
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
Type Description
String

DefaultGrpcAdapter

protected abstract GrpcAdapter DefaultGrpcAdapter { get; }

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

Property Value
Type Description
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
Type Description
EmulatorDetection

Endpoint

public string Endpoint { get; set; }

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

Property Value
Type Description
String

GrpcAdapter

public GrpcAdapter GrpcAdapter { get; set; }

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

Property Value
Type Description
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
Type Description
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
Type Description
String

Scopes

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

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

Property Value
Type Description
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
Type Description
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
Type Description
String

Methods

Build()

public abstract TClient Build()

Builds the resulting client.

Returns
Type Description
TClient

BuildAsync(CancellationToken)

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

Builds the resulting client asynchronously.

Parameter
Name Description
cancellationToken CancellationToken
Returns
Type Description
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
Name Description
source ClientBuilderBase<TOther>

The builder to copy from.
Type Parameter
Name Description
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
Type Description
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
Name Description
cancellationToken CancellationToken
Returns
Type Description
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
Type Description
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
Name Description
cancellationToken CancellationToken
Returns
Type Description
Task<ChannelCredentials>

GetChannelOptions()

protected virtual GrpcChannelOptions GetChannelOptions()

Returns the options to use when creating a channel.

Returns
Type Description
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
Type Description
ChannelPool

GetDefaultEndpoint()

protected abstract string GetDefaultEndpoint()

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

Returns
Type Description
String

GetDefaultScopes()

protected abstract IReadOnlyList<string> GetDefaultScopes()

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

Returns
Type Description
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
Name Description
requiredEmulatorEnvironmentVariables IEnumerable<String>

Required emulator environment variables.
allEmulatorEnvironmentVariables IEnumerable<String>

All emulator environment variables.
environmentVariableProvider Func<String, String>

The provider used to retrieve environment variables. This is used to faciliate testing, and defaults to using GetEnvironmentVariable(String).
Returns
Type Description
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
Type Description
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
Type Description
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
Name Description
message String

The message if the condition is violated.
values Object[]

The values to check for nullity.
Exceptions
Type Description
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
Name Description
message String

The message if the condition is violated.
controlling Object

The value controlling whether or not any other value can be non-null.
values Object[]

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