coreex-subscriber

<!-- AI workflow asset — dual-audience notice: - In the Avanade/CoreEx repository: this file is the authored source. Edit it here. - In a consumer repository: this file was generated by `dotnet new coreex-ai` (or refreshed via `dotnet new coreex-ai --force` / the `/coreex-docs-sync` skill). Do not hand-edit it directly — propose the change upstream in Avanade/CoreEx instead, then refresh once it is released. -->

CoreEx: Subscriber

Guides you through adding or modifying a subscriber in a CoreEx Subscribe host. A subscriber is the messaging equivalent of a controller — it receives a command or event from the broker and immediately delegates to an Application-layer service or adapter. No business logic lives here.

When to Use

There are three distinct subscriber scenarios — determine which applies before writing any code:

Scenario	Trigger	Delegates to	Example
Command	A command addressed to this domain arrives on the broker	Application service	e.g. {Entity}ConfirmSubscriber → I{Entity}Service
Event — Data Sync	An event from another domain/system arrives; maintain a local cached copy	Replication adapter (IXxxSyncAdapter)	e.g. {Entity}ModifySubscriber → I{Entity}SyncAdapter
Event — Business Process	An event from another domain arrives; trigger a choreography step in this domain	Application service	e.g. {Entity}PlacedSubscriber → I{Entity}Service

Rule: Never subscribe to a command addressed to another domain — only to commands addressed to this domain, or to events from any domain. Subscribing to another domain's commands means you are not the intended recipient. Use events for cross-domain coordination.

When Not to Use

• HTTP API controllers — use coreex-api
• Application services that the subscriber calls — use coreex-app-service
• Replication adapter implementations (IXxxSyncAdapter) — use coreex-adapter
• Subscribe host Program.cs setup or Service Bus receiver wiring — see /.github/instructions/coreex-host-setup.instructions.md

Resolve project-wide choices from state before asking. Read the solution-root AGENTS.md Feature Configuration: messaging-provider gates this skill (a Subscribe host exists only when a messaging provider is configured); outbox-enabled determines whether the delegated service publishes resulting events transactionally; rop-enabled confirms Result/Result<T> return-style pipelines. Only prompt for what is unrecorded; re-state resolved values for confirmation.

Quick Reference

• Untyped subscriber (SubscribedBase) — message carries data in the key only; extract with @event.Key.Required()
• Typed subscriber (SubscribedBase<TValue>) — message carries a serialised payload; set ValueValidator to validate before OnReceiveAsync
• [ScopedService] + one or more [Subscribe("subject")] attributes on every subscriber class
• No Program.cs edit needed — AddSubscribersUsing<T>() discovers all [Subscribe]-decorated classes automatically
• Subject format: {solution}.{domain}.{entity}.{action}[.v{n}] — include .v{n} only when the message carries a payload
• EventData.CreateCommand(...) for commands; EventData.CreateEvent(...) / new EventData().WithTitle(...) for events
• ErrorHandler for graceful not-found and retry/dead-letter control — share the same static instance across related subscribers
• Integration tests use WithApiTester<Program> (Subscribe host); simulate receipt via ServiceBusSubscribedSubscriber.ReceiveAsync(sbm) — see coreex-test-subscribe for the full test workflow

For full workflow and code examples see references/workflow.md.

Key References

• /.github/instructions/coreex-event-subscribers.instructions.md — full subscriber conventions reference
• /.github/instructions/coreex-host-setup.instructions.md — Subscribe host Program.cs shape
• Related skills: coreex-app-service (command/business-process subscribers delegate to it), coreex-adapter (data-sync subscribers drive IXxxSyncAdapter), coreex-api (sibling HTTP entry point), coreex-test-subscribe (full Subscribe-test integration test workflow — test class shape, simulating message receipt, per-scenario patterns, unsubscribed-subject test)
• Hosts layer deep-dive — optional (after /coreex-docs-sync)
• Illustrative examples (CoreEx sample — not present in your project):
  • ReservationConfirmSubscriber — command subscriber with ErrorHandler
  • ReservationCancelSubscriber — command subscriber sharing an ErrorHandler
  • ProductModifySubscriber — typed event-sync subscriber with ValueValidator
  • ProductDeleteSubscriber — untyped event-sync subscriber (key-only delete)