IMessageDescriptions

IMessageDescriptions is a store of message descriptions with lookup tables.

/// <summary>Table of <see cref="IMessageDescriptions"/>.</summary>
public interface IMessageDescriptions : IReadOnly
{
    /// <summary>Message descriptions by key</summary>
    IDictionary<string, IMessageDescription> Keys { get; set; }
    /// <summary>Message descriptions by hresult</summary>
    IDictionary<int, List<IMessageDescription>> HResults { get; set; }
    /// <summary>Message descriptions by code</summary>
    IDictionary<int, IMessageDescription> Codes { get; set; }
    /// <summary>Message descriptions as list</summary>
    IList<IMessageDescription> List { get; set; }

    /// <summary>Add <paramref name="messageDescription"/>.</summary>
    /// <exception cref="InvalidOperationException">On key or code collision.</exception>
    void Add(IMessageDescription messageDescription);
}

MessageDescriptions stores message descriptions. Each added message is added to lookup tables.

IMessageDescriptions store = new MessageDescriptions()
    .Add(LibraryMessagesTable.Instance.GoodResult)
    .SetReadOnly();

WriteLine(store.Keys["Library.GoodResult"]); // "'MyObject' Ok result"

Store can be initialized by overriding .Initialize().

/// <summary></summary>
public class LibraryMessages : MessageDescriptions
{
    /// <summary>Base id for datatype codes.</summary>
    public const int BaseCode = 0x20A10000;
    /// <summary>Singleton</summary>
    static Lazy<LibraryMessages> instance = new Lazy<LibraryMessages>(() => new LibraryMessages().Initialize().SetAllReadOnly<LibraryMessages>().SetReadOnly());
    /// <summary>Singleton</summary>
    public static LibraryMessages Instance => instance.Value;

    /// <summary>Message description fields</summary>
    IMessageDescription badUnexpected = null!, badArgumentNull = null!, goodResult = null!;

    /// <summary>Initialize fields</summary>
    public override LibraryMessages Initialize()
    {
        // Create descriptions
        set(0xA0A10001, ref badUnexpected, "'{object}': Unexpected error");
        set(0xA0A10002, ref badArgumentNull, "'{object}': Unexpected error");
        set(0x20A10003, ref goodResult, "'{object}': Unexpected error");
        // Return 
        return this;
    }

    /// <summary>Create description</summary>
    void set(long id, ref IMessageDescription messageDescription, string templateText, [CallerArgumentExpression("messageDescription")] string key = null!)
        => Add(messageDescription = new MessageDescription($"Library.{char.ToUpper(key[0])}{key.Substring(1)}", id, templateText).SetHResult(id));

    /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
    public IMessageDescription BadUnexpected { get => badUnexpected; set => this.AssertWritable().badUnexpected = value; }
    /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
    public IMessageDescription BadArgumentNull { get => badArgumentNull; set => this.AssertWritable().badArgumentNull = value; }
    /// <summary>Good result.</summary>
    public IMessageDescription GoodResult { get => goodResult; set => this.AssertWritable().goodResult = value; }
}

MessageDescriptionsTable is base class for tables where message descriptions are read with reflection either from fields and properties.

/// <summary></summary>
public class LibraryMessagesTable : MessageDescriptionsTable
{
    /// <summary>Base id for datatype codes.</summary>
    public const int BaseCode = 0x20A10000;
    /// <summary>Singleton</summary>
    static Lazy<LibraryMessagesTable> instance = new Lazy<LibraryMessagesTable>(() => new LibraryMessagesTable().ReadSummaryXmls().SetAllReadOnly<LibraryMessagesTable>().SetReadOnly());
    /// <summary>Singleton</summary>
    public static LibraryMessagesTable Instance => instance.Value;

    /// <summary>Message description fields</summary>
    IMessageDescription badUnexpected = Create(0xA0A10001, nameof(badUnexpected), "'{object}': Unexpected error");
    IMessageDescription badArgumentNull = Create(0xA0A10002, nameof(badArgumentNull), "'{object}': Bad argument 'null'");
    IMessageDescription goodResult = Create(0x20A10003, nameof(goodResult), "'{object}': Ok result");

