Google.Cloud.Compute.V1

Google.Cloud.Compute.V1 is a.NET client library for the Compute Engine API.

Note: This documentation is for version 2.3.0 of the library. Some samples may not work with other versions.

Installation

Install the Google.Cloud.Compute.V1 package from NuGet. Add it to your project in the normal way (for example by right-clicking on the project in Visual Studio and choosing "Manage NuGet Packages...").

Authentication

When running on Google Cloud Platform, no action needs to be taken to authenticate.

Otherwise, the simplest way of authenticating your API calls is to download a service account JSON file then set the GOOGLE_APPLICATION_CREDENTIALS environment variable to refer to it. The credentials will automatically be used to authenticate. See the Getting Started With Authentication guide for more details.

Getting started

All operations are performed through the following client classes:

Create a client instance by calling the static Create or CreateAsync methods. Alternatively, use the builder class associated with each client class (e.g. AcceleratorTypesClientBuilder for AcceleratorTypesClient) as an easy way of specifying custom credentials, settings, or a custom endpoint. Clients are thread-safe, and we recommend using a single instance across your entire application unless you have a particular need to configure multiple client objects separately.

Using wire values for enums

Many fields in the Compute API are effectively enums, representing one of a fixed set of values.

These are currently represented as string properties in the API surface, for compatibility reasons. C# enums containing the known values are generated, but not used directly within the API surface.

As an example, the Address resource has a NetworkTier property, of type string. The set of valid values is represented by the Address.Types.NetworkTier enum - but these are generated with C#-idiomatic names, not the strings that need to be used for the Address.NetworkTier property.

Two approaches are provided to allow client code to refer to specific values without hard-coding string literals in an error-prone way. First, the ComputeEnumConstants class provides all known enum constants via nested classes. For example, the NetworkTier enum used by Address is represented in the ComputeEnumConstants.Address.NetworkTier class:

Address addressResource = new Address
{
    Name = addressName,
    Region = region,
    NetworkTier = ComputeEnumConstants.Address.NetworkTier.Premium
};

This is simple for cases where client code needs to refer to a single value known at compile-time. In situations where more flexibility is required, the wire value corresponding to each enum value can be obtained using ComputeEnumHelpers.Format:

// This could be passed into a method as a parameter, for example.
Address.Types.NetworkTier tier = Address.Types.NetworkTier.Premium;
Address addressResource = new Address
{
    Name = addressName,
    Region = region,
    NetworkTier = ComputeEnumHelpers.Format(tier)
};

The reverse operation (parsing from a wire value to an enum value) can be achieved using ComputeEnumHelpers.TryParse and ComputeEnumHelpers.Parse:

if (ComputeEnumHelpers.TryParse(addressResource.NetworkTier, out Address.Types.NetworkTier tier))
{
    // The wire value was recognized, and tier contains the enum value.
    Console.WriteLine($"Network tier: {tier}");
}

(Following .NET conventions, the Parse method returns the parsed enum value directly instead of using an out parameter, but throws an exception if the value is not recognized.)