FractalDataWorks.Messages 0.4.0-preview.6

FractalDataWorks.Messages

Structured, type-safe messaging for the FractalDataWorks framework.

Overview

The Messages package provides message types for structured result information in GenericResult<T> operations. Messages are not for logging - they are for communicating operation outcomes with severity, codes, and source information.

Target Framework: netstandard2.0

Key Components

IGenericMessage Interface

The core interface that all framework messages implement. Defined in FractalDataWorks.Abstractions/IGenericMessage.cs.

From IGenericMessage.cs:8-27:

public interface IGenericMessage
{
    /// <summary>
    /// Gets the message text.
    /// </summary>
    /// <value>The human-readable message text describing the condition or status.</value>
    string Message { get; }

    /// <summary>
    /// Gets the message code or identifier.
    /// </summary>
    /// <value>A unique identifier for this type of message, useful for programmatic handling.</value>
    string? Code { get; }

    /// <summary>
    /// Gets the source component or operation that generated the message.
    /// </summary>
    /// <value>The name or identifier of the source that generated this message.</value>
    string? Source { get; }
}

IGenericMessage<TSeverity> Interface

Generic interface for messages with strongly typed severity.

From IGenericMessage.cs:33-40:

public interface IGenericMessage<TSeverity> : IGenericMessage where TSeverity : Enum
{
    /// <summary>
    /// Gets the severity level of the message.
    /// </summary>
    /// <value>The severity level indicating the importance and impact of the message.</value>
    TSeverity Severity { get; }
}

MessageSeverity Enum

Defines the severity levels for framework messages.

From MessageSeverity.cs:6-32:

public enum MessageSeverity
{
    /// <summary>
    /// Debug-level messages for detailed diagnostic information.
    /// </summary>
    Debug = 0,

    /// <summary>
    /// Informational messages that provide context or status updates.
    /// </summary>
    Information = 1,

    /// <summary>
    /// Warning messages that indicate potential issues but don't prevent operation.
    /// </summary>
    Warning = 2,

    /// <summary>
    /// Error messages that indicate failures or critical problems.
    /// </summary>
    Error = 3,

    /// <summary>
    /// Critical messages that indicate system-level failures.
    /// </summary>
    Critical = 4
}

GenericMessage Class

Concrete implementation of IGenericMessage for general-purpose messaging.

From GenericMessage.cs:10-89:

public class GenericMessage : IGenericMessage, ITypeOption<int>
{

    /// <inheritdoc/>
    public MessageSeverity Severity { get; set; }

    /// <inheritdoc/>
    public string Message { get; set; } = string.Empty;

    /// <inheritdoc/>
    public string? Code { get; set; }

    /// <inheritdoc/>
    public string? Source { get; set; }

    /// <summary>
    /// Gets or sets the unique identifier for this message.
    /// </summary>
    public int Id { get; set; } = 1;

    object ITypeOption.Id => Id;

    /// <summary>
    /// Gets or sets the display name or string representation of this enum value.
    /// </summary>
    public string Name { get; set; } = "GenericMessage";

    /// <summary>
    /// Gets the category for this type option.
    /// </summary>
    public string Category => "Message";

    /// <summary>
    /// Gets or sets the timestamp when the message was created.
    /// </summary>
    public DateTime Timestamp { get; set; } = DateTime.UtcNow;

    /// <summary>
    /// Gets or sets the correlation identifier for related messages.
    /// </summary>
    public Guid CorrelationId { get; set; } = Guid.NewGuid();

    /// <summary>
    /// Gets or sets additional metadata for the message.
    /// </summary>
    public IDictionary<string, object> Metadata { get; set; } = new Dictionary<string, object>(StringComparer.Ordinal);