    /// <summary>Create description</summary>
    static IMessageDescription Create(long id, string key, string templateText)
        => new MessageDescription($"Library.{char.ToUpper(key[0])}{key.Substring(1)}", id, templateText).SetHResult(id);

    /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
    public IMessageDescription BadUnexpected { get => badUnexpected; set => this.AssertWritable().badUnexpected = value; }
    /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
    public IMessageDescription BadArgumentNull { get => badArgumentNull; set => this.AssertWritable().badArgumentNull = value; }
    /// <summary>Good result.</summary>
    public IMessageDescription GoodResult { get => goodResult; set => this.AssertWritable().goodResult = value; }
}

.ReadSummaryXmls() in initialization in the example above reads <summary> comments from assembly. Note, that this requires that the .csproj has following property.

    <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
        <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
    </PropertyGroup>

Messages are available from singleton.

// Print key
WriteLine(LibraryMessagesTable.Instance.GoodResult); // "Library.GoodResult"

// Create message
IMessage message = LibraryMessagesTable.Instance.GoodResult.New("MyObject");
// Print message
WriteLine(message); // "'MyObject' Ok result"

.List contains all message descriptions.

foreach (IMessageDescription code in LibraryMessagesTable.Instance.List) WriteLine(code);
// MessageDescription(Code = A0A10001, Key = Library.BadUnexpected, HResult = A0A10001, Severity =, Template = "'{object}': Unexpected error", "Captured unexpected <see cref="T: System.Exception" />.")
// MessageDescription(Code = A0A10002, Key = Library.BadArgumentNull, HResult = A0A10002, Severity =, Template = "'{object}': Bad argument 'null'", "Captured unexpected <see cref="T: System.Exception" />.")
// MessageDescription(Code = 20A10003, Key = Library.GoodResult, HResult = 20A10003, Severity =, Template = "'{object}': Ok result", "Good result.")

.Codes contain code to message description mapping.

IMessageDescription statusCode = LibraryMessagesTable.Instance.Codes[0x20A10003];

.Keys contain key to message description mapping.

IMessageDescription statusCode = LibraryMessagesTable.Instance.Keys["Library.GoodResult"];

.HResults contain hresult to message description mapping.

IMessageDescription statusCodes = LibraryMessagesTable.Instance.HResults[unchecked((int)0xA0A10002)].First();

Full Example

Full example

using System.Collections.Generic;
using Avalanche.Utilities;
using Avalanche.Message;
using static System.Console;
using System.Runtime.CompilerServices;


class messagedescriptions
{
    /// <summary>ABC</summary>
    public class Test<T>
    {
        /// <summary>DEF</summary>
        public Test<T> Do<K>() { return default!; }
    }


    public static void Run()
    {
        {
            // <01>
            // Print key
            WriteLine(LibraryMessagesTable.Instance.GoodResult); // "Library.GoodResult"

            // Create message
            IMessage message = LibraryMessagesTable.Instance.GoodResult.New("MyObject");
            // Print message
            WriteLine(message); // "'MyObject' Ok result"
            // </01>
        }
        {
            // <02>
            foreach (IMessageDescription code in LibraryMessagesTable.Instance.List) WriteLine(code);
            // MessageDescription(Code = A0A10001, Key = Library.BadUnexpected, HResult = A0A10001, Severity =, Template = "'{object}': Unexpected error", "Captured unexpected <see cref="T: System.Exception" />.")
            // MessageDescription(Code = A0A10002, Key = Library.BadArgumentNull, HResult = A0A10002, Severity =, Template = "'{object}': Bad argument 'null'", "Captured unexpected <see cref="T: System.Exception" />.")
            // MessageDescription(Code = 20A10003, Key = Library.GoodResult, HResult = 20A10003, Severity =, Template = "'{object}': Ok result", "Good result.")
            // </02>
        }
        {
            // <03>
            IMessageDescription statusCode = LibraryMessagesTable.Instance.Codes[0x20A10003];
            // </03>
            WriteLine(statusCode);
        }        
        {
            // <03B>
            IMessageDescription statusCode = LibraryMessages.Instance.Codes[0x20A10003];
            // </03B>
            WriteLine(statusCode);
        }
        {
            // <04>
            IMessageDescription statusCode = LibraryMessagesTable.Instance.Keys["Library.GoodResult"];
            // </04>
            WriteLine(statusCode);
        }
        {
            // <05>
            IMessageDescription statusCodes = LibraryMessagesTable.Instance.HResults[unchecked((int)0xA0A10002)].First();
            // </05>
            WriteLine(statusCodes);
        }
        {
            // <10>
            IMessageDescriptions store = new MessageDescriptions()
                .Add(LibraryMessagesTable.Instance.GoodResult)
                .SetReadOnly();

            WriteLine(store.Keys["Library.GoodResult"]); // "'MyObject' Ok result"
            // </10>
        }
    }

