NiceNotice 0.1.0

NiceNotice

NiceNotice is an abstraction layer for cross-application notifications.

NiceNotice is intended to help address the arrangement and coordination of the logical work required to dispatch typed/structured notifications of application events to an event bus, e.g., AWS Simple Notification Service (SNS), RabbitMQ.

Dispatching a typed notice is as simple as: await dispatcher.DispatchAsync(new UserSessionStarted { SessionId = signInResult.SessionId, UserId = signInResult.UserId }). (See How the ITypedNoticeDispatcher<TEnterpriseEventBaseType> works for details on how the dispatcher works.)

NiceNotice applies a structured approach to building an application/enterprise event notification dispatch system in .NET applications using four basic components:

• Routing
  • Routing answers the question "given an arbitrary event object, to what logical destination (i.e., stream) does it belong."
• Serialization
  • Serialization encodes the event notification object into a string in a manner consistent with the documented expectations of your application and the event bus. (Generally, this just means serialize the object to JSON.)
• Validation
  • Validation answers the question "is this event object and its serialized representation valid to send."
• Dispatch
  • Dispatch is the work to send the serialized notice to an external I/O (e.g., AWS SNS).

Requirements

Runtime Application Requirements

.NET Generic Host: NiceNotice is designed to be used in applications using the standard .NET Generic Host infrastructure (standard in ASP.NET Core applications; available to other applications using the Microsoft.Extensions.Hosting NuGet package).

Technically, NiceNotice only depends upon the IServiceCollection and IServiceProvider infrastructure, but most applications using cross-application event notifications will be using service resolution from the application Host.

External I/O Client: You'll need to install and configure your chosen messaging I/O client, e.g., AWS SDK for Simple Notification Service. Make sure that the applicable I/O dependencies for that library are registered in the Host ServiceCollection. E.g., if you're using AWS SNS then you must make sure IAmazonSimpleNotificationService is registered. (See Notice Dispatch for an explanation of how NiceNotice represents/adapts an I/O client.)

Getting Started

Start by installing the NiceNotice NuGet package.

Step 1: Create/Select your base/required event schema

This is a crucial decision point if your use case or organization depends upon a shared event schema. (E.g., if all notices need a timestamp or a deduplication id.)

In your application, declare a base "enterprise event" type. This is a value object which all typed notices are expected to extend.

ExampleCustomBaseEnterpriseEvent is defined in a NiceNotice unit test and provides an example of how you might define a "base" event for your project.

Event Schema Object Quick Start

NiceNotice provides a recommended base record: EnterpriseEvent. The EnterpriseEvent type exposes two important properties: timestamp, and id.

The timestamp allows messages to be ordered chronologically.

The id allows messages to be deduplicated; an essential component in resilient asynchronous workflows.

Simply add a record in your project extending EnterpriseEvent.

See this GameEvent example from NiceNotice unit tests, intended to support an application sending events related to a team sport.

public record MyApplicationEvent : EnterpriseEvent;

The above example base application event, MyApplicationEvent, inherits timestamp and id properties from EnterpriseEvent. When serialized using the default NiceNotice serializer, an instance of MyApplicationEvent would be emitted like the following:

{"timestamp":"2025-10-11T23:17:59.5603648+00:00","id":"9fd368e0-23e2-4ec2-a30a-6ef99c3c2841"}

Routing Considerations

By default, NiceNotice internally routes notices to an EventStreamId which matches the notification type name. (E.g., MyCompany.MyApplication.LoginEvent would be routed to a "stream" named LoginEvent)

When you create a new event type, you can optionally add a [NoticeStream("")] attribute to specify a custom stream name.

This is very helpful for "grouping" events. For example, you might want all user session events (e.g., login, logout, timeout) to route to the same logical stream, user-session. To do so you'd simply add [NoticeStream("user-session")] to the applicable events' type definitions. This works on up the object hierarchy tree, so by applying a [NoticeStream()] attribute to a base event type you can easily apply consistent routing to all event types derived from it.

Step 2: Configure NiceNotice in application service configuration

On your Host's IServiceCollection, use the .AddNiceNotice() extension method to add NiceNotice services.

See this example of how a console application might be configured.

See this example of how an ASP.NET Core application might be configured.

Example using the builder fluent API:

services
  .AddNiceNotice(builder => builder
    .UseTypedNotices<MyApplicationEvent>(
      tnBuilder => tnBuilder
        .SerializeToJson() // Optional; JSON is the default
        .RouteToTypeNameStreams() // Optional; by default, type names are used as the stream names
        .ValidateWithDataAnnotations(),
      ServiceLifetime.Scoped
    )
    .DispatchToSns( // Dispatch enterprise events to AWS SNS. Requires `NiceNotice.Aws.Sns` NuGet package.
      "sns:topics", // IConfiguration section key, unique to this application's configuration; contains NiceNotice SNS topic routing
      ServiceLifetime.Scoped
    )
  );

Example of using the configuration object API:

