IMessageDescriptions

IMessageDescriptions is a store of message descriptions.

/// <summary>Table of <see cref="IMessageDescriptions"/>.</summary>
public interface IMessageDescriptions : IReadOnly
{
    /// <summary>Table name</summary>
    string? TableName { get; set; }
    /// <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 is the default implementation. .Add(messageDescription) adds to .List and to lookup tables Codes and Keys.

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

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

MessageDescriptions can be sub-classed. .ReadSummaryXmls() reads triple slash /// <summary> comments from assembly.

/// <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().ReadSummaryXmls().SetAllReadOnly().SetReadOnly());
    /// <summary>Singleton</summary>
    public static LibraryMessages Instance => instance.Value;

    /// <summary>Create messages</summary>
    public LibraryMessages() : base() { this.AddRange(MessageDescriptionsExtensions.FieldReader(this)); }

    /// <summary>Create description</summary>
    static IMessageDescription create(string key, long id, string templateText) => new MessageDescription($"Library.{key}", id, templateText).SetHResult(id);

    /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
    public readonly IMessageDescription BadUnexpected = create(nameof(BadUnexpected), 0xA0A10001, "'{object}': Unexpected error");
    /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
    public readonly IMessageDescription BadArgumentNull = create(nameof(BadArgumentNull), 0xA0A10002, "'{object}': Unexpected error");
    /// <summary>Good result.</summary>
    public readonly IMessageDescription GoodResult = create(nameof(GoodResult), 0x20A10003, "'{object}': Unexpected error");
}

Note, that .ReadSummaryXmls() 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);

// Prints:
//   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();

.ToMarkdownText() prints table as .md text.

WriteLine(LibraryMessagesTable.Instance.ToMarkdownText());

| Key                                                                             |StatusCode| Description                                                                 | Message Template                                                | Exception           |
|:--------------------------------------------------------------------------------|:---------|:----------------------------------------------------------------------------|:----------------------------------------------------------------|:--------------------|
| Library.BadUnexpected                                                           | A0A10001 | Captured unexpected <em>Exception</em>.                                     | '{object}': Unexpected error                                    |                     |
| Library.BadArgumentNull                                                         | A0A10002 | Captured unexpected <em>Exception</em>.                                     | '{object}': Bad argument 'null'                                 |                     |
| Library.GoodResult                                                              | 20A10003 | Good result.                                                                | '{object}': Ok result                                           |                     |

See Avalanche.StatusCode for message description tables.

Full Example

Full example

using System.Collections.Generic;
using Avalanche.Utilities;
using Avalanche.Message;
using static System.Console;
using System.Runtime.CompilerServices;
using static messagedescriptions;
using Avalanche.Localization;
using System.Globalization;
using Avalanche.Service.Support;

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);

            // Prints:
            //   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>
        }
        {
            // <20>
            WriteLine(LibraryMessagesTable.Instance.ToMarkdownText());
            // </20>
        }
    }

    // <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().ReadSummaryXmls().SetAllReadOnly().SetReadOnly());
        /// <summary>Singleton</summary>
        public static LibraryMessages Instance => instance.Value;

        /// <summary>Create messages</summary>
        public LibraryMessages() : base() { this.AddRange(MessageDescriptionsExtensions.FieldReader(this)); }

        /// <summary>Create description</summary>
        static IMessageDescription create(string key, long id, string templateText) => new MessageDescription($"Library.{key}", id, templateText).SetHResult(id);

        /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
        public readonly IMessageDescription BadUnexpected = create(nameof(BadUnexpected), 0xA0A10001, "'{object}': Unexpected error");
        /// <summary>Captured unexpected <see cref="System.Exception"/>.</summary>
        public readonly IMessageDescription BadArgumentNull = create(nameof(BadArgumentNull), 0xA0A10002, "'{object}': Unexpected error");
        /// <summary>Good result.</summary>
        public readonly IMessageDescription GoodResult = create(nameof(GoodResult), 0x20A10003, "'{object}': Unexpected error");
    }
    // </98>

    // <99>
    /// <summary></summary>
    public class LibraryMessagesTable : MessageDescriptions
    {
        /// <summary>Singleton</summary>
        static readonly Lazy<LibraryMessagesTable> instance = new Lazy<LibraryMessagesTable>(() => new LibraryMessagesTable().Initialize().ReadSummaryXmls().SetAllReadOnly().SetReadOnly());
        /// <summary>Singleton</summary>
        public static LibraryMessagesTable Instance => instance.Value;
        /// <summary>Base id for datatype codes.</summary>
        public const int BaseCode = 0x20A10000;
        /// <summary>Initialize fields</summary>
        public virtual LibraryMessagesTable Initialize() => this.AddRange(MessageDescriptionsExtensions.FieldReader(this));

        /// <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>

}