From 91ff29512b2ef7a65bac23c6b6a7e9ceac3769b9 Mon Sep 17 00:00:00 2001 From: clemensv Date: Wed, 15 Jan 2020 11:12:03 +0100 Subject: [PATCH] Documentation fixes Signed-off-by: clemensv --- README.md | 10 ++++++++++ samples/HttpSend/Program.cs | 5 +++++ 2 files changed, 15 insertions(+) diff --git a/README.md b/README.md index fa3d645..3fe59a9 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,16 @@ The `CloudNative.CloudEvents` package provides utility methods and classes for creating, encoding, decoding, sending, and receiving [CNCF CloudEvents](https://github.com/cloudevents/spec). +## A few gotchas highlighted for the impatient who don't usually read docs + +1. The [CloudEvent](src/CloudNative.CloudEvents/CloudEvent.cs) class is not meant to be used with + object serializers like JSON.NET and does not have a default constructor to underline this. If you need to serialize or deserialize a CloudEvent directly, always use an [ICloudEventFormatter](src/CloudNative.CloudEvents/ICloudEventFormatter.cs) like the [JsonEventFormatter](src/CloudNative.CloudEvents/JsonEventFormatter.cs). +2. The transport integration is provided in the form of extensions and the objective of those extensions + is to map the CloudEvent to and from the respective protocol message, like an [HTTP request](src/CloudNative.CloudEvents/CloudEventContent.cs) or [response](src/CloudNative.CloudEvents/HttpClientExtension.cs#L249) + object, but the application is otherwise fully in control of the client. Therefore, the extensions do not + add security headers or credentials or any other headers or properties that may be required to interact + with a particular product or service. Adding this information is up to the application. + ## CloudEvent The `CloudEvent` class reflects the event envelope defined by the diff --git a/samples/HttpSend/Program.cs b/samples/HttpSend/Program.cs index 4bb8a93..96910ec 100644 --- a/samples/HttpSend/Program.cs +++ b/samples/HttpSend/Program.cs @@ -13,6 +13,8 @@ namespace HttpSend using McMaster.Extensions.CommandLineUtils; using Newtonsoft.Json; + // This application uses the McMaster.Extensions.CommandLineUtils library for parsing the command + // line and calling the application code. The [Option] attributes designate the parameters. class Program { [Option(Description = "CloudEvents 'source' (default: urn:example-com:mysource:abc)", LongName = "source", @@ -38,6 +40,9 @@ namespace HttpSend var content = new CloudEventContent(cloudEvent, ContentMode.Structured, new JsonEventFormatter()); var httpClient = new HttpClient(); + // your application remains in charge of adding any further headers or + // other information required to authenticate/authorize or otherwise + // dispatch the call at the server. var result = (await httpClient.PostAsync(this.Url, content)); Console.WriteLine(result.StatusCode);