create-pubsub-dotnet

Files (2)

• REFERENCE.md
• SKILL.md

SKILL.md (first lines)

# Create Dapr Pub/Sub .NET Application

## Overview

This skill creates a new Dapr pub/sub application in .NET: a publisher, a subscriber or both, sharing the message contract the user described and one Redis-backed `pubsub` component. The subscriber uses a declarative (default), programmatic or streaming subscription, and the app runs with `dapr run -f .` or with .NET Aspire.

The application is built from the user's own domain. There is no built-in sample scenario: the event, its fields, its topic and what the subscriber does with it all come from the **Check specification** interview, and every template is filled in from the placeholder vocabulary in [`../dapr-shared/pubsub-placeholders.md`](../dapr-shared/pubsub-placeholders.md).

## Execution Order

You MUST follow these phases in strict order:
1. **Check specification** - Check if the user specified what needs to be built; infer first, then ask.
2. **Check optional tools** — Check whether the Diagrid Dapr Dev Dashboard is installed and remember the result. Never stop, ask or install for this.
3. **Project Setup** — Create all files and folders.
4. **Verify** — Verify that the solution builds.
5. **Create README.md** — Create a readme that summarizes what is built and how to run & test the application. Do not provide instructions at the end of this phase.
6. **Show final message** - Your LAST output MUST be EXACTLY the message defined in the `## Show final message` section: the closing sentence followed by the Dev Dashboard recommendation. Do NOT add any other text, summary, or commentary.

## Prerequisites

The following must be installed by the user before this skill can run. Do not run the check-prereq skills; assume the prerequisites are installed.

