From 281a7ca8bf55d2a0ec231de1dff45c49a7705852 Mon Sep 17 00:00:00 2001 From: Erwin Date: Mon, 6 Apr 2026 12:26:33 +0200 Subject: [PATCH] Add package readme's in consistent style and update missing info in the guide Signed-off-by: Erwin --- docs/guide.md | 10 +++-- src/CloudNative.CloudEvents.Amqp/PACKAGE.md | 31 ++++++++++++++ .../PACKAGE.md | 40 +++++++++++++++++++ src/CloudNative.CloudEvents.Avro/PACKAGE.md | 33 +++++++++++++++ src/CloudNative.CloudEvents.Kafka/PACKAGE.md | 31 ++++++++++++++ src/CloudNative.CloudEvents.Mqtt/PACKAGE.md | 31 ++++++++++++++ .../PACKAGE.md | 34 ++++++++++++++++ .../PACKAGE.md | 33 +++++++++++++++ .../PACKAGE.md | 34 ++++++++++++++++ src/CloudNative.CloudEvents/PACKAGE.md | 38 ++++++++++++++++++ src/Directory.Build.props | 4 +- 11 files changed, 314 insertions(+), 5 deletions(-) create mode 100644 src/CloudNative.CloudEvents.Amqp/PACKAGE.md create mode 100644 src/CloudNative.CloudEvents.AspNetCore/PACKAGE.md create mode 100644 src/CloudNative.CloudEvents.Avro/PACKAGE.md create mode 100644 src/CloudNative.CloudEvents.Kafka/PACKAGE.md create mode 100644 src/CloudNative.CloudEvents.Mqtt/PACKAGE.md create mode 100644 src/CloudNative.CloudEvents.NewtonsoftJson/PACKAGE.md create mode 100644 src/CloudNative.CloudEvents.Protobuf/PACKAGE.md create mode 100644 src/CloudNative.CloudEvents.SystemTextJson/PACKAGE.md create mode 100644 src/CloudNative.CloudEvents/PACKAGE.md diff --git a/docs/guide.md b/docs/guide.md index dcae258f..cd361d83 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -19,6 +19,7 @@ unnecessary dependencies. These packages are: |[CloudNative.CloudEvents.Kafka](https://www.nuget.org/packages/CloudNative.CloudEvents.Kafka)|Kafka protocol binding using [Confluent.Kafka](https://www.nuget.org/packages/Confluent.Kafka)| |[CloudNative.CloudEvents.Mqtt](https://www.nuget.org/packages/CloudNative.CloudEvents.Mqtt)|MQTT protocol binding using [MQTTnet](https://www.nuget.org/packages/MQTTnet)| |[CloudNative.CloudEvents.NewtonsoftJson](https://www.nuget.org/packages/CloudNative.CloudEvents.NewtonsoftJson)|JSON event formatter using [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json)| +|[CloudNative.CloudEvents.Protobuf](https://www.nuget.org/packages/CloudNative.CloudEvents.Protobuf)|Protobuf event formatter using [Google.Protobuf](https://www.nuget.org/packages/Google.Protobuf)| |[CloudNative.CloudEvents.SystemTextJson](https://www.nuget.org/packages/CloudNative.CloudEvents.SystemTextJson)|JSON event formatter using [System.Text.Json](https://www.nuget.org/packages/System.Text.Json)| Note that protocol bindings for HTTP using `HttpRequestMessage`, @@ -113,7 +114,7 @@ if you write your own extensions: - Create a static class for all related extension attributes (e.g. the `sequence` and `sequencetype` extension attributes are both exposed - via the `CloudNative.CloudEvents.Extension.Sequence` class) + via the `CloudNative.CloudEvents.Extensions.Sequence` class) - Create a static read-only property of type `CloudEventAttribute` for each extension attribute - Create a static read-only property of type @@ -145,7 +146,7 @@ methods, typically extracting a CloudEvent from an existing transport message, or creating/populating a transport message with an existing CloudEvent. -Protocol bindings work with [CloudEvent formatters](#event-formatters) to +Protocol bindings work with [CloudEvent formatters](#cloudevent-formatters) to determine exactly how the CloudEvent is represented within any given transport message. @@ -161,7 +162,7 @@ The following table summarizes the protocol bindings available: |Protocol binding|Namespace|Types| |-|-|-| |HTTP (built-in)|CloudNative.CloudEvents.Http|HttpClientExtensions, HttpListenerExtensions, HttpWebExtensions| -|HTTP (ASP.NET Core)|CloudNative.CloudEvents.AspNetCore|HttpRequestExtensions, CloudEventJsonInputFormatter| +|HTTP (ASP.NET Core)|CloudNative.CloudEvents.AspNetCore|HttpRequestExtensions, HttpResponseExtensions| |AMQP|CloudNative.CloudEvents.Amqp|AmqpExtensions| |Kafka|CloudNative.CloudEvents.Kafka|KafkaExtensions| |MQTT|CloudNative.CloudEvents.Mqtt|MqttExtensions| @@ -193,11 +194,12 @@ For structured mode (and batch mode) messages, the way in which the CloudEvent (or batch of CloudEvents) is represented is determined by the *CloudEvent format* being used. In the .NET SDK, a CloudEvent format is represented by concrete types derived from the -`CloudEventFormatter` abstract base class. Two formats are supported: +`CloudEventFormatter` abstract base class. Three formats are supported: - JSON, via the `JsonEventFormatter` types in the `CloudNative.CloudEvents.SystemTextJson` and `CloudNative.CloudEvents.NewtonsoftJson` packages - Avro, via the `AvroEventFormatter` type in the `CloudNative.CloudEvents.Avro` package +- Protobuf, via the `ProtobufEventFormatter` type in the `CloudNative.CloudEvents.Protobuf` package Note that a `CloudEventFormatter` in the .NET SDK has more responsibility than a CloudEvent format in the specification, in diff --git a/src/CloudNative.CloudEvents.Amqp/PACKAGE.md b/src/CloudNative.CloudEvents.Amqp/PACKAGE.md new file mode 100644 index 00000000..b0a56c50 --- /dev/null +++ b/src/CloudNative.CloudEvents.Amqp/PACKAGE.md @@ -0,0 +1,31 @@ +## About + +This package provides a protocol binding for transporting CloudEvents over AMQP using AMQPNetLite; for an overview of protocol bindings and their types in this SDK, see the [Protocol bindings](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#protocol-bindings) section of the user guide. + +## How to Use + +Use this package with a CloudEvent and formatter to create an AMQP message: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.Amqp; +using CloudNative.CloudEvents.SystemTextJson; + +var cloudEvent = new CloudEvent +{ + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/orders"), + Type = "com.example.order.created" +}; + +var formatter = new JsonEventFormatter(); +var message = cloudEvent.ToAmqpMessage(ContentMode.Structured, formatter); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [CloudEvents Core SDK](https://www.nuget.org/packages/CloudNative.CloudEvents/) +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [CloudEvents AMQP Protocol Binding specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/bindings/amqp-protocol-binding.md) diff --git a/src/CloudNative.CloudEvents.AspNetCore/PACKAGE.md b/src/CloudNative.CloudEvents.AspNetCore/PACKAGE.md new file mode 100644 index 00000000..f247976e --- /dev/null +++ b/src/CloudNative.CloudEvents.AspNetCore/PACKAGE.md @@ -0,0 +1,40 @@ +## About + +This package provides a protocol binding for transporting CloudEvents with ASP.NET Core request and response types; for an overview of protocol bindings and their types in this SDK, see the [Protocol bindings](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#protocol-bindings) section of the user guide. + +## How to Use + +Use this package with a formatter in an ASP.NET Core endpoint to read a CloudEvent from the request and write one to the response: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.AspNetCore; +using CloudNative.CloudEvents.SystemTextJson; +using Microsoft.AspNetCore.Http; + +app.MapPost("/events", async (HttpRequest request, HttpResponse response) => +{ + var formatter = new JsonEventFormatter(); + var cloudEvent = await request.ToCloudEventAsync(formatter); + + var result = new CloudEvent + { + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/processed"), + Type = "com.example.event.processed", + DataContentType = "application/json", + Data = new { OriginalId = cloudEvent.Id } + }; + + await result.CopyToHttpResponseAsync(response, ContentMode.Structured, formatter); +}); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [CloudEvents Core SDK](https://www.nuget.org/packages/CloudNative.CloudEvents/) +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [CloudEvents HTTP Protocol Binding specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/bindings/http-protocol-binding.md) +- [ASP.NET Core sample](https://github.com/cloudevents/sdk-csharp/tree/main/samples/CloudNative.CloudEvents.AspNetCoreSample) diff --git a/src/CloudNative.CloudEvents.Avro/PACKAGE.md b/src/CloudNative.CloudEvents.Avro/PACKAGE.md new file mode 100644 index 00000000..3902607e --- /dev/null +++ b/src/CloudNative.CloudEvents.Avro/PACKAGE.md @@ -0,0 +1,33 @@ +## About + +This package provides a CloudEvent formatter for the Avro event format; for an overview of formatters and their types in this SDK, see the [CloudEvent formatters](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#cloudevent-formatters) section of the user guide. + +## How to Use + +Create the formatter, encode a CloudEvent, then decode it again: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.Avro; + +var cloudEvent = new CloudEvent +{ + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/orders"), + Type = "com.example.order.created", + Data = new byte[] { 1, 2, 3, 4 } +}; + +var formatter = new AvroEventFormatter(); +var body = formatter.EncodeStructuredModeMessage(cloudEvent, out var contentType); +var decoded = formatter.DecodeStructuredModeMessage(body, contentType, extensionAttributes: null); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [CloudEvents Core SDK](https://www.nuget.org/packages/CloudNative.CloudEvents/) +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [Formatter implementation guide](https://github.com/cloudevents/sdk-csharp/blob/main/docs/formatters.md) +- [CloudEvents Avro Event Format specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/formats/avro-format.md) diff --git a/src/CloudNative.CloudEvents.Kafka/PACKAGE.md b/src/CloudNative.CloudEvents.Kafka/PACKAGE.md new file mode 100644 index 00000000..5001af0b --- /dev/null +++ b/src/CloudNative.CloudEvents.Kafka/PACKAGE.md @@ -0,0 +1,31 @@ +## About + +This package provides a protocol binding for transporting CloudEvents over Kafka using `Confluent.Kafka`; for an overview of protocol bindings and their types in this SDK, see the [Protocol bindings](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#protocol-bindings) section of the user guide. + +## How to Use + +Use this package with a CloudEvent and formatter to create a Kafka message: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.Kafka; +using CloudNative.CloudEvents.SystemTextJson; + +var cloudEvent = new CloudEvent +{ + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/orders"), + Type = "com.example.order.created" +}; + +var formatter = new JsonEventFormatter(); +var message = cloudEvent.ToKafkaMessage(ContentMode.Structured, formatter); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [CloudEvents Core SDK](https://www.nuget.org/packages/CloudNative.CloudEvents/) +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [CloudEvents Kafka Protocol Binding specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/bindings/kafka-protocol-binding.md) diff --git a/src/CloudNative.CloudEvents.Mqtt/PACKAGE.md b/src/CloudNative.CloudEvents.Mqtt/PACKAGE.md new file mode 100644 index 00000000..ef0358ca --- /dev/null +++ b/src/CloudNative.CloudEvents.Mqtt/PACKAGE.md @@ -0,0 +1,31 @@ +## About + +This package provides a protocol binding for transporting CloudEvents over MQTT using MQTTnet; for an overview of protocol bindings and their types in this SDK, see the [Protocol bindings](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#protocol-bindings) section of the user guide. + +## How to Use + +Use this package with a CloudEvent and formatter to create an MQTT message: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.Mqtt; +using CloudNative.CloudEvents.SystemTextJson; + +var cloudEvent = new CloudEvent +{ + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/orders"), + Type = "com.example.order.created" +}; + +var formatter = new JsonEventFormatter(); +var message = cloudEvent.ToMqttApplicationMessage(ContentMode.Structured, formatter, "orders/created"); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [CloudEvents Core SDK](https://www.nuget.org/packages/CloudNative.CloudEvents/) +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [CloudEvents MQTT Protocol Binding specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/bindings/mqtt-protocol-binding.md) diff --git a/src/CloudNative.CloudEvents.NewtonsoftJson/PACKAGE.md b/src/CloudNative.CloudEvents.NewtonsoftJson/PACKAGE.md new file mode 100644 index 00000000..68711305 --- /dev/null +++ b/src/CloudNative.CloudEvents.NewtonsoftJson/PACKAGE.md @@ -0,0 +1,34 @@ +## About + +This package provides a CloudEvent formatter for the JSON event format using `Newtonsoft.Json`; for an overview of formatters and their types in this SDK, see the [CloudEvent formatters](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#cloudevent-formatters) section of the user guide. + +## How to Use + +Create the formatter, encode a CloudEvent, then decode it again: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.NewtonsoftJson; + +var cloudEvent = new CloudEvent +{ + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/orders"), + Type = "com.example.order.created", + DataContentType = "application/json", + Data = new { OrderId = 1234 } +}; + +var formatter = new JsonEventFormatter(); +var body = formatter.EncodeStructuredModeMessage(cloudEvent, out var contentType); +var decoded = formatter.DecodeStructuredModeMessage(body, contentType, extensionAttributes: null); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [CloudEvents Core SDK](https://www.nuget.org/packages/CloudNative.CloudEvents/) +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [Formatter implementation guide](https://github.com/cloudevents/sdk-csharp/blob/main/docs/formatters.md) +- [CloudEvents JSON Event Format specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/formats/json-format.md) diff --git a/src/CloudNative.CloudEvents.Protobuf/PACKAGE.md b/src/CloudNative.CloudEvents.Protobuf/PACKAGE.md new file mode 100644 index 00000000..1358d00e --- /dev/null +++ b/src/CloudNative.CloudEvents.Protobuf/PACKAGE.md @@ -0,0 +1,33 @@ +## About + +This package provides a CloudEvent formatter for the Protobuf event format using `Google.Protobuf`; for an overview of formatters and their types in this SDK, see the [CloudEvent formatters](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#cloudevent-formatters) section of the user guide. + +## How to Use + +Create the formatter, encode a CloudEvent, then decode it again: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.Protobuf; + +var cloudEvent = new CloudEvent +{ + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/orders"), + Type = "com.example.order.created", + Data = "Order created" +}; + +var formatter = new ProtobufEventFormatter(); +var body = formatter.EncodeStructuredModeMessage(cloudEvent, out var contentType); +var decoded = formatter.DecodeStructuredModeMessage(body, contentType, extensionAttributes: null); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [CloudEvents Core SDK](https://www.nuget.org/packages/CloudNative.CloudEvents/) +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [Formatter implementation guide](https://github.com/cloudevents/sdk-csharp/blob/main/docs/formatters.md) +- [CloudEvents Protobuf Event Format specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/formats/protobuf-format.md) diff --git a/src/CloudNative.CloudEvents.SystemTextJson/PACKAGE.md b/src/CloudNative.CloudEvents.SystemTextJson/PACKAGE.md new file mode 100644 index 00000000..9d61a2e5 --- /dev/null +++ b/src/CloudNative.CloudEvents.SystemTextJson/PACKAGE.md @@ -0,0 +1,34 @@ +## About + +This package provides a CloudEvent formatter for the JSON event format using `System.Text.Json`; for an overview of formatters and their types in this SDK, see the [CloudEvent formatters](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#cloudevent-formatters) section of the user guide. + +## How to Use + +Create the formatter, encode a CloudEvent, then decode it again: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.SystemTextJson; + +var cloudEvent = new CloudEvent +{ + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/orders"), + Type = "com.example.order.created", + DataContentType = "application/json", + Data = new { OrderId = 1234 } +}; + +var formatter = new JsonEventFormatter(); +var body = formatter.EncodeStructuredModeMessage(cloudEvent, out var contentType); +var decoded = formatter.DecodeStructuredModeMessage(body, contentType, extensionAttributes: null); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [CloudEvents Core SDK](https://www.nuget.org/packages/CloudNative.CloudEvents/) +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [Formatter implementation guide](https://github.com/cloudevents/sdk-csharp/blob/main/docs/formatters.md) +- [CloudEvents JSON Event Format specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/formats/json-format.md) diff --git a/src/CloudNative.CloudEvents/PACKAGE.md b/src/CloudNative.CloudEvents/PACKAGE.md new file mode 100644 index 00000000..613af6e0 --- /dev/null +++ b/src/CloudNative.CloudEvents/PACKAGE.md @@ -0,0 +1,38 @@ +## About + +Core CloudEvents support for .NET. + +This package provides the core CloudEvents types for representing events and their attributes in .NET, plus the `CloudEventFormatter` base class. + +It also includes the built-in HTTP protocol binding; for an overview of protocol bindings and their types in this SDK, see the [Protocol bindings](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md#protocol-bindings) section of the user guide. + +## How to Use + +You can use the core package on its own, or combine it with a formatter package such as [CloudNative.CloudEvents.SystemTextJson](https://www.nuget.org/packages/CloudNative.CloudEvents.SystemTextJson/) when you want to serialize events with the built-in HTTP binding: + +```csharp +using CloudNative.CloudEvents; +using CloudNative.CloudEvents.Http; +using CloudNative.CloudEvents.SystemTextJson; + +var cloudEvent = new CloudEvent +{ + Id = Guid.NewGuid().ToString(), + Source = new Uri("https://example.com/orders"), + Type = "com.example.order.created", + DataContentType = "application/json", + Data = new { OrderId = 1234 } +}; + +var formatter = new JsonEventFormatter(); +var content = cloudEvent.ToHttpContent(ContentMode.Structured, formatter); +``` + +For more examples, see [Samples](https://github.com/cloudevents/sdk-csharp/tree/main/samples). + +## Additional Documentation + +- [Main docs](https://github.com/cloudevents/sdk-csharp/tree/main/docs) +- [CloudEvents Event Format specification](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#event-format) +- [CloudEvents HTTP Protocol Binding specification](https://github.com/cloudevents/spec/blob/ce@stable/cloudevents/bindings/http-protocol-binding.md) +- [User guide](https://github.com/cloudevents/sdk-csharp/blob/main/docs/guide.md) diff --git a/src/Directory.Build.props b/src/Directory.Build.props index e093cefd..18482a78 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -42,11 +42,13 @@ Apache-2.0 https://cloudevents.io Copyright Cloud Native Foundation + PACKAGE.md - + +