Introduce minimal PACKAGE.md files for each package

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

src/Directory.Build.props

@@ -42,11 +42,13 @@
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
     <PackageProjectUrl>https://cloudevents.io</PackageProjectUrl>
     <Copyright>Copyright Cloud Native Foundation</Copyright>
+    <PackageReadmeFile Condition="Exists('$(MSBuildProjectDirectory)\PACKAGE.md')">PACKAGE.md</PackageReadmeFile>
   </PropertyGroup>
 
-  <!-- Package the icon specified in the PackageIcon property -->
+  <!-- Package shared NuGet assets. -->
   <ItemGroup>
     <None Include="$(RepoRoot)\nuget-icon.png" Pack="true" PackagePath=""/>
+    <None Include="$(MSBuildProjectDirectory)\PACKAGE.md" Pack="true" PackagePath="" Link="PACKAGE.md" Condition="Exists('$(MSBuildProjectDirectory)\PACKAGE.md')" />
   </ItemGroup>
 
 </Project>