Library types

There are many Google Cloud Libraries for .NET, which fall into a few different "types" which are designed in slightly different ways, based on how we expect customers to want to use them. Most of the time we hope you won't need to differentiate between the different types of library, but it can be useful when trying to diagnose an issue, for example.

Fully generated gRPC-based libraries

Most of our libraries have no hand-written code at all. They're completely generated by the "GAPIC" generator, based on API definitions expressed using Protocol Buffers.

These libraries default to using gRPC over HTTP/2.0 as the transport to make API calls, but some also permit using JSON over HTTP/1.1 for situations where you may be behind a proxy that doesn't support HTTP/2.0 for example. See the transport selection documentation for more information.

Some other purely-generated libraries such as Google.Cloud.Logging.Type or Google.Cloud.Bigtable.Common.V2 contain just protobuf types or resource name types used by multiple other libraries.

Hybrid generated+handwritten gRPC-based libraries

Some libraries build on the generated code as described above, but add some hand-written code. Sometimes these are just very small amounts of code to just make a few operations simpler, or to provide emulator support. In a few other cases (most notably Google.Cloud.PubSub.V1 and Google.Cloud.Bigtable.V2) the hand-written code forms the bulk of the library's public API surface that you're likely to use directly.

The hybrid libraries are:

  • Google.Cloud.AIPlatform.V1
  • Google.Cloud.Bigtable.Admin.V2
  • Google.Cloud.Bigtable.V2
  • Google.Cloud.Compute.V1 (which always uses JSON over HTTP/1.1)
  • Google.Cloud.Datastore.V1
  • Google.Cloud.DevTools.ContainerAnalysis.V1
  • Google.Cloud.Iam.V1
  • Google.Cloud.Language.V1
  • Google.Cloud.Spanner.Admin.Database.V1
  • Google.Cloud.Spanner.Admin.Instance.V1
  • Google.Cloud.Speech.V1
  • Google.Cloud.Speech.V1P1Beta1
  • Google.Cloud.PubSub.V1
  • Google.Cloud.Spanner.V1
  • Google.Cloud.Tasks.V2
  • Google.Cloud.Translation.V2
  • Google.Cloud.VideoIntelligence.V1
  • Google.Cloud.Vision.V1
  • Google.LongRunning
  • Grafeas.V1

Where we expect customers to use the hand-written code, the "getting started" page for each library will describe it (see the Pub/Sub documentation for an example).

In a few cases (most notably Google.Cloud.Spanner.V1) the hand-written code is primarily present to help other libraries to provide a more customized layer.

Handwritten libraries providing a layer over gRPC libraries

Some libraries provide entirely hand-written surfaces, taking a dependency on another fully/mostly generated library. In these cases, while the underlying API surface is still accessible, most users will never need to use types from the lower-level library.

Example of these are:

  • Google.Cloud.Spanner.Data: an ADO.NET layer over Google.Cloud.Spanner.V1 to allow developers to work with Cloud Spanner using familiar patterns.
  • Google.Cloud.Firestore: a complete wrapper around Google.Cloud.Firestore.V1, including a simple way of storing and querying user-defined classes within Cloud Firestore.
  • Google.Cloud.Diagnostics.Common: a library to allow easy integration of applications with Cloud Logging, Cloud Error Reporting and Cloud Trace
  • Google.Cloud.Diagnostics.AspNetCore3: built on top of Google.Cloud.Diagnostics.Common above, this provides middleware and a few other aspects specific to ASP.NET Core.

Other libraries exist to integrate Cloud Logging with other .NET frameworks:

  • Google.Cloud.Logging.Log4Net
  • Google.Cloud.Logging.NLog

Handwritten libraries providing a layer over HTTP/1.1 + REST libraries

There are three libraries of this type:

  • Google.Cloud.BigQuery.V2 (wraps Google.Apis.Bigquery.v2)
  • Google.Cloud.Storage.V1 (wraps Google.Apis.Storage.v1)
  • Google.Cloud.Translation.V2 (wraps Google.Apis.Translate.v2)

These libraries do not use gRPC at all. They provide a more convenient API surface over the corresponding legacy HTTP/1.1 + REST libraries described below, to make the APIs easier to use. They are still actively maintained, and currently there are no gRPC-based libraries providing the same functionality for BigQuery and Cloud Storage. (There are various gRPC-based libraries for other BigQuery APIs such as the migration or reservation APIs - but not the "core" BigQuery API.) The Google.Cloud.Translate.V3 library provides a gRPC-based API for the Translation AI product. (There are additional differences between Translation v2 and v3; see the product documentation for more details.)

Console logging

The Google.Cloud.Logging.Console library provides custom console log formatting for use with the Microsoft .NET Logging API, producing rich logs for Cloud Logging.

Legacy HTTP/1.1 + REST libraries

The API-specific libraries with source code in the google-api-dotnet-client repository are all generated from Discovery documents instead of API protobuf representations. API calls are made over HTTP/1.1 with JSON content.

These libraries are still supported and automatically updated as the API surfaces change, but the underlying code and generator is not being actively worked on, and only high-impact feature requests are considered.

Examples include:

  • Google.Apis.Analytics.v3
  • Google.Apis.CloudBuild.v1
  • Google.Apis.Calendar.v3
  • Google.Apis.YouTube.v3

(In general, packages starting "Google.Apis" followed by a product name and a version number fall into this category.)

More information about various aspects of these libraries can be found in the dedicated page.