Google.Cloud.PubSub.V1

Google.Cloud.PubSub.V1 is a.NET client library for the Cloud Pub/Sub API.

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

Class renaming in v1.0.0-beta16

The following classes have been renamed when moving from version 1.0.0-beta15 to 1.0.0-beta16:

Installation

Install the Google.Cloud.PubSub.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

PublisherServiceApiClient and SubscriberServiceApiClient provide a general-purpose abstraction over raw the RPC API, providing features such as page streaming to make client code cleaner and simpler.

PublisherClient and SubscriberClient provide simpler APIs for message publishing and subscribing. These classes offer considerably higher performance and simplicity, especially when working with higher message throughput.

Note that both PublisherClient and SubscriberClient expect to execute in an environment with continuous processing and continuous network access to the Pub/Sub API. In environments such as Cloud Run or Cloud Functions, where servers do not use any CPU between requests, the PublisherServiceApiClient and SubscriberServiceApiClient classes should be used instead.

Sample code

Using PublisherClient and SubscriberClient for message publishing and subscribing:

// First create a topic.
PublisherServiceApiClient publisherService = await PublisherServiceApiClient.CreateAsync();
TopicName topicName = new TopicName(projectId, topicId);
publisherService.CreateTopic(topicName);

// Subscribe to the topic.
SubscriberServiceApiClient subscriberService = await SubscriberServiceApiClient.CreateAsync();
SubscriptionName subscriptionName = new SubscriptionName(projectId, subscriptionId);
subscriberService.CreateSubscription(subscriptionName, topicName, pushConfig: null, ackDeadlineSeconds: 60);

// Publish a message to the topic using PublisherClient.
PublisherClient publisher = await PublisherClient.CreateAsync(topicName);
// PublishAsync() has various overloads. Here we're using the string overload.
string messageId = await publisher.PublishAsync("Hello, Pubsub");
// PublisherClient instance should be shutdown after use.
// The TimeSpan specifies for how long to attempt to publish locally queued messages.
await publisher.ShutdownAsync(TimeSpan.FromSeconds(15));

// Pull messages from the subscription using SubscriberClient.
SubscriberClient subscriber = await SubscriberClient.CreateAsync(subscriptionName);
List<PubsubMessage> receivedMessages = new List<PubsubMessage>();
// Start the subscriber listening for messages.
await subscriber.StartAsync((msg, cancellationToken) =>
{
    receivedMessages.Add(msg);
    Console.WriteLine($"Received message {msg.MessageId} published at {msg.PublishTime.ToDateTime()}");
    Console.WriteLine($"Text: '{msg.Data.ToStringUtf8()}'");
    // Stop this subscriber after one message is received.
    // This is non-blocking, and the returned Task may be awaited.
    subscriber.StopAsync(TimeSpan.FromSeconds(15));
    // Return Reply.Ack to indicate this message has been handled.
    return Task.FromResult(SubscriberClient.Reply.Ack);
});

// Tidy up by deleting the subscription and the topic.
subscriberService.DeleteSubscription(subscriptionName);
publisherService.DeleteTopic(topicName);

Using PublisherServiceApiClient and SubscriberServiceApiClient only:

// First create a topic.
PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
TopicName topicName = new TopicName(projectId, topicId);
publisher.CreateTopic(topicName);

// Subscribe to the topic.
SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
SubscriptionName subscriptionName = new SubscriptionName(projectId, subscriptionId);
subscriber.CreateSubscription(subscriptionName, topicName, pushConfig: null, ackDeadlineSeconds: 60);

// Publish a message to the topic.
PubsubMessage message = new PubsubMessage
{
    // The data is any arbitrary ByteString. Here, we're using text.
    Data = ByteString.CopyFromUtf8("Hello, Pubsub"),
    // The attributes provide metadata in a string-to-string dictionary.
    Attributes =
    {
        { "description", "Simple text message" }
    }
};
publisher.Publish(topicName, new[] { message });

// Pull messages from the subscription. We're returning immediately, whether or not there
// are messages; in other cases you'll want to allow the call to wait until a message arrives.
PullResponse response = subscriber.Pull(subscriptionName, returnImmediately: true, maxMessages: 10);
foreach (ReceivedMessage received in response.ReceivedMessages)
{
    PubsubMessage msg = received.Message;
    Console.WriteLine($"Received message {msg.MessageId} published at {msg.PublishTime.ToDateTime()}");
    Console.WriteLine($"Text: '{msg.Data.ToStringUtf8()}'");
}

// Acknowledge that we've received the messages. If we don't do this within 60 seconds (as specified
// when we created the subscription) we'll receive the messages again when we next pull.
subscriber.Acknowledge(subscriptionName, response.ReceivedMessages.Select(m => m.AckId));

// Tidy up by deleting the subscription and the topic.
subscriber.DeleteSubscription(subscriptionName);
publisher.DeleteTopic(topicName);

Using the emulator

To connect to a Pub/Sub Emulator, set the EmulatorDetection property in the appropriate class depending on which client type you are constructing:

  • PublisherClient.ClientCreationSettings (for PublisherClient)
  • SubscriberClient.ClientCreationSettings (for SubscriberClient)
  • PublisherServiceApiClientBuilder (for PublisherServiceApiClient)
  • SubscriberServiceApiClientBuilder (for SubscriberServiceApiClient)

See the FAQ entry for more details.