The Google Cloud Libraries for .NET area mixture of handwritten and autogeneratedlibraries connecting to Google Cloud services. The handwritten libraries (suchasGoogle.Cloud.Firestore andGoogle.Cloud.Spanner.Data)are mostly higher level abstractions over the underlying API. See the documentationfor those individual libraries for details; the documentation here is primarilyaimed at the autogenerated libraries.

If you haven't already found the library for the API you're interested in, please consultthe list of .NET libraries which shows both the NuGet packagename and the link to the library-specific documentation. In particular, each library has:

• A "getting started" page which lists the client types within that library
• Version history for the library
• API reference documentation

This page demonstrates using theGoogle.Cloud.Translate.V3API as a simple example; the steps required for other APIs are very similar.

Prerequisites

All Google Cloud APIs require a Google Cloud project. If you haven't set one up already,pleasecreate one.You'll also need toenable your chosen API if it hasn'talready been used within that Google Cloud project.

There are no specific tools required to develop using the Google Cloud Libraries for .NET. Alldevelopment environments should work, but you should check that you're targeting asupported platform.

We recommend installing thegcloud CLI.

Install the library

All Google Cloud Libraries for .NET are available fromnuget.org and can be installedusing any NuGet package manager. If the version you wish to is install a pre-release version,please ensure you enable pre-release packages (for example, in the Visual Studio NuGet user interface,check the "Include prerelease" box).

The libraries can be installed in any regular project type - for example, console applications,GUI applications such as WinForms and WPF, ASP.NET Core applications, and class libraries.

For the translation example, we'll create a console application using thedotnet toolingand install the package.

Note that for simplicity, the sample code below uses synchronous calls - but all methods have asynchronous equivalents,including client construction. Within naturally asynchronous environments such as web applications,we recommend the use of the asynchronous methods.

mkdir TranslationExamplecd TranslationExampledotnet new consoledotnet add package Google.Cloud.Translate.V3

Dependencies
If you install the library in an interactive environment such as Visual Studio, you may noticea lot of transitive dependencies being installed. This is entirely expected, but you may not recognizesome of those dependencies. The list below is not comprehensive, but highlights some of the packagesyou'll see being installed.

• Google.Protobuf: the library supporting theProtocol Buffers seralization format
• Google.Api.Gax, Google.Api.Gax.Grpc: support libraries specifically tailored for the Google Cloud client libraries
• Google.Apis.Auth, Google.Apis, Google.Apis.Core: authentication support for Google Cloud credentials
• Grpc.Auth, Grpc.Core.Api, Grpc.Net.Client, Grpc.Net.Common: support for thegRPC RPC protocol
• Google.LongRunning: support forlong-running operations

Create a client

The first step in making any API calls is to create a client. Some libraries have multiple clientsfor operations involving different resources; others have a single client. In the Translation APIwe're using, there's justTranslationServiceClient.

Clients can be configured in a number of ways, but in many cases the defaults are fine. The mostcommon reason to use explicit configuration is to use specific credentials forauthentication. For this example, we'll just useApplication Default Credentials (ADC).To set up ADC in your local environment, follow the instructions inLocal development environment.When you create a client, it automatically detects and uses these credentials.

Each client class has staticCreate andCreateAsync methods to create clients using all the default settings.So in this case we can just use:

using Google.Cloud.Translate.V3;var client = TranslationServiceClient.Create();

In applications that use dependency injection via Microsoft.Extensions.DependencyInjection, we recommendusing dependency injection for client construction. See theclient lifecycle documentation on dependency injectionfor details.

Make requests

The Google Cloud Libraries useProtocol Buffersto represent requests and responses, with some additional types to make the APIs moreconvenient to work with.

Most APIs are expressed in terms of a single request returning a single response, althoughthere are also some streaming APIs involving multiple requests and/or multiple responses.For our Translation API example, we'll create a simple request for theTranslateText API.

using Google.Api.Gax.ResourceNames;...string projectId = "your-project-id-here";string locationId = "global";var request = new TranslateTextRequest{    Contents = { "It is raining.", "It is sunny." },    TargetLanguageCode = "fr-FR",    ParentAsLocationName = new LocationName(projectId, locationId)};var response = client.TranslateText(request);

This example demonstrates a few features:

• Protocol Buffer messages always have parameterless constructors and support object initializers
• TheContents property is a read-only property of typeRepeatedField<string> - the code abovedoesn't assign a new value to the property; instead it uses a collection initializer to populatethe repeated field
• The Translate library has added an extraParentAsLocationName property to the message.There's aParent property which is just of typestring, but usingParentAsLocationNameallows resource names to be handled in a type-safe manner, and you don't need to concern yourselfwith the underlying resource name format. For more details, see theresource names documentation.

The Google Cloud Libraries always expose methods accepting an API request directly,but in some cases additional overloads are provided for convenience. In this particular case, we could have used:

var response = client.TranslateText(    new LocationName(projectId, locationId),    "fr-FR",    new[] { "It is raining.", "It is sunny." });

The convenience methods don't always cover all possible aspects of the request.For example,TranslateTextRequest has aMimeType property which can easily be set whenusing the code creating a full request, but can't be specified in the convenience method.

The response is also a Protocol Buffers message. CallingToString() on any message will return the JSONrepresentation of the message, which can be useful to see the structure of a response when using a specificAPI for the first time. In this case we'll just look at theTranslations property though:

Console.WriteLine($"Translations returned: {response.Translations.Count}");Console.WriteLine();foreach (var translation in response.Translations){    Console.WriteLine($"Detected language: {translation.DetectedLanguageCode}");    Console.WriteLine($"Translated text: {translation.TranslatedText}");    Console.WriteLine();}

This produces output of:

Translations returned: 2Detected language: enTranslated text: Il pleut.Detected language: enTranslated text: Il fait beau.

The complete code is:

using Google.Api.Gax.ResourceNames;using Google.Cloud.Translate.V3;var client = TranslationServiceClient.Create();string projectId = "your-project-id-here";string locationId = "global";var request = new TranslateTextRequest{    Contents = { "It is raining.", "It is sunny." },    TargetLanguageCode = "fr-FR",    ParentAsLocationName = new LocationName(projectId, locationId)};var response = client.TranslateText(request);Console.WriteLine($"Translations returned: {response.Translations.Count}");Console.WriteLine();foreach (var translation in response.Translations){    Console.WriteLine($"Detected language: {translation.DetectedLanguageCode}");    Console.WriteLine($"Translated text: {translation.TranslatedText}");    Console.WriteLine();}

This is just a simple example, which hasn't touched onpage streamingorspecifying call settings for example.

Getting help

If you run into problems with the Google Cloud Libraries for .NET, help is available.Please read theSupport guide for more information about the most effective wayto ask for help.