quinzee.cloud

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.

Developer’s guide

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.