# apigenie-generator server aspnet (AsyncAPI)

Source: https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi
Part of the reference of [apigenie-generator](https://apigenie.pl/docs/reference/generator.md).
Its other pages: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir.md), [client fetch](https://apigenie.pl/docs/reference/generator/client-fetch.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server go](https://apigenie.pl/docs/reference/generator/server-go.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server mcp](https://apigenie.pl/docs/reference/generator/server-mcp.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client go](https://apigenie.pl/docs/reference/generator/client-go-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

[Tier 2](/docs/reference/generator/conformance#tiers) · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · [Verification](#verification)

Generate an ASP.NET Core application of the Kafka channels of an AsyncAPI document.

## Usage

```sh
apigenie-generator server aspnet [...OPTIONS] INPUT_FILE
```

## Description

`apigenie-generator server aspnet` generates from OpenAPI documents (see
[`apigenie-generator server aspnet`](/docs/reference/generator/server-aspnet)) and from AsyncAPI 3.x
documents, telling them apart by their `openapi` or `asyncapi` field. Documents referencing other
files are bundled first.

From an AsyncAPI document it generates an ASP.NET Core project (.NET 8, `Microsoft.NET.Sdk.Web`)
using the Kafka client [Confluent.Kafka](https://github.com/confluentinc/confluent-kafka-dotnet)
(Apache-2.0, pinned at 2.15.1 in the project file). The consumers are hosted services of the
application, so the same project can also serve a REST API. By default the application is the one
the document describes: it sends the messages of `send` operations and receives the messages of
`receive` operations. Set the `perspective` option to `counterpart` to swap them.

The generator writes the Kafka channels: the channels of servers with the `kafka` or
`kafka-secure` protocol, and channels with a Kafka binding in documents without servers. Channels
of other protocols are skipped and reported as info.

```csharp
public sealed class LabelFarm : IRequestLabelRenderHandler
{
    public Task<IRequestLabelRenderReply?> OnRenderLabelAsync(RenderLabel message, CancellationToken cancellationToken)
    {
        IRequestLabelRenderReply reply = new LabelRendered { Key = message.Key, Payload = Render(message.Payload) };
        // sent to Topics.LabelRenderResults with the request's correlation id
        return Task.FromResult<IRequestLabelRenderReply?>(reply);
    }
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCarpetExpressKafka(builder.Configuration);
builder.Services.AddScoped<IRequestLabelRenderHandler, LabelFarm>();
var app = builder.Build();
app.MapPost("/shipments/{id}/delivered", async (string id, PublishShipmentEventsSender sender) =>
    await sender.SendShipmentDeliveredAsync(Delivered(id)));
app.Run();
```

The project's root namespace (and assembly name) is `root_namespace`, else `--package-name` or the
document's title in PascalCase; the names of the application's classes start with the latter
(`CarpetExpress`):

| File | Contents |
| ---- | -------- |
| `Models/*.cs` | the types of the schemas the payloads use, as `apigenie-generator client csharp` writes them: records with `[JsonPropertyName]` and DataAnnotations, enums, and unions as abstract records |
| `Serialization/*.cs` | the JSON context of the source generator of System.Text.Json, and the converters of unions, which read the discriminator wherever it is |
| `Messages/*.cs` | a record per message (`Key`, `Headers`, `Payload`), its headers record and header constants, with `ToRecord()` and `FromRecord()` |
| `Kafka/*.cs` | the settings, the handler interfaces and consumers of the received operations, the senders of the sent operations, the reply interfaces, and `Add<Name>Kafka` |
| `Infrastructure/*.cs` | the Kafka runtime (producer, consumer service, requester, headers) and the validation of messages |
| `<RootNamespace>.csproj`, `README.md` | the project |
| `Program.cs`, `appsettings.json`, `Handlers/*.cs` | starting points, written once and never overwritten |

- **Messages.** Headers are the message's headers merged with those of its traits as AsyncAPI
  does (JSON Merge Patch: a later `required` list replaces an earlier one). Header values are
  text on Kafka, so headers are `string`, `long`, `double` or `bool` properties, nullable when
  optional, with DataAnnotations for their length, pattern, format, values and range. Headers
  with a constant value, e.g. the `ce_specversion` and `ce_type` of CloudEvents in binary mode,
  are constants (`ShipmentStatusChanged.CeType`), which senders write and receivers compare.
  Messages are validated as a whole before they are sent and after they are received.
- **Received operations.** A handler interface per operation (`IPublishShipmentEventsHandler`)
  has an `On<Message>Async` method per message and, when there are several messages,
  `OnUnknownAsync`, which ignores records by default. Register an implementation with the
  dependency injection container: the operation's consumer, a `BackgroundService` in the
  operation's consumer group, resolves it in a scope of its own for every record. Several
  messages are told apart by a payload property or a header with a distinct constant value
  (e.g. `type` or `ce_type`); otherwise the first message whose payload reads strictly and is
  valid is chosen. Records matching no message go to `OnUnknownAsync`.
- **Delivery.** A record is committed once its handler returns. When the handler throws, the
  consumer logs the error and handles the record again after `RetryDelay`, so the records of a
  failing partition wait. Records that can't be read or are invalid messages are logged as
  warnings and committed. Stopping the host (Ctrl+C, SIGTERM) cancels the consumers, which close
  and leave their groups.
- **Sent operations.** A sender per operation (`PublishShipmentEventsSender`), registered as a
  singleton, has a `Send<Message>Async` method per message that validates the message and
  completes once the brokers have it. Senders, requesters and repliers share one producer.
- **Request/reply** with a reply channel: the requester's `Request<Message>Async` returns the
  reply (one of the reply messages, `IRequestLabelRenderReply`), matched by the request's
  correlation id, which is generated when the request has none; `ReplyTimeout` bounds the wait.
  Each requester consumes the reply topic without a consumer group, from a minute before it
  started, so a reply isn't missed and every instance of the application sees every reply. A
  replier's handler returns the reply (`null` for none), which is sent to the reply topic with the
  request's correlation id copied (to a header, or a payload property, as the `correlationId`
  locations say).

### Settings

The `AsyncApi:Kafka` section of the configuration holds the settings, with the document's values
as defaults; `appsettings.json` lists them, and environment variables override them as usual in
ASP.NET Core (`AsyncApi__Kafka__BootstrapServers=localhost:9092`):

```json
{
  "AsyncApi": {
    "Kafka": {
      "BootstrapServers": "kafka-eu.events.carpetexpress.example:9093",
      "ClientId": "carpet-express",
      "Topics": { "ShipmentEvents": "carpetexpress.shipment-events.v2" },
      "Operations": {
        "PublishShipmentEvents": { "GroupId": "carpet-express-publish-shipment-events", "ClientId": "carpet-express-publish-shipment-events" }
      },
      "ReplyTimeout": "00:00:30",
      "RetryDelay": "00:00:01",
      "Consumer": { "security.protocol": "SASL_SSL" },
      "Producer": { "security.protocol": "SASL_SSL" }
    }
  }
}
```

`BootstrapServers` defaults to the host of the first Kafka server, its variables replaced by their
defaults. Group and client ids come from the `groupId` and `clientId` schemas of the Kafka
operation bindings, of the operation or its traits: their `const`, single `enum` value, `default`
or first example. Without a value, `<package name in kebab case>-<operation>` is used, and the
documentation of the setting names the binding's pattern. The partitions, replicas and topic
configuration of channel bindings are documented on the topic settings; the generated code creates
no topics. `Consumer` and `Producer` take further librdkafka properties.

### Security

Each SASL or client certificate scheme of the Kafka servers is a constant of
`<Name>KafkaSecurity`, with its key as value. Set `Security` to the key (`"Security": "kafkaScram"`,
or `AsyncApi__Kafka__Security=kafkaScram`) to connect every consumer and producer with the scheme;
without one, they connect without security. The credentials come from environment variables named
after the scheme key, e.g. `KAFKA_SCRAM_USERNAME` and `KAFKA_SCRAM_PASSWORD`:

| Scheme | Settings of Confluent.Kafka |
| ------ | --------------------------- |
| `scramSha256`, `scramSha512` | `SecurityProtocol` `SaslSsl` (`SaslPlaintext` on `kafka` servers), `SaslMechanism`, and `<KEY>_USERNAME` and `<KEY>_PASSWORD` as `SaslUsername` and `SaslPassword` |
| `plain`, `userPassword` | the same with `SaslMechanism.Plain` |
| `X509` | `SecurityProtocol` `Ssl`, and the PEM files named by `<KEY>_CERT` (the client certificate), `<KEY>_KEY` (its private key) and `<KEY>_CA` as `SslCertificateLocation`, `SslKeyLocation` and `SslCaLocation` |

`<Name>KafkaSecurity.With<Scheme>(config, ...)` applies a scheme with credentials from elsewhere,
e.g. a secret store, to a `ClientConfig`. Other schemes (`gssapi`, `oauth2`, ...) are left out with
a warning.

### Avro payloads

A message whose `schemaFormat` is an Avro one (`application/vnd.apache.avro;version=1.9.0`, with or
without `+json` or `+yaml`) carries a class of its record schema as its payload, in `Avro/<full
name>.cs`: an `ISpecificRecord` of Apache.Avro in the namespace of the schema (`<root
namespace>.Avro` for a schema without one), with C# enums for the schema's enums. The logical types
`date` and `timestamp-*` (`local-timestamp-*` too) are `DateTime`, `time-millis` and `time-micros`
`TimeSpan`, and `uuid` `Guid`; a union with `null` is a nullable type, other unions `object?`. A
root schema that isn't a record, and records with `decimal` fields, are skipped with a warning.

The generated `KafkaAvro` codec encodes and decodes the payloads in Avro's binary encoding, with
the id of the writer's schema where the Kafka binding of the message says: before the payload
(`schemaIdLocation: payload`, Confluent's wire format) or in the `apicurio.value.globalId` header
(`schemaIdLocation: header`). Senders get the id from a schema registry, by the subject of
`schemaLookupStrategy` (`TopicIdStrategy`, `{topic}-value`, by default):

- an `ISchemaRegistry` service, when the application registers one;
- otherwise the Confluent-compatible registry at `SchemaRegistryUrl` (by default the
  `schemaRegistryUrl` of the Kafka binding of the first Kafka server that has one), with the basic
  authentication of `SchemaRegistryUsername` and `SchemaRegistryPassword`. It registers each schema
  once with `POST /subjects/{subject}/versions`.

```csharp
builder.Services.AddSingleton<ISchemaRegistry>(
    new ConfluentSchemaRegistry("https://schemas.events.carpetexpress.example", "ingest", builder.Configuration["RegistryPassword"]));
```

Consumers decode records with the schema of the generated class, so the writer's schema must be
the same; a record that isn't a payload of it is rejected. Request/reply operations with Avro
messages are skipped with a warning.

Not supported, and reported as warnings: payloads of other non-JSON schema formats (the messages
are skipped, and operations left without a message too), reply addresses given by runtime
expressions, and Kafka topics with parameters. With a correlation id in the payload at a place that
isn't a string or uuid property of the payload record, the request must carry the id and the
replier's handler must copy it.

## Extensions

| Extension | Effect |
| --------- | ------ |
| `x-apigenie.codegen.disabled` | `true` on a channel or an operation leaves it out (with the operations of a channel left out) |
| `x-enum-varnames`, `x-enum-names` | names of the members of an enum, in PascalCase |
| `x-enum-descriptions`, `x-enumDescriptions` | documentation comments of the members of an enum |

The extensions can live in an overlay for this target instead of in the document, e.g.
`aspnet.overlay.yaml`:

```yaml
overlay: 1.0.0
info:
  title: ASP.NET names
  version: 1.0.0
actions:
  - target: $.components.schemas.OrderStatus
    update:
      x-enum-varnames: [Created, Paid, Shipped]
  - target: $.operations.publishAudit
    update:
      x-apigenie:
        codegen:
          disabled: true
```

```sh
apigenie-generator server aspnet asyncapi.yaml --overlay aspnet.overlay.yaml -o out
```

## Options

### -c, --config

Path to the configuration file to use. See the "Configuration" section for more information.

### --overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the "Extensions" section. Can be repeated: the overlays apply in order, after those
listed under `commands.generate.server_aspnet.overlay` in the configuration file (with paths
relative to it). Warnings and errors about a value an overlay set point to the overlay. The overlays
apply to the AsyncAPI document bundled with the files it references.

### --strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (`OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.`).

### --check

Writes nothing: compares what the generator would write with the output directory, prints the
files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See
[Check that generated code is up to date](/docs/reference/generator#check-that-generated-code-is-up-to-date).

### -o, --output

Directory where the project is generated.

### --package-name

Root namespace of the generated code and base of the names of the application's classes, in
PascalCase (`carpet-express` gives `CarpetExpress`); defaults to the title of the API. Its kebab
case is the base of default group and client ids.

### --package-version

Version of the project; defaults to the version of the API when it is a .NET version, else 1.0.0.

### -p, --property

Applies to OpenAPI documents only; using it with an AsyncAPI document is an error.

## Configuration

The options are read from the `asyncapi` section of the configuration of `apigenie-generator server aspnet`;
its other keys configure the generation from OpenAPI documents.

```yaml
version: '1.0'
commands:
  generate:
    server_aspnet:
      asyncapi:
        root_namespace: Acme.Events
        validation: true
        program: true
        perspective: application
```

| Option | Description |
| ------ | ----------- |
| `root_namespace` | Root namespace and assembly name of the project (default: from `--package-name` or the title) |
| `validation` | `true` (default): validate messages by their DataAnnotations before sending and after receiving them |
| `program` | `true` (default): write `Program.cs`, `appsettings.json` and the handler stubs when they don't exist |
| `perspective` | `application` (default): the described application; `counterpart`: its counterpart, receiving what it sends |

## Verification

The [codegen conformance suite](/docs/reference/generator#conformance-checks) runs this target on the Carpet Express AsyncAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. [All targets](/docs/reference/generator/conformance#asyncapi).

This target's support tier is [Tier 2](/docs/reference/generator/conformance#tiers). It goes through all three levels before every release, like Tier 1. It doesn't aim to support every feature: a feature of the fixture can stay unsupported, with the reason its manifest gives.

| Results | Level 1 | Level 2 | Level 3 |
| --- | --- | --- | --- |
| Release 0.12.0, `server aspnet` | ✓ snapshots of 3.0; 31 supported, 0 not yet | ✓ pass (.NET SDK 8.0.204) | ✓ 7 of 7 operations pass (.NET SDK 8.0.204) |
| Release 0.12.0, `server aspnet (counterpart)` | ✓ snapshots of 3.0; 31 supported, 0 not yet | ✓ pass (.NET SDK 8.0.204) | ✓ 7 of 7 operations pass (.NET SDK 8.0.204) |
| Development version, `server aspnet` | ✓ snapshots of 3.0; 31 supported, 0 not yet | runs before a release | runs before a release |
| Development version, `server aspnet (counterpart)` | ✓ snapshots of 3.0; 31 supported, 0 not yet | runs before a release | runs before a release |
