diff --git a/docs/guide.md b/docs/guide.md
index dcae258..cd361d8 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 0000000..b0a56c5
--- /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 0000000..f247976
--- /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 0000000..3902607
--- /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 0000000..5001af0
--- /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 0000000..ef0358c
--- /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 0000000..6871130
--- /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 0000000..1358d00
--- /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 0000000..9d61a2e
--- /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 0000000..613af6e
--- /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 e093cef..18482a7 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
-
+
+