Class ClientBuilderBase<TClient> (4.8.0)

Version latest

• 4.8.0 (latest)
• 4.4.0
• 4.3.1
• 4.2.0
• 4.0.0
• 3.2.0

public abstract class ClientBuilderBase<TClient>

Base class for API-specific builders.

Inheritance

object > ClientBuilderBase<TClient>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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(ServiceMetadata)

protected ClientBuilderBase(ServiceMetadata serviceMetadata)

Creates a new instance with no explicit settings. This takes the value of UseJwtAccessWithScopes from serviceMetadata.

Parameter
Name	Description
serviceMetadata	ServiceMetadata The metadata for the service that the client will be used with. Must not be null.

Properties

ApiKey

protected string ApiKey { get; set; }

An API key to use as an alternative to a full credential.

Property Value
Type	Description
string

Remarks

This is protected as not all APIs support API keys. APIs which support API keys should declare a new public property (also called ApiKey) in the concrete client builder class, and ensure they call GetEffectiveSettings<T>(T) to potentially specify the API key header via CallSettings.

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 and if UseJwtAccessWithScopes flag matches the flag in ChannelPool. Derived classes should override this property if there are other reasons why the channel pool should not be used.

Property Value
Type	Description
bool

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

Credential

public ICredential Credential { get; set; }

The credentials to use in "raw" form, for conversion into channel credentials. No other settings (e.g. QuotaProject or Scopes) are applied to these credentials.

Property Value
Type	Description
ICredential

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

DefaultOptions

protected static GrpcChannelOptions DefaultOptions { get; }

The default gRPC options.

Property Value
Type	Description
GrpcChannelOptions

EffectiveEndpoint

protected virtual string EffectiveEndpoint { get; }

Returns the service endpoint taking into account Endpoint and UniverseDomain. Override this property in a concrete builder type if an endpoint may be customized further.

Property Value
Type	Description
string

EffectiveGrpcAdapter

protected GrpcAdapter EffectiveGrpcAdapter { get; }

Returns the effective GrpcAdapter for this builder, using the GrpcAdapter property if that is set, or the appropriate fallback adapter for ServiceMetadata otherwise.

Property Value
Type	Description
GrpcAdapter

EffectiveUniverseDomain

protected string EffectiveUniverseDomain { get; }

Effective, and known, universe domain to connect to. Will be null if UniverseDomain is not set and there's nothing to gain from defaulting to DefaultUniverseDomain. For instance, if CallInvoker has been set, which is self contained, we really don't know the universe we are in, and we really don't care.

Property Value
Type	Description
string

Remarks

This will be:

• The value of UniverseDomain if set.
• null if CallInvoker is set.
• null if both Endpoint and one of the non GoogleCredential options is used.
• DefaultUniverseDomain otherwise.

Note that we don't validate here that the builder properties are set in a valid combination. EffectiveUniverseDomain is to be called from CreateCallInvoker() and CreateCallInvokerAsync(CancellationToken) after Validate() has been called.

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

Remarks

If Endpoint is set, its value will take preference over that built using UniverseDomain.

GoogleCredential

public GoogleCredential GoogleCredential { get; set; }

The credentials to use as a GoogleCredential, or null if credentials are being provided in a different way. Note that unlike ChannelCredentials and TokenAccessMethod, settings for Scopes, QuotaProject and self-signed JWTs will be applied to this credential (creating a new one), in the same way as for application default credentials and credentials specified using CredentialsPath or JsonCredentials.

Property Value
Type	Description
GoogleCredential

GrpcAdapter

public GrpcAdapter GrpcAdapter { get; set; }

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

Property Value
Type	Description
GrpcAdapter

GrpcChannelOptions

public GrpcChannelOptions GrpcChannelOptions { get; set; }

Any custom channel options to merge with the default options. If an option specified both here and in the default options, the custom option will take priority. This property may be null (the default) in which case the default options are used.

Property Value
Type	Description
GrpcChannelOptions

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

LastCreatedChannel

public ChannelBase LastCreatedChannel { get; protected set; }

Returns the channel created last time any of the Build()-related methods were called, or

null

if the last-created client did not require channel creation. If a channel is obtained from a channel pool, this does not count as channel creation. This property is useful when multiple clients are created and the calling code wishes to clean up resources associated with the channel.

Property Value
Type	Description
ChannelBase

Logger

public ILogger Logger { get; set; }

The logger to include in the client, if any.

Property Value
Type	Description
ILogger

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
IReadOnlyListstring

ServiceMetadata

protected ServiceMetadata ServiceMetadata { get; }

The metadata associated with the service that this client will make requests to.

Property Value
Type	Description
ServiceMetadata

TokenAccessMethod

[Obsolete("The Credential property is preferred for simplicity. This property may be removed in a future major version.")]
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
FuncstringCancellationTokenTaskstring

UniverseDomain

public string UniverseDomain { get; set; }

The universe domain to connect to, or null to use the default universe domain DefaultUniverseDomain.

