Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.
12. Deliver work with Service Bus
Use a Service Bus queue when workers must explicitly acknowledge work. Use a
topic when each subscriber needs its own copy of an event. Service Bus is a
separate service from Queue Storage: its .NET client is
Azure.Messaging.ServiceBus, and its native transport is AMQP over TLS.
This chapter and the next use separate example projects and a standalone cloud.
They do not replace the earlier tutorial's Program.cs or use its credentials.
The application environment from chapter 2 does not enable the AMQP listener.
Step 1: run the complete SDK example
On the host, install the native build prerequisites, .NET 10 SDK, Python 3 and OpenSSL, then run:
make service-bus-sdk-test
The command builds Quinzee, compiles the Service Bus Bicep example, restores the
locked SDK project and starts a temporary cloud with private certificates. It
deploys an orders queue and an events topic with first and second
subscriptions. The client sends, peeks, receives, renews a lock, abandons,
completes, dead-letters and fans out messages. It also checks bearer
authentication and rejection of invalid SAS and unsupported batch sends.
Success ends with Service Bus SDK smoke passed; the fixture removes its
temporary state. No Azure account or host trust/DNS change is needed.
The command supplies a temporary connection, namespace and trusted root to its client. The persistent lab below explains how to prepare those same prerequisites for your own program; a client cannot connect using the namespace name alone.
Step 2: understand delivery and settlement
This excerpt assumes an already authenticated ServiceBusClient named client,
as created by the complete example:
await using var sender = client.CreateSender("orders");
await using var receiver = client.CreateReceiver("orders");
await sender.SendMessageAsync(new ServiceBusMessage("invoice-42")
{
MessageId = "invoice-42", ContentType = "text/plain"
});
var message = await receiver.ReceiveMessageAsync(TimeSpan.FromSeconds(5));
if (message is null) throw new InvalidOperationException("No work available");
Console.WriteLine(message.Body.ToString());
await receiver.CompleteMessageAsync(message);
The default receive mode is PeekLock. Receipt reserves the message; successful
completion removes it. In a real worker, complete only after committing the
application's work. An abandoned or expired lock makes the message available
again, so handlers must tolerate redelivery. A MessageId does not enable
duplicate detection. Renew a lock before it expires if processing needs longer.
| Operation | Effect |
|---|---|
| Peek | Inspect a message without reserving it |
| Receive in PeekLock mode | Obtain an exclusive, expiring lock |
| Complete | Remove the message using its current lock |
| Abandon | Release the lock for another delivery |
| Dead-letter | Move failed work to the entity's $DeadLetterQueue |
| ReceiveAndDelete | Remove immediately, before processing can succeed |
For topics, CreateSender("events") publishes one message, and
CreateReceiver("events", "first") receives the first subscription's copy.
The second subscription has an independent copy and lock. Create subscriptions
before publishing: a topic does not keep a copy for a future subscription.
Step 3: provision a persistent messaging lab
Use the following host commands when you want resources to remain available in QHQ after the isolated example finishes:
make certs
make cloud-up
make bicep-examples
install -d -m 700 .local/messaging
make qhq-run
These commands use .local/quinzee, the default HTTPS endpoint
https://localhost:11443, and a loopback AMQP port of 5671. QUINZEE_AMQP_PORT
changes the host AMQP port. Keep clients on the private Docker network when
using service DNS names; native namespace names end in
.servicebus.quinzee.cloud. Azure names require explicitly enabled emulation
and its matching client trust root.
In QHQ, select the standalone subscription and create resource group
quinzee-messaging in westeurope. Under Resource Manager → Deployments,
submit .packages/tools/service_bus.json. Save this parameter document as
.local/messaging/service-bus.parameters.json and select it in the deployment:
{
"parameters": {
"namespaceName": { "value": "bookbus" }
}
}
Use a different namespace if bookbus already
belongs to another exercise. After the deployment succeeds, open Service Bus
→ Namespaces. Its Namespaces, Queues, Topics and Subscriptions controls inspect
the resources; they do not reveal keys or consume messages.
Step 4: obtain connection details privately
Save the following as .local/messaging/client.py. Run it from the repository
root with python3 .local/messaging/client.py. It signs in to the standalone
cloud, obtains the primary namespace connection string through ARM, and writes
it to a private file for the next chapter. It uses the first local subscription;
adjust the group or namespace if you selected different names in QHQ.
import http.client
import json
import os
from pathlib import Path
import ssl
import urllib.parse
ROOT = Path(__file__).resolve().parents[2]
context = ssl.create_default_context(cafile=str(
ROOT / ".local/certificates/ca/quinzee-dev-root-ca.crt"))
port = int(os.environ.get("QUINZEE_HTTPS_PORT", "11443"))
token = ""
def request(method, path, body=None, *, host=None, headers=None):
fields = dict(headers or {})
if token and not host:
fields["Authorization"] = "Bearer " + token
if host:
fields["Host"] = host
if isinstance(body, dict):
body = json.dumps(body)
fields["Content-Type"] = "application/json"
connection = http.client.HTTPSConnection(
"localhost", port, context=context, timeout=15)
try:
connection.request(method, path, body, fields)
response = connection.getresponse()
raw = response.read()
if not 200 <= response.status < 300:
raise RuntimeError(f"Request failed: HTTP {response.status}")
return json.loads(raw) if raw else None
finally:
connection.close()
def access_token(scope):
credentials = json.loads(
(ROOT / ".local/quinzee/credentials.json").read_text())
form = dict(grant_type="client_credentials",
client_id=credentials["clientId"],
client_secret=credentials["clientSecret"], scope=scope)
return request("POST",
f"/{credentials['tenantId']}/oauth2/v2.0/token",
urllib.parse.urlencode(form),
host="localhost",
headers={"Content-Type": "application/x-www-form-urlencoded"}
)["access_token"]
token = access_token("https://management.azure.com/.default")
subscription = request("GET", "/subscriptions?api-version=2023-05-01")
sub = subscription["value"][0]["subscriptionId"]
group = f"/subscriptions/{sub}/resourceGroups/quinzee-messaging"
if __name__ == "__main__":
keys = request("POST", group +
"/providers/Microsoft.ServiceBus/namespaces/bookbus" +
"/authorizationRules/RootManageSharedAccessKey/listKeys" +
"?api-version=2024-01-01", {})
os.umask(0o077)
destination = ROOT / ".local/messaging/connection.txt"
with destination.open("x") as output:
output.write(keys["primaryConnectionString"])
print("Saved private Service Bus connection file")
The helper deliberately refuses to overwrite an existing connection file. It
verifies the local HTTPS endpoint's CA and hostname; the Host header selects
the local service without changing system DNS. Keep this directory private and
out of source control. The connection string grants broad namespace access;
never include it in screenshots, logs or command-line arguments.
For your own .NET client, read that file into the ServiceBusClient constructor,
select AmqpTcp, and provide the environment's public CA. On a forwarded port,
set CustomEndpointAddress to the local TLS endpoint while preserving the
namespace in the connection string. The complete SDK example demonstrates
private CA trust with hostname checking retained. An HTTPS health response alone
does not prove that AMQP is listening or that a message was settled.
For capacity planning, this local broker retains at most 10,000 message copies in a 256 MiB store. Topic subscriptions each consume a copy. Use small synthetic messages while learning, settle completed work, and inspect dead letters when receives stop succeeding. Unsupported batch sends, sessions, transactions, scheduling and WebSockets return errors; use the single-message TLS workflow shown in this chapter.