Provisioning an Event Grid Namespace

1. Start Locally

Firstly, we need to launch Locally which we can do from a terminal by running:

Once Locally has started, the Locally Dashboard will open automatically:

The az eventgrid namespace commands live in the eventgrid Azure CLI extension, so let's add it:

It's added to Locally's own copy of the Azure CLI configuration, so your usual az setup isn't touched.

2. Create a Resource Group

Next we can create the Resource Group to hold the namespace:

There's two things to note here:

1. The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with locally run.
2. Locally intentionally uses a different set of locations to Azure as a safety precaution, so that you can be confident you're deploying against Locally rather than regular Azure. You can also configure Locally to use the Azure locations too, but you'll want to be extra sure that you're prefixing commands with locally run when you do.

3. Create the Namespace

Now we can create the Event Grid Namespace:

{
  "hostname": "sample-egns-1.eventgrid.locally",
  "name": "sample-egns-1",
  "provisioningState": "Succeeded"
}

That eventgrid.locally hostname is served by Locally's own DNS server and points at the Event Grid Emulator running on your machine.

4. Create a topic and a subscription

Events are published to a topic inside the namespace. Let's create one called orders:

{
  "inputSchema": "CloudEventSchemaV1_0",
  "name": "orders",
  "provisioningState": "Succeeded"
}

To read events back off the topic, we'll add a subscription called worker with queue delivery. Rather than Event Grid pushing each event to a handler, our worker pulls events off the subscription when it's ready for them:

{
  "deliveryConfiguration": {
    "deliveryMode": "Queue",
    "queue": {
      "maxDeliveryCount": 4,
      "receiveLockDurationInSeconds": 60
    }
  },
  "name": "worker",
  "provisioningState": "Succeeded"
}

A received event is locked for 60 seconds, and handed out at most four times before it's given up on.

5. Publish an event

Publishing needs one of the namespace's access keys:

And its endpoint. The hostname we saw earlier doesn't include a port, and Locally serves Event Grid over HTTPS on port 5662, so we'll add it:

Now we can publish a CloudEvent to the orders topic:

{}

An empty object back means the event was accepted.

6. Receive and acknowledge the event

Let's receive the event from the worker subscription, saving the response to a file:

{
  "value": [
    {
      "brokerProperties": {
        "deliveryCount": 1,
        "lockToken": "16f41041-d43a-437d-b8a3-fd4eb3ed0b01"
      },
      "event": {
        "specversion": "1.0",
        "id": "order-42",
        "source": "/shop/orders",
        "type": "Shop.OrderPlaced",
        "data": {
          "orderId": 42,
          "total": 19.99
        }
      }
    }
  ]
}

The event is now locked to us. The lock token is what we use to settle it, so let's pull it out:

Once the work is done, acknowledging the event removes it from the subscription:

{
  "succeededLockTokens": [
    "16f41041-d43a-437d-b8a3-fd4eb3ed0b01"
  ],
  "failedLockTokens": []
}

So receiving again comes back empty:

{
  "value": []
}

7. Tidy up

Finally, we can tidy up. To remove the Resource Group and everything within it:

Doing this with other tooling

Whilst this guide used the Azure CLI, the namespace works the same way through any of the tooling that Locally supports - Microsoft.EventGrid/namespaces, Microsoft.EventGrid/namespaces/topics and Microsoft.EventGrid/namespaces/topics/eventSubscriptions resources in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way.

The same is true of the data plane: point the Azure Event Grid SDK for .NET, Go or Python at the endpoint and key from step 5, and your application publishes and receives events against Locally.

Next steps

To push events to a handler instead of pulling them, see Event Grid Topic. The Event Grid Emulator shows each subscription's pending, locked and acknowledged events.

Should you encounter any issues, please take a look at the troubleshooting section.

Resource types this guide uses

These are the Azure resource types this guide creates in Locally:

• Microsoft.EventGrid/namespaces
• Microsoft.EventGrid/namespaces/topics
• Microsoft.EventGrid/namespaces/topics/eventSubscriptions