Many aspects of the SDK have changed since the 1.x versions. Users adopting 2.x should expect to rewrite some code and retest thoroughly when migrating from 1.x.
The following sections are not exhaustive, but describe the most important changes.
The CloudEvent type constructor now only accepts the spec version
and initial extension attributes (with no values). Everything else
(type, ID, timestamp etc) must be set via properties or indexers.
(In particular, the timestamp and ID are no longer populated
automatically.) The spec version for an event is immutable once
constructed; everything else can be modified after construction.
The types used to specify attribute values must match the
corresponding attribute type exactly; there is no implicit
conversion available. For example, cloudEvent["source"] = "https://cloudevents.io"; will fail because the source attribute
is expected to be a URI.
The following are now fully-abstracted concepts, rather than implicitly using more primitive types:
- Spec version (
CloudEventSpecVersion) - Attributes (
CloudEventAttribute) - Attribute types (
CloudEventAttributeType)
The 1.x CloudEventAttributes class has now been removed, however -
the attributes are contained directly in a map within CloudEvent.
Timestamp attributes are now represented by DateTimeOffset instead
of DateTime, as this provides a more specific "timestamp" concept
with fewer ambiguities.
Extension attributes are no longer expected to implement an
interface (the old ICloudEventExtension). Instead,
CloudEventAttribute is used to represent all kinds of attribute,
and extensions are encouraged to be provided using C# extension
methods and static properties. See the user
guide for more details.
The distributed tracing extension attributes have been removed for now, while their long-term future is discussed in the broader CloudEvent ecosystem.
CloudEventFormatter is now an abstract base class (compared with
the 1.x interface ICloudEventFormatter). Attribute encoding is no
longer part of the responsibility of a CloudEventFormatter, but
binary data encoding (and batch encoding where supported) are part
of the event formatter.
The core package no longer contains any event formatters; the
Json.NET-based event formatter is now in a separate package
(CloudNative.CloudEvents.NewtonsoftJson) to avoid an unnecessary
dependency. An alternative implementation based on System.Text.Json
is now available in the CloudNative.CloudEvents.SystemTextJson
package.
Event formatters no longer supports streams for data, but are expected to handle strings and byte arrays, as well as supporting any formatter-specific types (e.g. JSON objects for JSON formatters). While each event formatter is still able to determine its own approach to serialization (meaning that formatters aren't really interchangable), the data responsiblities are more clearly documented, and each formatter should provide details of its serialization and deserialization algorithm.
Protocol bindings now typically require a CloudEventFormatter for
all serialization and deserialization operations, as there's no
built-in formatter to use by default. (This sounds inconvenient, but
does make the dependency on a specific event format explicit.)
The method names have been made consistent as far as possible. See the protocol bindings implementation guide for details.