Getting Started
Architecture
Service Platform
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Modernization
Shape the future
Samples

CloudEvents

Component: NServiceBus
NuGet Package: NServiceBus 10.x

This guideline explains how to configure NServiceBus endpoints to receive CloudEvents.

Supported formats

This section describes CloudEvents formats supported by NServiceBus.

JSON

NServiceBus supports the JSON format. The JSON Batch format is not supported.

Supported bindings

This section describes CloudEvents bindings supported by NServiceBus.

Structured Content Mode for HTTP and AMQP

NServiceBus supports HTTP Structured and AMQP Structured content modes. For each content mode, two implementations are provided:

  • Strict
  • Permissive

Strict mode

In Strict mode, the CloudEvents message Content-Type header must be equal to or contain application/cloudevents+json. The implementation will not attempt to deserialize the payload if the Content-Type header does not meet the requirements.

Fields id, source, type, and at least one of data or data_base64 must be present. The specversion is not required to be present or to equal to 1.0.

Permissive mode

In Permissive mode, the CloudEvents message type field must be present. The Content-Type header is not verified, and a payload deserialization attempt is always executed.

Binary Content Mode for HTTP and AMQP

NServiceBus supports the HTTP Binary and AMQP Binary content modes.

To recognize the CloudEvents message, the fields id, source, and type must be present. The specversion field is not required to be present or to equal to 1.0.

Field names must be encoded according to the binding specification (e.g. ce-id for the id field when using HTTP).

The implementation will not attempt to deserialize the payload if the headers do not meet the requirements.

The HTTP Content-Type and AMQP Content-Type headers are not validated.

Configuration

This section describes the configuration options.

Enabling CloudEvents

To enable the CloudEvents support:

Copy code|Copy usings|Edit
var cloudEventsConfiguration = endpointConfiguration.EnableCloudEvents();

Type mapping

TypeMappings configure how to match the incoming message content-type value with the class definition used in the NServiceBus message handler:

Copy code|Copy usings|Edit
cloudEventsConfiguration.TypeMappings["ObjectCreated:Put"] = [typeof(AwsBlobNotification)];

Enabled unwrappers

The EnvelopeUnwrappers property contains the list of enabled modes. By default, both Binary Content Mode and Structured Content Mode in Strict Mode are enabled.

To enable or disable unwrappers, modify the EnvelopeUnwrappers property by adding or removing unwrappers.

The following code snippet shows how to change the JSON Structured Content unwrapper from Strict to Permissive:

Copy code|Copy usings|Edit
cloudEventsConfiguration.EnvelopeUnwrappers.Find<CloudEventJsonStructuredEnvelopeUnwrapper>()?.EnvelopeHandlingMode = JsonStructureEnvelopeHandlingMode.Permissive;

Metrics and logging

The package provides metrics and logs insights into every stage of receiving a message.

When selecting an unwrapper for the message:

  • A warning message is logged when the unwrapper fails to unwrap the message.
  • A metric is emitted for every unwrapping attempt. The metric's value indicates whether the unwrapping succeeded or crashed. Keep in mind that, if the unwrapper recognizes that it can't unwrap the message (e.g. because the message lacks required fields), then it's considered a successful unwrapping.

Structured Content Mode in Strict Mode produces the following signals:

  • If the message has the correct content type header, a metric is emitted.
  • If, and only if, the message has the correct content type header, a metric is emitted and a warning message is logged if the message's body cannot be deserialized, or if the message doesn't have at least one required field.
  • If, and only if, the message has the correct content type header and all required fields, a metric is emitted and a warning message is logged if the version field contains an unexpected value, or if the version field is missing.

Structured Content Mode in Permissive Mode produces the following signals:

  • A metric is emitted to indicate that the unwrapper attempts to unwrap the message (i.e. for every message).
  • If, and only if, the message could be parsed, and the message contains the type field, a metric is emitted and a warning message is logged if the version field contains an unexpected value.

Binary Content Mode produces the following signals:

  • A metric is emitted if at least one of the required headers is absent.
  • A metric is emitted if the required headers are present.
  • If, and only if, the message has required headers, a metric is emitted and a warning message is logged if the version header contains an unexpected value, or if the version header is missing

Troubleshooting

To troubleshoot the mechanism, examine the metrics and logs to understand why messages are not unwrapped as CloudEvents. A non-exhaustive list of elements to check includes:

  • Is the mechanism enabled?
  • Are correct unwrappers registered?
  • Is the mode for Structured Content Mode messages configured correctly?
  • Is the JSON deserializer configured to handle lowercase/uppercase letters correctly?
  • Do the incoming messages have all required headers and fields? Pay special attention to lowercase/uppercase letters.
  • Is the type mapping configured correctly?

Samples

Feedback