Tooark.Notifications 4.7.1

Tooark.Notifications

Library for creating and managing notifications and alerts, easing communication and monitoring in .NET projects.

📖 Docs: Tooark.Notifications on the site · All packages · API reference

🌍 Languages: 🇺🇸 English (this file) · 🇧🇷 Português

📑 Contents

• Installation
• Classes
  • NotificationItem
  • Notification
  • NotificationErrorMessages
• Usage Examples
• Contributing
• Help & Security
• Support
• License

🔧 Installation

dotnet add package Tooark.Notifications

The package has no configuration. Notification is used through inheritance, in classes that accumulate the result of several checks — such as the Tooark value objects and entities —, and the mutators are protected: the object itself accumulates the notification, not whoever consumes it.

Messages are stored as a key, not as final text. Translation is done by the layer that builds the response, such as the ResponseDto of Tooark.Dtos.

🧱 Classes

The available classes are:

1. Notification Item

Purpose: Represents the structure of a notification item with message, key and error code. The values are normalized on construction and the instance is read-only.

Properties:

• Message: The notification message.
• Key: The notification key.
• Code: The notification error code.

Methods:

• NotificationItem(string? message): Creates a new instance with the Unknown key and the T.ERR code.
• NotificationItem(string? message, string? key): Creates a new instance with the given key and the T.ERR code.
• NotificationItem(string? message, string? key, string? code): Creates a new instance with the given key and code.

The three parameters accept a missing value because the constructor already handled it: a blank message becomes Notifications.MessageNullEmpty, a blank key becomes Unknown and a blank code becomes T.ERR. The signature declared non-nullable while the body checked for null — whoever passed a string? got a compiler warning for a path that always worked.

• ToString(): Returns the notification message.
• string: Implicitly converts a NotificationItem instance to a string, returning the message. A null instance returns an empty string.
• NotificationItem: Implicitly converts a string to a NotificationItem instance, with the Unknown key and the T.ERR code.

Value normalization:

Usage Example

2. Notification

Purpose: Abstract class that manages the notification list of the object inheriting it. It is the base of ValueObject, BaseEntity and Validation.

Creating and clearing notifications is protected: only the object itself decides what it notifies. Aggregating existing notifications is public, allowing the validation result of other objects to be composed.

Properties:

• Notifications: Returns the read-only list of notifications.
• IsValid: Returns true if the notification list is empty.
• Count: Returns the number of notifications.
• Codes: Returns the list of error codes of the notifications.
• Keys: Returns the list of keys of the notifications.
• Messages: Returns the list of messages of the notifications.

Public methods:

• AddNotifications(Notification notification): Adds the notifications of another notification to the notification list.
• AddNotifications(params Notification[] notifications): Adds the notifications of a collection of notifications to the notification list.

Protected methods:

• AddNotification(NotificationItem notification): Adds a notification item to the notification list.
• AddNotification(Type property, string message): Adds a notification item using the type name as key.
• AddNotification(Type property, string message, string code): Adds a notification item using the type name as key, with an error code.
• AddNotification(string message, string key): Adds a notification item with message and key.
• AddNotification(string message, string key, string code): Adds a notification item with message, key and error code.
• AddNotifications(ICollection<NotificationItem> notifications): Adds a collection of notification items to the notification list.
• Clear(): Clears the notification list.

Null handling:

Usage Example

3. Error Messages

Purpose: Static class NotificationErrorMessages with the messages generated by the library itself. They are translation keys, not final texts.

📝 Usage Examples

Notification Item

// Message, with the 'Unknown' key and the 'T.ERR' code
var notification1 = new NotificationItem("Example message");

// Message and key, with the 'T.ERR' code
var notification2 = new NotificationItem("Example message", "ExampleKey");

// Message, key and code
var notification3 = new NotificationItem("Example message", "ExampleKey", "XPTO1");

// The key has its whitespace removed
var notification4 = new NotificationItem("Example message", "Example Key");
var key = notification4.Key; // "ExampleKey"

Notification

// Adding notifications is protected: only the object itself notifies its errors
public class MyNotification : Notification
{
  public void NotifyError(string message)
  {
    AddNotification(message, "Error", "XPTO1");
  }
}

var myNotification = new MyNotification();

myNotification.NotifyError("An error occurred.");

var isValid = myNotification.IsValid; // False
var count = myNotification.Count; // 1
var codes = myNotification.Codes; // ["XPTO1"]
var keys = myNotification.Keys; // ["Error"]
var messages = myNotification.Messages; // ["An error occurred."]
var notifications = myNotification.Notifications; // [NotificationItem { Message = "An error occurred.", Key = "Error", Code = "XPTO1" }]

// Aggregation is public: existing notifications can be composed from outside the object
public class MyValidation : Notification
{ }

var validation = new MyValidation();

validation.AddNotifications(myNotification, myOtherNotification);

🤝 Contributing

Contributions are welcome! Start with CONTRIBUTING.md — it covers the development workflow, the coding and commit conventions and the pull request checklist. Bugs and feature requests go through the issue templates of the Tooark repository.

By participating you agree to the Code of Conduct.

🆘 Help & Security

• ❓ Questions, bugs, feature ideas — see SUPPORT.md for the right channel
• 🔒 Security vulnerabilities — do not open a public issue; follow SECURITY.md

💖 Support

If Tooark helps your projects, consider supporting its development:

• 💙 GitHub Sponsors
• ☕ Ko-fi

Every contribution helps keep the project maintained and improving. Thank you! 🙏

📄 License

This project is licensed under the BSD 3-Clause License.