IMessageDescriptions
IMessageDescriptions is a store of message descriptions.
/// <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 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;
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>
}