    /// <summary>
    /// Initializes a new instance of the <see cref="GenericMessage"/> class.
    /// </summary>
    public GenericMessage()
    {
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="GenericMessage"/> class with a message.
    /// </summary>
    /// <param name="message">The message text.</param>
    public GenericMessage(string message)
    {
        Message = message ?? string.Empty;
        Severity = MessageSeverity.Information;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="GenericMessage"/> class with full details.
    /// </summary>
    /// <param name="severity">The message severity.</param>
    /// <param name="message">The message text.</param>
    /// <param name="code">The message code.</param>
    /// <param name="source">The message source.</param>
    public GenericMessage(MessageSeverity severity, string message, string? code = null, string? source = null)
    {
        Severity = severity;
        Message = message ?? string.Empty;
        Code = code;
        Source = source;
    }

}

MessageTemplate<TSeverity> Abstract Class

Base class for framework messages with formatting and metadata capabilities.

From MessageTemplate.cs:12-14:

public abstract class MessageTemplate<TSeverity> : IMessageIdentifier, IGenericMessage<TSeverity>, ITypeOption<int>
where TSeverity : Enum

Key properties from MessageTemplate.cs:19-79:

public int Id { get; }
public string Name { get; }
public string Category => "Message";
public TSeverity Severity { get; }
public string OriginatedIn { get; }
public string Message { get; }
public string? Code { get; }
public string? Source { get; }
public DateTime Timestamp { get; }
public IDictionary<string, object?>? Details { get; }
public object? Data { get; }

Key methods from MessageTemplate.cs:134-152:

public virtual string Format(params object[] args)
{
    if (args?.Length > 0)
    {
        return string.Format(CultureInfo.InvariantCulture, Message, args);
    }
    return Message;
}

public virtual MessageTemplate<TSeverity> WithSeverity(TSeverity severity)
{
    // Default implementation - subclasses can override if they need different behavior
    throw new NotSupportedException($"WithSeverity is not supported for {GetType().Name}. Override this method if severity changes are needed.");
}

MessageCollectionBase<T>

Base class for message collections that provides lookup functionality.

From MessageCollectionBase.cs:23-24:

public abstract class MessageCollectionBase<T> where T : class, IGenericMessage, ITypeOption<int>

Key methods from MessageCollectionBase.cs:99-162:

public static ImmutableArray<T> All() => _all;
public static T Empty() => _empty;
public static T? GetByName(string? name)
public static T? GetById(int id)
public static bool TryGetByName(string? name, out T? value)
public static bool TryGetById(int id, out T? value)
public static IEnumerable<T> AsEnumerable() => _all;
public static int Count => _all.Length;
public static bool Any() => _all.Length > 0;
public static T GetByIndex(int index) => _all[index];

Attributes

MessageAttribute

Marks message classes for collection generation.

From MessageAttribute.cs:10-64:

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
public sealed class MessageAttribute : Attribute
{
    public string? CollectionName { get; set; }
    public string? Name { get; set; }
    public Type? ReturnType { get; set; }
    public string? ReturnTypeNamespace { get; set; }
    public bool IncludeInGlobalCollection { get; set; } = true;
}

MessageCollectionAttribute

Marks a class as a message collection base type.

From Attributes/MessageCollectionAttribute.cs:10-38:

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
public sealed class MessageCollectionAttribute : Attribute
{
    public MessageCollectionAttribute(string name)
    public string Name { get; }
    public Type ReturnType { get; set; }
}

GlobalMessageCollectionAttribute

Marks a message collection for global cross-assembly discovery.

From Attributes/GlobalMessageCollectionAttribute.cs:16-44:

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
[ExcludeFromCodeCoverage]
public sealed class GlobalMessageCollectionAttribute : Attribute
{
    public GlobalMessageCollectionAttribute(string name)
    public string Name { get; }
    public Type ReturnType { get; set; }
}

MessageOptionAttribute

Marks a class as belonging to a specific message collection.

From Attributes/MessageOptionAttribute.cs:9-26:

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
public sealed class MessageOptionAttribute : Attribute
{
    public MessageOptionAttribute(Type collectionType)
    public Type CollectionType { get; }
}

Built-in Message Types

The package includes several pre-defined message types.

ErrorMessage

From ErrorMessage.cs:14-35:

[Message("StandardMessages")]
[MessageOption(typeof(MessageCollectionBase<GenericMessage>))]
[ExcludeFromCodeCoverage]
public sealed class ErrorMessage : MessageTemplate<MessageSeverity>
{
    public ErrorMessage(string errorDescription)
        : base(
            id: 1003,
            name: "Error",
            severity: MessageSeverity.Error,
            message: errorDescription,
            code: "ERROR",
            source: "General")
    {
        ErrorDescription = errorDescription;
    }

    public string ErrorDescription { get; }
}

ValidationMessage

From ValidationMessage.cs:14-35:

[Message("StandardMessages")]
[MessageOption(typeof(MessageCollectionBase<GenericMessage>))]
[ExcludeFromCodeCoverage]
public sealed class ValidationMessage : MessageTemplate<MessageSeverity>
{
    public ValidationMessage(string validationError)
        : base(
            id: 1004,
            name: "Validation",
            severity: MessageSeverity.Error,
            message: validationError,
            code: "VALIDATION",
            source: "Validation")
    {
        ValidationError = validationError;
    }

    public string ValidationError { get; }
}

Best Practices

Message Design

• Write messages that help users understand what happened and what to do
• Use standard .NET format strings for the Format() method
• Choose severity levels that match the actual impact
• Use meaningful, unique codes for programmatic handling

Usage Guidelines

• Messages are for GenericResult<T> operations, not for logging
• Prefer immutable message instances where possible
• Use the Details dictionary and Data property for structured additional information
• All MessageTemplate instances include automatic UTC timestamp creation

Code Coverage Exclusions

The following code is excluded from coverage testing:

Attributes (Configuration Only)

• GlobalMessageCollectionAttribute - Marked with [ExcludeFromCodeCoverage]
• Constructor parameter validation in attributes (infrastructure code)

Generated Code

• Source generator output files
• Auto-generated assembly info files

Infrastructure Code

• Internal initialization methods in MessageCollectionBase<T>
• Dictionary initialization for lookups

Dependencies

• FractalDataWorks.Abstractions: Core interfaces including IGenericMessage
• System.Collections.Immutable: For collection storage
• Microsoft.Bcl.HashCode: For hash code generation on netstandard2.0

Integration

Messages integrate with other FractalDataWorks components:

• Results: Used in GenericResult<T> for structured error/success information
• Services: Service operations return messages for validation failures and errors
• TypeCollections: Message collections use the TypeOption pattern for discovery
• Source Generation: Compile-time code generation for collections