84 lines
3.5 KiB
Markdown
84 lines
3.5 KiB
Markdown
# Changes since version 1.x
|
|
|
|
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.
|
|
|
|
## Core package
|
|
|
|
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](guide.md#extension-attributes) 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.
|
|
|
|
## Event formatters
|
|
|
|
`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
|
|
|
|
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](bindings.md) for
|
|
details.
|