Property Value
Type	Description
string

Remarks

UniverseDomain is used to build the endpoint to connect to, unless Endpoint is set, in which case Endpoint will be used without further modification.

If default credentials or one of GoogleCredential, CredentialsPath or JsonCredentials is used, GetUniverseDomain() should be:

• The same as UniverseDomain if UniverseDomain has been set.
• DefaultUniverseDomain otherwise.

UseJwtAccessWithScopes

public bool UseJwtAccessWithScopes { get; set; }

Returns whether or not self-signed JWTs will be used over OAuth tokens when OAuth scopes are explicitly set.

Property Value
Type	Description
bool

Remarks

In the base implementation, this defaults to true. Subclasses may add code in their own constructors to make the default effectively false, however.

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

Build(IServiceProvider)

public TClient Build(IServiceProvider provider)

Populates properties supplied via dependency injection, then builds a client.

Parameter
Name	Description
provider	IServiceProvider The service provider to request dependencies from. Must not be null.

Returns
Type	Description
TClient	An API client configured from this builder.

BuildAsync(IServiceProvider, CancellationToken)

public Task<TClient> BuildAsync(IServiceProvider provider, CancellationToken cancellationToken = default)

Populates properties supplied via dependency injection, then builds a client asynchronously.

Parameters
Name	Description
provider	IServiceProvider The service provider to request dependencies from. Must not be null.
cancellationToken	CancellationToken A token to cancel the operation.

Returns
Type	Description
Task	An API client configured from this builder.

BuildAsync(CancellationToken)

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

Builds the resulting client asynchronously.

Parameter
Name	Description
cancellationToken	CancellationToken

Returns
Type	Description
Task

Configure(IServiceProvider)

protected virtual void Configure(IServiceProvider provider)

Populates properties based on those set via dependency injection.

Parameter
Name	Description
provider	IServiceProvider The service provider to request dependencies from.

Remarks

If gRPC adapters are configured in provider, the first one that supports the ServiceMetadata will be used.

Credentials are only requested from dependency injection if they are not already set via any of ChannelCredentials, CredentialsPath, JsonCredentials, Credential, GoogleCredential or TokenAccessMethod.

If credentials are requested, they are tried in the following order:

• ChannelCredentials
• ICredential
• GoogleCredential

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 The builder to copy from.

Type Parameter
Name	Description
TOther	The other client type

CopySettingsForEmulator(ClientBuilderBase<TClient>)

protected void CopySettingsForEmulator(ClientBuilderBase<TClient> source)

Copies common settings from the specified builder, expecting that any settings around credentials and endpoints will be set by the caller, along with any client-specific settings. Emulator detection is not copied, to avoid infinite recursion when building.

Parameter
Name	Description
source	ClientBuilderBase

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
TaskCallInvoker

CreateChannel(string, ChannelCredentials)

protected virtual ChannelBase CreateChannel(string endpoint, ChannelCredentials credentials)

Returns a ChannelBase as created by EffectiveGrpcAdapter for the specified endpoint and credentials, using the gRPC channel options from GetChannelOptions().

Parameters
Name	Description
endpoint	string The endpoint of the channel.
credentials	ChannelCredentials The channel credentials.

Returns
Type	Description
ChannelBase	The channel created by the gRPC adapter.

Remarks

This is only useful in very specific situations where a known channel is required; CreateCallInvoker() and its async equivalent are more usually useful. This implementation sets the LastCreatedChannel property, and so should any overriding implementations.

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
TaskChannelCredentials

GetChannelOptions()

protected virtual GrpcChannelOptions GetChannelOptions()

Returns the options to use when creating a channel, taking GrpcChannelOptions into account.

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

GetEffectiveSettings<T>(T)

protected T GetEffectiveSettings<T>(T settings) where T : ServiceSettingsBase, new()

Returns the effective settings for this builder, taking into account API keys and any other properties which may require additional settings (typically via CallSettings).

Parameter
Name	Description
settings	T A clone of the existing settings specified in the concrete builder type. May be null.

Returns
Type	Description
T	The appropriate effective settings for this builder, or null if no settings have been provided and no other properties require additional settings. Note that clone operations are provided on a per-concrete-type basis, so this method must accept already-cloned settings.

Type Parameter
Name	Description
T	The concrete settings type, derived from ServiceSettingsBase, with a parameterless constructor that can be used to construct a new default instance.

Remarks

This method only needs to be called if the concrete builder type knows that the settings may need to be modified (e.g. if the API supports API keys). It should typically be called as GetEffectiveSettings(Settings?.Clone()).

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	IEnumerablestring Required emulator environment variables.
allEmulatorEnvironmentVariables	IEnumerablestring All emulator environment variables.
environmentVariableProvider	Funcstringstring The provider used to retrieve environment variables. This is used to faciliate testing, and defaults to using GetEnvironmentVariable(string).

Returns
Type	Description
Dictionarystringstring	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, params 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, params 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.