    // <98>
    /// <summary></summary>
    public class LibraryMessages : MessageDescriptions
    {
        /// <summary>Base id for datatype codes.</summary>
        public const int BaseCode = 0x20A10000;
        /// <summary>Singleton</summary>
        static Lazy<LibraryMessages> instance = new Lazy<LibraryMessages>(() => new LibraryMessages().Initialize().SetAllReadOnly<LibraryMessages>().SetReadOnly());
        /// <summary>Singleton</summary>
        public static LibraryMessages Instance => instance.Value;

        /// <summary>Message description fields</summary>
        IMessageDescription badUnexpected = null!, badArgumentNull = null!, goodResult = null!;

        /// <summary>Initialize fields</summary>
        public override LibraryMessages Initialize()
        {
            // Create descriptions
            set(0xA0A10001, ref badUnexpected, "'{object}': Unexpected error");
            set(0xA0A10002, ref badArgumentNull, "'{object}': Unexpected error");
            set(0x20A10003, ref goodResult, "'{object}': Unexpected error");
            // Return 
            return this;
        }

        /// <summary>Create description</summary>
        void set(long id, ref IMessageDescription messageDescription, string templateText, [CallerArgumentExpression("messageDescription")] string key = null!)
            => Add(messageDescription = new MessageDescription($"Library.{char.ToUpper(key[0])}{key.Substring(1)}", id, templateText).SetHResult(id));

        /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
        public IMessageDescription BadUnexpected { get => badUnexpected; set => this.AssertWritable().badUnexpected = value; }
        /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
        public IMessageDescription BadArgumentNull { get => badArgumentNull; set => this.AssertWritable().badArgumentNull = value; }
        /// <summary>Good result.</summary>
        public IMessageDescription GoodResult { get => goodResult; set => this.AssertWritable().goodResult = value; }
    }
    // </98>
    
    // <99>
    /// <summary></summary>
    public class LibraryMessagesTable : MessageDescriptionsTable
    {
        /// <summary>Base id for datatype codes.</summary>
        public const int BaseCode = 0x20A10000;
        /// <summary>Singleton</summary>
        static Lazy<LibraryMessagesTable> instance = new Lazy<LibraryMessagesTable>(() => new LibraryMessagesTable().ReadSummaryXmls().SetAllReadOnly<LibraryMessagesTable>().SetReadOnly());
        /// <summary>Singleton</summary>
        public static LibraryMessagesTable Instance => instance.Value;

        /// <summary>Message description fields</summary>
        IMessageDescription badUnexpected = Create(0xA0A10001, nameof(badUnexpected), "'{object}': Unexpected error");
        IMessageDescription badArgumentNull = Create(0xA0A10002, nameof(badArgumentNull), "'{object}': Bad argument 'null'");
        IMessageDescription goodResult = Create(0x20A10003, nameof(goodResult), "'{object}': Ok result");

        /// <summary>Create description</summary>
        static IMessageDescription Create(long id, string key, string templateText)
            => new MessageDescription($"Library.{char.ToUpper(key[0])}{key.Substring(1)}", id, templateText).SetHResult(id);

        /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
        public IMessageDescription BadUnexpected { get => badUnexpected; set => this.AssertWritable().badUnexpected = value; }
        /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
        public IMessageDescription BadArgumentNull { get => badArgumentNull; set => this.AssertWritable().badArgumentNull = value; }
        /// <summary>Good result.</summary>
        public IMessageDescription GoodResult { get => goodResult; set => this.AssertWritable().goodResult = value; }
    }
    // </99>

}