FractalDataWorks.Messages 0.1.4-alpha-gbae2e75cc2

FractalDataWorks.Messages

A powerful message management system built on top of FractalDataWorks.EnhancedEnums that provides type-safe, domain-specific message collections with cross-assembly scanning support.

Features

• 🔒 Type-safe message collections - Domain-specific interfaces for compile-time safety
• 🔍 Cross-assembly scanning - Aggregate messages from all referenced assemblies
• 📊 Severity levels - Built-in support for Debug, Information, Warning, Error, and Critical
• 🎯 Message formatting - Template-based messages with parameter support
• 🔄 Immutable messages - Thread-safe singleton instances
• 🎨 Domain separation - Organize messages by functional area
• ⚡ High performance - Leverages EnhancedEnums' optimized collections

Installation

dotnet add package FractalDataWorks.Messages

Quick Start

1. Define Domain-Specific Messages

using FractalDataWorks.Messages;
using FractalDataWorks.EnhancedEnums.Attributes;

// Define a domain-specific interface
public interface IConnectionMessage : IFdwMessage { }

// Create a base class for your domain
[EnhancedEnumBase("ConnectionMessages", ReturnType = "IConnectionMessage")]
public abstract class ConnectionMessageBase : MessageBase<IConnectionMessage>, IConnectionMessage
{
    protected ConnectionMessageBase(string code, string message, MessageSeverity severity)
        : base(code, message, severity) { }
}

// Define concrete messages
[EnumOption]
public class ConnectionTimeout : ConnectionMessageBase
{
    public ConnectionTimeout() 
        : base("CONN_001", "Connection timeout after {0} seconds", MessageSeverity.Error) { }
}

[EnumOption]
public class ConnectionEstablished : ConnectionMessageBase
{
    public ConnectionEstablished() 
        : base("CONN_002", "Connection established to {0}", MessageSeverity.Information) { }
}

2. Use Messages in Your Code

// Access messages through generated static collections
var timeoutMsg = ConnectionMessages.ConnectionTimeout;
Console.WriteLine(timeoutMsg); // Output: [CONN_001] Connection timeout after {0} seconds

// Format messages with parameters
var formatted = timeoutMsg.Format(30);
Console.WriteLine(formatted); // Output: Connection timeout after 30 seconds

// Modify severity
var critical = timeoutMsg.WithSeverity(MessageSeverity.Critical);

// Look up messages by code
var found = ConnectionMessages.GetByName("CONN_001");

3. Create Cross-Assembly Message Collections

// Enable assembly scanning in AssemblyInfo.cs
[assembly: EnableAssemblyScanner]

// Create an app-wide message collection
[EnhancedEnumBase("AppMessages", 
    IncludeReferencedAssemblies = true, 
    ReturnType = "IFdwMessage")]
public abstract class AppMessageBase : MessageBase<IFdwMessage>
{
    protected AppMessageBase(string code, string message, MessageSeverity severity)
        : base(code, message, severity) { }
}

// Now AppMessages will contain ALL messages from all referenced assemblies
var allMessages = AppMessages.All;
var anyMessage = AppMessages.GetByName("CONN_001"); // Works across all domains

Core Concepts

MessageBase<T> Generic Pattern

The MessageBase<T> class uses a generic parameter to specify the return type for static collections:

// Domain-specific collection returning IConnectionMessage
[EnhancedEnumBase("ConnectionMessages", ReturnType = "IConnectionMessage")]
public abstract class ConnectionMessageBase : MessageBase<IConnectionMessage>, IConnectionMessage

// App-wide collection returning IFdwMessage
[EnhancedEnumBase("AppMessages", ReturnType = "IFdwMessage")]
public abstract class AppMessageBase : MessageBase<IFdwMessage>

Message Equality

Messages are considered equal if they have the same Code, regardless of:

• Their domain type
• Their severity level
• Their concrete class

IFdwMessage msg1 = ConnectionMessages.ConnectionTimeout;
IFdwMessage msg2 = ConnectionMessages.ConnectionTimeout.WithSeverity(MessageSeverity.Warning);
Console.WriteLine(msg1.Equals(msg2)); // True - same code

IConnectionMessage connMsg = ConnectionMessages.ConnectionTimeout;
IServiceMessage svcMsg = ServiceMessages.ServiceStarted;
Console.WriteLine(connMsg.Equals(svcMsg)); // False - different codes

Message Codes Convention

Recommended code format: PREFIX_NUMBER

• Use consistent prefixes per domain (e.g., CONN_, AUTH_, DATA_)
• Use sequential numbers (e.g., 001, 002, 003)
• Keep codes uppercase for consistency

Message Templates

Use numbered placeholders for parameters:

"Connection to {0} failed after {1} attempts"
"User {0} logged in from {1}"
"Processing {0} of {1} items"

Advanced Features

Custom Lookup Properties

Add custom lookup methods using [EnumLookup]:

[EnhancedEnumBase("ErrorMessages")]
public abstract class ErrorMessageBase : MessageBase<IFdwMessage>
{
    [EnumLookup]
    public abstract int ErrorCode { get; }
    
    [EnumLookup]
    public abstract string Category { get; }
}

// Generated methods:
var msg = ErrorMessages.GetByErrorCode(404);
var msgs = ErrorMessages.GetByCategory("Validation");

Integration with FdwResult

Messages integrate seamlessly with FdwResult for error handling:

public FdwResult<User> GetUser(int id)
{
    var user = _repository.FindById(id);
    if (user == null)
        return FdwResult<User>.Failure(UserMessages.UserNotFound.Format(id));
    
    return FdwResult<User>.Success(user);
}

Thread Safety

All message instances are immutable singletons, making them thread-safe by design:

// Safe to access from multiple threads
var msg = ConnectionMessages.ConnectionTimeout;

// WithSeverity creates a new instance
var warning = msg.WithSeverity(MessageSeverity.Warning);

Best Practices

1. Organize by Domain: Create separate message classes for each functional area
2. Use Descriptive Names: Message class names should clearly indicate their purpose
3. Consistent Codes: Follow a naming convention for message codes
4. Meaningful Templates: Write clear, actionable message templates
5. Appropriate Severity: Choose severity levels that match the impact
6. Parameter Validation: Ensure Format() calls have the correct number of parameters
7. Document Messages: Add XML comments to message classes explaining when they're used

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │               AppMessages Collection                 │    │
│  │        (Cross-Assembly, Returns IFdwMessage)        │    │
│  └─────────────────────────────────────────────────────┘    │
│                           │                                  │
│  ┌──────────────┬────────┴────────┬──────────────┐         │
│  │ Connection   │    Service       │    Auth      │ ...     │
│  │  Messages    │    Messages      │  Messages    │         │
│  └──────────────┴─────────────────┴──────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Infrastructure Layer                      │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              MessageBase<T> Abstract Class           │    │
│  └─────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              IFdwMessage Interface                   │    │
│  └─────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │          FractalDataWorks.EnhancedEnums             │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Performance

The Messages library leverages EnhancedEnums' performance optimizations:

• Compile-time generation: All collections are generated at compile time
• Singleton instances: Messages are created once and reused
• Frozen dictionaries: .NET 8+ uses FrozenDictionary for lookups
• Immutable collections: Thread-safe without locking

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Related Projects

• FractalDataWorks.EnhancedEnums - The underlying enum pattern implementation
• FractalDataWorks - Core framework with FdwResult integration