Google Cloud Pub/Sub with C#: .NET 10 Tutorial and Gotchas
Last updated: October 19, 2026 · Tested with Google.Cloud.PubSub.V1 3.39.0 on .NET 10 (SDK 10.0.401, runtime 10.0.12) against the Pub/Sub emulator 0.8.37, Windows 11
Short answer: Install Google.Cloud.PubSub.V1, create a topic and a subscription, publish with PublisherClient and consume with SubscriberClient.StartAsync, returning Reply.Ack or Reply.Nack from your handler. I rebuilt every example in this tutorial on .NET 10 and ran it against the local Pub/Sub emulator. Five things I found that most tutorials (including the first version of this one) get wrong:
- The .NET client ignores
PUBSUB_EMULATOR_HOSTby default. Even with the variable set,PublisherClient.CreateAsyncfailed with “Your default credentials were not found”. You must opt in withEmulatorDetection. - If the process exits without
ShutdownAsync, queued messages are lost: 0 of 50 arrived. WithShutdownAsyncorawait using, 50 of 50 arrived. SubscriberClient.StopAsync(TimeSpan)is obsolete in 3.39.0, and a shutdown timeout under 30 seconds silently switches to “nack immediately”. In my worker, 30 of 100 messages went back to the subscription.- A dead-letter policy needs
MaxDeliveryAttemptsof at least 5. - An ordering key fails unless you enable ordering on the publisher and the subscription.
What Pub/Sub Is, in One Paragraph
A publisher sends a message to a topic. Pub/Sub delivers a copy to every subscription attached to that topic. A subscriber receives messages from its subscription and acknowledges each one; until it does, Pub/Sub redelivers the message. That gives you at-least-once delivery, and it is why every handler you write must cope with duplicates. Compared with Azure Service Bus or RabbitMQ, there are no brokers or queues to size; compared with Kafka, there are no partitions or consumer groups to plan. The choice usually follows the cloud you’re already on.
Setup: Package and Local Emulator
dotnet new console -n PubSubDemo
dotnet add PubSubDemo package Google.Cloud.PubSub.V1 # 3.39.0, released October 9, 2026
For production you authenticate with Application Default Credentials (gcloud auth application-default login on a dev machine, the attached service account on Cloud Run or GKE). For development and CI, use the emulator: no account, no cost, and every developer gets their own state. The usual way to start it is:
gcloud beta emulators pubsub start --project=demo-project
# then, in the shell that runs your app:
set PUBSUB_EMULATOR_HOST=localhost:8085 (Windows cmd)
export PUBSUB_EMULATOR_HOST=localhost:8085 (bash)
I didn’t have gcloud or Docker on this machine, so I ran the emulator component directly: it is one jar that needs Java 21 (java -jar cloud-pubsub-emulator-0.8.37-all.jar --host=localhost --port=8085, which printed Server started, listening on 8085).
The Emulator Trap: EmulatorDetection
This is the line most tutorials show, run with PUBSUB_EMULATOR_HOST=localhost:8085 set:
var publisher = await PublisherClient.CreateAsync(TopicName.FromProjectTopic("demo-project", "orders"));
System.InvalidOperationException: Your default credentials were not found. To set up Application Default Credentials, see https://cloud.google.com/docs/authentication/external/set-up-adc.
The .NET client never looked at the emulator. The package’s XML docs say it plainly: EmulatorDetection “defaults to None, meaning that environment variables are ignored”. Use the builders and opt in:
using Google.Api.Gax;
using Google.Cloud.PubSub.V1;
PublisherServiceApiClient AdminPub() => new PublisherServiceApiClientBuilder
{ EmulatorDetection = EmulatorDetection.EmulatorOrProduction }.Build();
SubscriberServiceApiClient AdminSub() => new SubscriberServiceApiClientBuilder
{ EmulatorDetection = EmulatorDetection.EmulatorOrProduction }.Build();
async Task<PublisherClient> Publisher(TopicName t, PublisherClient.Settings? s = null) =>
await new PublisherClientBuilder
{
TopicName = t,
Settings = s,
EmulatorDetection = EmulatorDetection.EmulatorOrProduction
}.BuildAsync();
async Task<SubscriberClient> Subscriber(SubscriptionName n, SubscriberClient.Settings? s = null) =>
await new SubscriberClientBuilder
{
SubscriptionName = n,
Settings = s,
EmulatorDetection = EmulatorDetection.EmulatorOrProduction
}.BuildAsync();
EmulatorOrProduction uses the emulator when the variable is set and the real service when it isn’t, so the same code runs in both places. Never ship with EmulatorOnly.
Create a Topic and a Subscription
const string projectId = "demo-project";
var topicName = TopicName.FromProjectTopic(projectId, "orders");
var subName = SubscriptionName.FromProjectSubscription(projectId, "orders-email");
var topic = await AdminPub().CreateTopicAsync(topicName);
Console.WriteLine($"Created topic: {topic.Name}");
await AdminSub().CreateSubscriptionAsync(new Subscription
{
SubscriptionName = subName,
TopicAsTopicName = topicName,
AckDeadlineSeconds = 60
});
try { await AdminPub().CreateTopicAsync(topicName); }
catch (RpcException ex) when (ex.StatusCode == StatusCode.AlreadyExists)
{
Console.WriteLine($"Second create: {ex.StatusCode} | {ex.Status.Detail}");
}
Created topic: projects/demo-project/topics/orders
Second create: AlreadyExists | Topic already exists
AckDeadlineSeconds is how long Pub/Sub waits for an ack before redelivering. The high-level SubscriberClient extends the deadline while your handler runs, so 60 seconds is a reasonable base. In production you usually create topics and subscriptions with Terraform or gcloud, not at app startup.
Publish Messages with PublisherClient
public record OrderPlaced(string OrderId, string CustomerEmail, decimal Total);
var publisher = await Publisher(topicName);
string[] ids = await Task.WhenAll(Enumerable.Range(1, 100).Select(i => publisher.PublishAsync(new PubsubMessage
{
Data = ByteString.CopyFromUtf8(JsonSerializer.Serialize(new OrderPlaced($"o-{i}", "a@b.c", i))),
Attributes = { { "eventType", "OrderPlaced" }, { "schemaVersion", "1" } }
})));
await publisher.ShutdownAsync(TimeSpan.FromSeconds(15));
PublisherClient batches messages in memory and sends them in the background; PublishAsync completes with the server’s message ID once its batch is sent. Create one client per topic and reuse it. Put routing metadata in attributes, not in the JSON: subscribers can then filter on them server-side (see the filter section) without deserializing anything.
ShutdownAsync is not optional: what I measured
I started 50 PublishAsync calls without awaiting them (fire-and-forget, as in a request handler that doesn’t wait) and let the process end. Then I counted what reached the subscription from a separate process:
| How the process ended | Messages that arrived |
|---|---|
| Process exits, no shutdown call | 0 of 50 |
await publisher.ShutdownAsync(TimeSpan.FromSeconds(15)) before exit | 50 of 50 |
await using var publisher = ... | 50 of 50 |
No exception, no log line: the messages simply never left the process. PublisherClient implements IAsyncDisposable, and DisposeAsync flushes with a default DisposeTimeout of 5 seconds, so await using is the shortest correct form in a console app. In a hosted app, registering the client in DI (below) gets it disposed on shutdown for you.
Consume Messages with SubscriberClient
var subscriber = await Subscriber(subName);
Task run = subscriber.StartAsync(async (PubsubMessage message, CancellationToken ct) =>
{
try
{
var order = JsonSerializer.Deserialize<OrderPlaced>(message.Data.ToStringUtf8());
if (order is null) return SubscriberClient.Reply.Ack; // empty payload: retrying won't help
await SendConfirmationEmailAsync(order, ct);
return SubscriberClient.Reply.Ack;
}
catch (JsonException)
{
return SubscriberClient.Reply.Ack; // malformed: will never succeed (or Nack + dead-letter topic)
}
catch (Exception)
{
return SubscriberClient.Reply.Nack; // transient: redeliver
}
});
// later, on shutdown:
await subscriber.StopAsync(new SubscriberClient.ShutdownOptions
{
Mode = SubscriberClient.ShutdownMode.WaitForProcessing,
Timeout = TimeSpan.FromSeconds(45)
}, CancellationToken.None);
await run;
With 100 messages, where the handler Nacked order o-7 once, I got 101 handler calls (100 + 1 redelivery), and nothing left in the subscription after StopAsync. A Nack is redelivered almost at once, so a failing dependency gets hammered unless you configure a retry policy with backoff on the subscription.
StopAsync(TimeSpan) is obsolete. The older overload that most samples use builds with a warning on 3.39.0:
warning CS0618: 'SubscriberClient.StopAsync(TimeSpan)' is obsolete: 'Use StopAsync(ShutdownOptions, CancellationToken) instead.'
The replacement takes a ShutdownMode: WaitForProcessing stops pulling and finishes the messages already received; NackImmediately stops and releases unhandled messages for redelivery.
Hosting in a Worker Service or ASP.NET Core
The package includes DI extensions that register the clients as singletons:
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddPublisherClient(b =>
{
b.TopicName = TopicName.FromProjectTopic(projectId, "orders");
b.EmulatorDetection = EmulatorDetection.EmulatorOrProduction;
});
builder.Services.AddSubscriberClient(b =>
{
b.SubscriptionName = SubscriptionName.FromProjectSubscription(projectId, "orders-email");
b.EmulatorDetection = EmulatorDetection.EmulatorOrProduction;
b.Settings = new SubscriberClient.Settings
{
FlowControlSettings = new FlowControlSettings(maxOutstandingElementCount: 10, maxOutstandingByteCount: null)
};
});
builder.Services.AddHostedService<OrderEmailWorker>();
await builder.Build().RunAsync();
public sealed class OrderEmailWorker(SubscriberClient subscriber, ILogger<OrderEmailWorker> logger) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
// Stop pulling when the host shuts down; let in-flight handlers finish and ack.
await using var _ = stoppingToken.Register(() =>
subscriber.StopAsync(new SubscriberClient.ShutdownOptions
{
Mode = SubscriberClient.ShutdownMode.WaitForProcessing,
Timeout = TimeSpan.FromSeconds(45)
}, CancellationToken.None));
await subscriber.StartAsync(async (message, ct) =>
{
var order = JsonSerializer.Deserialize<OrderPlaced>(message.Data.ToStringUtf8());
if (order is null) return SubscriberClient.Reply.Ack;
await Task.Delay(200, ct); // pretend to send an email
return SubscriberClient.Reply.Ack;
});
logger.LogInformation("Subscriber stopped.");
}
}
To test shutdown, a second hosted service published 100 orders and called StopApplication() 1.5 seconds later, while the worker was still processing. With the shutdown timeout set to 20 seconds, the library logged this and changed mode:
warn: Google.Cloud.PubSub.V1.SubscriberClient[0]
Shutdown timeout is 00:00:20. Not enough time to fulfill request for shutdown mode WaitForProcessing and NackImmediately grace period before shutdown of 00:00:30 Going to NackImmediately shutdown mode immediately.
info: OrdersWorker.OrderEmailWorker[0]
Subscriber stopped. Handled 70, max concurrent handlers 10
The other 30 messages stayed in the subscription, so nothing was lost, but a deploy did not drain the worker as intended. With 45 seconds: Handled 100 and 0 messages left. Keep the timeout above 30 seconds if you want WaitForProcessing, and keep the host’s own HostOptions.ShutdownTimeout (30 seconds by default) at least as long, or the host stops waiting first. max concurrent handlers 10 also confirms that flow control works: cap it near your database connection pool size.
Idempotent Handlers (Duplicates Will Happen)
At-least-once delivery means the same message can arrive twice: after a crash, a missed ack deadline or a Nack. Key the work on a business ID with a unique constraint and skip what you’ve already done. Tested with SQLite (Microsoft.Data.Sqlite 10.0.13) and the same order published twice:
using var cmd = db.CreateCommand();
cmd.CommandText = "INSERT INTO processed_events (order_id) VALUES ($id) ON CONFLICT DO NOTHING";
cmd.Parameters.AddWithValue("$id", order.OrderId);
if (await cmd.ExecuteNonQueryAsync(ct) == 0)
return SubscriberClient.Reply.Ack; // already processed: skip
// send the e-mail here
return SubscriberClient.Reply.Ack;
processed o-1 | processed o-2 | duplicate o-1 skipped
PostgreSQL accepts the same ON CONFLICT DO NOTHING; SQL Server needs a MERGE or a caught duplicate-key error. Pub/Sub’s exactly-once delivery setting reduces redeliveries, but your handler can still fail after the side effect and before the ack, so keep the check.
Ordering Keys
var plain = await Publisher(topicName);
await plain.PublishAsync(new PubsubMessage { OrderingKey = "customer-1", Data = ByteString.CopyFromUtf8("x") });
System.InvalidOperationException: Message ordering must be enabled in settings before using OrderingKey
Enable it on the publisher and create the subscription with EnableMessageOrdering = true:
var ordered = await Publisher(topicName, new PublisherClient.Settings { EnableMessageOrdering = true });
await Task.WhenAll(Enumerable.Range(1, 20).Select(i => ordered.PublishAsync(new PubsubMessage
{ OrderingKey = "customer-1", Data = ByteString.CopyFromUtf8($"{i}") })));
Order received: 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
Ordering is per key, and it costs throughput per key. Use it only where the business needs it (events for one customer or one account), and don’t assume any order without it.
Subscription Filters
new Subscription
{
SubscriptionName = subName,
TopicAsTopicName = topicName,
Filter = "attributes.eventType = \"OrderPlaced\""
}
I published three messages: a with eventType=OrderPlaced, b with OrderShipped and c with no attributes. The subscription received only a. Messages a filter drops are acknowledged automatically, so they don’t pile up in the backlog. You can’t change a subscription’s filter after creating it; you create a new subscription.
Dead-Letter Topics
DeadLetterPolicy = new DeadLetterPolicy
{
DeadLetterTopic = deadLetterTopic.ToString(),
MaxDeliveryAttempts = 2
}
OutOfRange | The value for max_delivery_attempts is too small. You passed 2 in the request, but the minimum value is 5.
Allowed values are 5 to 100. With MaxDeliveryAttempts = 5 and a handler that always Nacks, the handler saw 5 deliveries, and message.GetDeliveryAttempt() returned 1, 2, 3, 4, 5. After that, the message was in the dead-letter topic’s subscription. In production, the Pub/Sub service account also needs permission to publish to the dead-letter topic and to subscribe to the source subscription; the emulator doesn’t check IAM, so test that part in a real project (Google’s dead-letter guide lists the roles).
Errors I Reproduced
| Message | Cause | Fix |
|---|---|---|
InvalidOperationException: Your default credentials were not found. | No ADC, or emulator variable ignored | gcloud auth application-default login, or EmulatorDetection.EmulatorOrProduction |
RpcException: Status(StatusCode="NotFound", Detail="Topic not found") | Publishing to a topic that doesn’t exist | Create the topic first |
AlreadyExists | Topic already exists | Creating a topic or subscription twice | Catch StatusCode.AlreadyExists |
ArgumentException: The given resource-name matches no pattern. | TopicName.Parse("orders"): a full name is required | TopicName.FromProjectTopic(projectId, "orders") |
InvalidArgument | Invalid [topics] name: (name=projects/demo-project/topics/go) | Topic ID too short or starting with “goog”; IDs need 3–255 characters and must start with a letter | Rename the topic |
InvalidOperationException: Message ordering must be enabled in settings before using OrderingKey | OrderingKey on a default publisher | EnableMessageOrdering = true in PublisherClient.Settings |
OutOfRange | The value for max_delivery_attempts is too small... | Dead-letter attempts below 5 | Use 5–100 |
warning CS0618: 'SubscriberClient.StopAsync(TimeSpan)' is obsolete | Old shutdown overload | StopAsync(ShutdownOptions, CancellationToken) |
What the Emulator Doesn’t Tell You
- Message size: the emulator accepted a message of 10 MB + 1 byte. The real service limits the data field to 10 MB and a publish request to 10 MB, so test big payloads against a real project (or store the payload in Cloud Storage and publish a reference).
- Subscription expiration: on the emulator, subscriptions never expire. In production, a subscription with no subscriber activity expires after 31 days by default. Set
ExpirationPolicywith no TTL for subscriptions that must survive a quiet month. - Message retention: the emulator keeps messages indefinitely; the service keeps unacknowledged messages for 7 days by default.
- IAM isn’t checked at all, and message IDs are small sequential numbers instead of long IDs.
In production, alert on the subscription’s oldest_unacked_message_age metric: a growing value means your subscribers aren’t keeping up.
FAQ
Do I need the gcloud CLI to use Pub/Sub from C#? No. The NuGet package talks to the API directly. You need credentials (ADC or a service account) for the real service, or the emulator for local work.
Push or pull subscriptions? Use pull (SubscriberClient) for workers you run yourself. Use push when the consumer is an HTTPS endpoint such as a Cloud Run service that scales to zero.
How does this compare with my other messaging posts? The same patterns (idempotent handlers, dead-letter queues, graceful shutdown) apply to Azure Service Bus. For the architecture around them, see event-driven architecture in C#. All cloud posts are listed in the cloud and security hub.