services
  .AddNiceNotice(builder => builder
    .UseTypedNotices<MyApplicationEvent>(
      new TypedNoticesBuilderOptions
      {
        RoutingType = TypedNoticesBuilderOptions.RoutingTypes.TypeFullName,
        SerializationType = TypedNoticesBuilderOptions.SerializationTypes.Json,
        ValidationType = TypedNoticesBuilderOptions.ValidationTypes.DataAttributes
      },
      ServiceLifetime.Scoped
    )
    .DispatchToSns( // Dispatch enterprise events to AWS SNS. Requires `NiceNotice.Aws.Sns` NuGet package.
      "sns:topics", // IConfiguration section key, unique to this application's configuration; contains NiceNotice SNS topic routing
      ServiceLifetime.Scoped
    )
  );

The examples above use the NiceNotice Amazon Web Services (AWS) Simple Notification Service (SNS) dispatch library, NiceNotice.Aws.Sns. In all examples, SNS notification dispatch was arranged to load runtime configuration from the configuration at key sns:topics. That specific value is not required. Use the actual path within your application's configuration which contains SNS topic routing details.

Refer to the NiceNotice.Aws.Sns documentation for more information.

Step 3: Start sending notices

There are 2 interfaces exposed by NiceNotice which you can use to dispatch typed events: ITypedNoticeDispatcher<TEnterpriseEventBaseType> (generic) ITypedNoticeDispatcher (non-generic).

Recommended ITypedNoticeDispatcher<TEnterpriseEventBaseType>

The ITypedNoticeDispatcher<TEnterpriseEventBaseType> interface is a central component in the overall strategy of sending typed notices (notifications with a known, serialized schema). Its main addition, over ITypedNoticeDispatcher (non-generic), is that it constrains types, to help ensure message consistency.

Example using the MyApplicationEvent base event, above:

# We're requesting a dispatcher using the base type we created
# and configured with `.UseTypedNotices<MyApplicationEvent>()`
public class MyService(ITypedNoticeDispatcher<MyApplicationEvent> dispatcher)
{
  public async Task SendImmediateNotice()
  {
    _ = await dispatcher.DispatchAsync(new ImportantNotice());
  }
  public record ImportantNotice : MyApplicationEvent;
}

ITypedNoticeDispatcher

The ITypedNoticeDispatcher encapsulates the idea of dispatching typed, serialized, validated notices. Its interface is very flexible, accepting notices of any object (required to be a serializable data transfer object).

Note: ITypedNoticeDispatcher<TEnterpriseEventBaseType> is recommended if your organization or project implements a standard structured notification schema. It encourages consistent event notifications.

Example using the MyApplicationEvent base event, above:

public class MyService(ITypedNoticeDispatcher dispatcher)
{
  public async Task SendImmediateNotice()
  {
    _ = await dispatcher.DispatchAsync(new ImportantNotice());
  }
  public record ImportantNotice : MyApplicationEvent;
}

Special Mention INoticeIo

An implementation of the INoticeIo interface is used to actually adapt the serialized events (emitted by the typed notice dispatcher) into the I/O requests needed for your application's chosen messaging infrastructure (e.g., AWS SNS). (See Notice Dispatch for an explanation of how NiceNotice represents/adapts an I/O client.)

NiceNotice does not include any I/O adapters in the core library. Two implementations of INoticeIo are provided:

• NullNoticeIo, the default implementation; notifications are not dispatched externally.
• CapturingNoticeIo, simply captures emitted notifications in memory; provided to support unit testing.

The NiceNotice.Aws.Sns nuget package offers a prebuilt adapter for Amazon Web Services Simple Notification Service.

For other destinations (enterprise event buses)…

Your application might require a custom INoticeIo implementation. Don't worry, it's a simple interface.

If your event bus supports batches, then instead implement INoticeBatchIo. (Otherwise batches of notices are sent by executing the single-notice process repeatedly.)

Check out the ExampleCustomDispatcher class in the NiceNotice unit tests for an example showing how the xUnit test output helper was adapted to be an I/O destination for tests. Or check out the SnsNoticeIo implementation in NiceNotice.Aws.Sns to see how AWS SNS is adapted.

Step 4: Add Notification Types as Needed

Once the base application event is established (e.g., the MyApplicationEvent in the example above), you'll add additional notice types as needed to represent the messages your application sends.

It is critical to remember that the notification objects are value objects which are ultimately serialized. Use [JsonPropertyName] and similar System.Text.Json attributes to refine the serialization of your notification types.

For example, the same application which defined MyApplicationEvent might want to dispatch notifications upon critical-level events. The application might define a CriticalFailureDetected event:

public record CriticalFailureDetected : MyApplicationEvent
{
  public required string ErrorId { get; init; } = string.Empty;
  public required string Message { get; init; } = string.Empty;
  public required string Details { get; init; } = string.Empty;
}

Such an event would serialize like:

{"errorId":"321.1","message":"Failed to communicate with the database for more than 90 seconds.","details":"Requests to database failed for configured time period (90 seconds). Considered unrecoverable.","timestamp":"2025-10-11T23:43:05.3421459+00:00","id":"16e15973-1e39-4347-a3dc-3de66af0a8bc"}