- [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download)
- [Docker](https://www.docker.com/products/docker-desktop/) or [Podman](https://podman.io/docs/installation)
- [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) 1.18+ (`dapr init` provides Redis)
- [Aspire CLI](https://aspire.dev/get-started/install-cli/), only for Aspire mode

Packages (added during project setup):

- `Dapr.AspNetCore` `1.18.10` for the publisher, declarative subscribers and programmatic subscribers
- `Dapr.Messaging` `1.18.10` for streaming subscribers (no `Dapr.AspNetCore` in that project)
- Aspire mode only: `CommunityToolkit.Aspire.Hosting.Dapr` `13.0.0` and `Aspire.Hosting.Valkey` (same version as the `Aspire.AppHost.Sdk` that `aspire new` writes)
- Optional: the [Diagrid Dapr Dev Dashboard](https://github.com/diagridio/dev-dashboard). The skill only checks whether it is installed; it never installs it and never stops without it.

Concepts (CloudEvents, dead-letter, routing, TTL, raw payload, subscription types): [`../dapr-shared/pubsub-concepts.md`](../dapr-shared/pubsub-concepts.md).
Placeholder vocabulary used by every template: [`../dapr-shared/pubsub-placeholders.md`](../dapr-shared/pubsub-placeholders.md).

## Check specification

**Never build a default scenario.** The application is about the user's domain, and the templates are
placeholders waiting for it. Infer everything the prompt already says, then ask only what is missing, one
question at a time, waiting for each answer. If the prompt gives no domain at all, ask for it — do not
invent one and do not fall back to an order-processing example.

Domain, first:

1. "What is the purpose of this pub/sub application?"
2. "Which event does it publish, and on which topic?" Accept several if the user describes several; one is
   the normal case. The topic name is lowercase and hyphenated; the event type is PascalCase.
3. For each event: "Which fields does the message carry, and which one uniquely identifies it?" The
   identifying field becomes `<IdProperty>`: the handler deduplicates on it, so there must be exactly one
   per event. Ask for the type of each field when the name does not make it obvious.
4. "What should the subscriber do when it receives this event?" If the user wants nothing beyond receiving
   it, say that the handler will log it and move on; never invent a side effect.

Then the wiring:

5. "Should this app publish, subscribe, or both? (default: both)"
6. Only if the role includes a subscriber: "Which subscription type? **declarative** (default — a Subscription YAML file, no Dapr code in the subscriber), **programmatic** (`[Topic]`/`WithTopic` in code) or **streaming** (the app pulls messages; no inbound port)". Inference: "streaming", "no inbound port" or "pull" → streaming; "programmatic", `[Topic]` or `WithTopic` → programmatic; "declarative" or "subscription YAML" → declarative.
7. "Run it with the Dapr CLI (`dapr run`, default) or with .NET Aspire?"
8. "Minimal APIs (default) or controllers?" **Skip** this when the subscriber is streaming and the role is `subscriber`.
9. "What's the name of this project? It is used as the folder and solution name. Don't use any spaces."

Feature rules:

- The dead-letter topic (`<TopicName>-deadletter`) is on unless the user declines it.
- Routing (CEL), message TTL and raw payload are added only when the user mentions them. See `REFERENCE.md` → **Routing, TTL and raw payload**.
- If the user asks for a broker other than Redis (for example Kafka), still scaffold Redis locally and say so in the README; the README explains how to switch.
- Routing combined with streaming is unsupported. Ask: "Streaming subscriptions cannot route by content. Use a declarative subscription for this topic instead? (default: yes)". On yes, switch the type to declarative.

### Resolving the placeholders

Before creating any file, write out the resolved values and restate them to the user in two or three
lines, so a wrong reading is caught before it is scaffolded. Resolve them exactly as
[`../dapr-shared/pubsub-placeholders.md`](../dapr-shared/pubsub-placeholders.md) defines them:

| Placeholder | Resolved from |
|---|---|
| `<EventName>`, `<EventFields>`, `<IdProperty>` | questions 2 and 3 |
| `<eventVar>`, `<EventDescription>` | `<EventName>`, in camelCase and as a lowercase noun phrase |
| `<TopicName>`, `<DeadLetterTopicName>` | question 2; the dead-letter topic is `<TopicName>-deadletter` |
| `<TopicConstant>`, `<DeadLetterTopicConstant>`, `<TopicResource>` | PascalCase of `<TopicName>` |
| `<PublishRoute>`, `<PublishResource>`, `<SubscribeRoute>`, `<DeadLetterRoute>` | `<TopicName>`; the subscribe route is `/events/pubsub/<TopicName>` |
| `<ValidationCondition>`, `<HandlerBody>` | questions 3 and 4 |

Fixed, never derived from the domain: the component name `pubsub`, the class `PubSubNames`, the
idempotency store `IProcessedEvents` / `InMemoryProcessedEvents`, and `PublishFeatures`. `<root-kebab>` is
`<ProjectRoot>` in kebab-case (`ShipTrack` → `shiptrack`); app ids are `<root-kebab>-publisher` and
`<root-kebab>-subscriber`.

## Check optional tools

Check once whether the optional Dev Dashboard is installed by following the **Check** section of [`../dapr-shared/dev-dashboard.md`](../dapr-shared/dev-dashboard.md) (`diagrid-dev-dashboard --version`). Remember the result (`DevDashboardInstalled`) for the final message. This check never stops the skill: do not ask the user about it, do not install anything, and continue whether or not the dashboard is installed.

## Project Setup

Create the project root inside the current location where the terminal is open. Run all commands from inside `<ProjectRoot>` and do not `cd` elsewhere between commands.

### Dapr CLI mode (`dapr run`)

```shell
mkdir <ProjectRoot>
cd <ProjectRoot>
dotnet new sln --format slnx -n <ProjectRoot>
dotnet new web -n <ProjectRoot>.Publisher
dotnet new web -n <ProjectRoot>.Subscriber
dotnet new classlib -n <ProjectRoot>.Contracts
dotnet add <ProjectRoot>.Publisher package Dapr.AspNetCore --version 1.18.10
dotnet add <ProjectRoot>.Subscriber package Dapr.AspNetCore --version 1.18.10
dotnet add <ProjectRoot>.Publisher reference <ProjectRoot>.Contracts
dotnet add <ProjectRoot>.Subscriber reference <ProjectRoot>.Contracts
dotnet sln add <ProjectRoot>.Publisher <ProjectRoot>.Subscriber <ProjectRoot>.Contracts
```

- Role `publisher` or `subscriber`: create only that web project; no `classlib`; the contract goes in the project's `Models/` folder.
- Streaming subscriber: add `Dapr.Messaging` `1.18.10` to the subscriber instead of `Dapr.AspNetCore`.
- Set `<TargetFramework>net10.0</TargetFramework>` in every project.
- Delete the generated `Class1.cs` from the Contracts classlib.

From diagrid-labs/dapr-skills, MIT.

More from diagrid-labs/dapr-skills