Client configuration

Every client has a corresponding builder class (e.g. ExampleClientBuilder) with Build and BuildAsync methods.

The builder allows you to customize various aspects of the client, most notably credentials. For example, if you load JSON containing the relevant credentials to use, you might construct a client with:

var client = new ExampleClientBuilder
{
    JsonCredentials = json
}.Build();

Clients can also be configured via dependency injection, but that's just a (very) convenient approach to using the builder: everything can be configured via the builder. See the client lifecycle documentation for more details of the options around where to configure the client; this page focuses on what can be configured.

Note that the options below are the ones supported by gRPC-based APIs. The Google.Cloud.Storage.V1, Google.Cloud.BigQuery.V2 and Google.Cloud.Translation.V2 libraries support builders as well, but with fewer options.

Specifying credentials

The following properties are used for specifying and configuring which credentials a client uses to authenticate and authorize requests. When no properties are set, application default credentials are used.

CredentialsPath, JsonCredentials or GoogleCredential

These three (mutually-exclusive) properties represent different ways of providing a GoogleCredential. Specifying CredentialsPath or JsonCredentials is equivalent to specifying the result of GoogleCredential.FromFile or GoogleCredential.FromJson for the GoogleCredential property.

Scopes, UseJwtAccessWithScopes and QuotaProject

When application default credentials are used, or a GoogleCredential is specified explicitly, these three properties can provide extra information for the credentials. By default, the credential is scoped with the default scopes for the client being constructed (e.g. ExampleClient.DefaultScopes). In some cases you may wish to specify more fine-grained scopes instead using the Scopes property.

The UseJwtAccessWithScopes property controls whether service account credentials request an OAuth2 token, or whether they create a self-signed JWT using the secret within the credential, where feasible. By default this is true.

The QuotaProject controls which Google Cloud project is used to account for or bill the requests made by the client.

ChannelCredentials, Credential or TokenAccessMethod

These three properties (which are mutually-exclusive, along with any of the GoogleCredential properties) represent "raw" credentials which are used exactly as they are provided, without applying any additional options such as scopes or a quota project. These are the most low-level properties, and are rarely as useful as the ones above.

API Keys

Most Cloud APIs do not support API keys, instead requiring full credentials as described above. For this reason, most client libraries do not have direct support for API keys, but API keys can still be used for those APIs which support them.

Where we are aware that API keys are supported, the client builder exposes an ApiKey property which can be set, leaving all other credential-related properties unset. For example, you can create a client for the Language API using an API key like this:

// Create a LanguageServiceClient which uses the given API key
// instead of regular credentials.
LanguageServiceClient client = new LanguageServiceClientBuilder
{
    ApiKey = apiKey
}.Build();

If you're using a library which doesn't expose an ApiKey property in the builder, but you wish to set one anyway, you can specify the API key in the X-Goog-Api-Key header on every request. Additionally, the gRPC channel should be built using ChannelCredentials.SecureSsl. For example, to manually specify the API key in a Language client (instead of using the built-in support) you could write code like this:

// Create a LanguageServiceSettings that applies the X-Goog-Api-Key
// header on every request
LanguageServiceSettings settings = new LanguageServiceSettings
{
    CallSettings = CallSettings.FromHeader("X-Goog-Api-Key", apiKey)
};

// Create a LanguageServiceClient which uses the settings to apply
// the API key to every request. The ChannelCredentials are set to
// just SSL; we don't authenticate at the channel level when
// applying API keys.
LanguageServiceClient client = new LanguageServiceClientBuilder
{
    ChannelCredentials = ChannelCredentials.SecureSsl,
    Settings = settings
}.Build();

After building the client, it can be used like any other client.

gRPC configuration

GrpcAdapter

The GrpcAdapter property configures which gRPC implementation is used. It is almost always safe to leave this unspecified, using the default selection algorithm. See the transports documentation for more details.

GrpcChannelOptions

Not to be confused with Grpc.Net.Client.GrpcChannelOptions, the Google.Api.Gax.Grpc.GrpcChannelOptions class provides an implementation-agnostic way of configuring aspects such as the maximum size of requests that can be sent. The default options are appropriate for most scenarios. Any options provided here are layered over the default options rather than replacing them entirely.

CallInvoker

This is the lowest level of configuration: when a CallInvoker is specified, none of the above properties are used at all. This is rarely used outside low-level testing.

Miscellaneous configuration

Endpoint

This is used to configure which server to send requests to. For instance, it may be used for APIs that support regional endpoints or for Private Service Connect. For example, in the Google.Cloud.AIPlatform.V1 API you might configure a client like this:

string region = "us-central1";
var client = new DatasetServiceClientBuilder
{
    Endpoint = $"{region}-aiplatform.googleapis.com"
}.Build();

Logger

When specified, this allows the client to log trace messages at the start and end of API calls. This does not provide transport-level gRPC logging. See the troubleshooting documentation for more details of configuring logging.

UserAgent

The user agent sent in the headers for each request can be customized with this property.

EmulatorDetection (for APIs that support it)

Some APIs (such as Pub/Sub and Spanner) support emulators. The EmulatorDetection property is used to specify whether to connect to an emulator if the appropriate environment variables are set. See the emulator support documentation for more details.

API-specific settings

Each client class has a corresponding Settings class (so ExampleClient would have an ExampleSettings class). This is used to provide API-wide and method-specific call settings to be applied by default on every call made via the client, for example to configure retry timings. If this property is not set, the default settings configured for the client are applied.