Introduction
Avalanche.Message unifies various codebase facets.
Class libraries:
- Avalanche.Message.dll contains implementations.
- Avalanche.Message.Abstractions.dll contains interfaces.
- Avalanche.Message.Logging.dll contains Microsoft.Extensions.Logging extensions.
- Avalanche.StatusCode.dll contains various public status codes (see more).
Message is an argumentable record.
IMessage message = new Message()
.SetMessageDescription(SystemMessages.ArgumentNull.Generic)
.SetArguments("argumentName")
.SetNow()
.SetId(123)
.SetUserData("User-data", new object())
.SetReadOnly();
Messages are statuscodes (validation).
// Parse invalid format
IValidable validable = TemplateFormats.Brace.Breakdown["Welcome {?}."];
// Validate
IEnumerable<IMessage> statuscodes = validable.Validate();
// Handle status codes
foreach (IMessage statuscode in statuscodes)
{
// Parse error
if (statuscode.MessageDescription.Code == TemplateBreakdown.MalformedFormat.Code)
{ /* ... */ }
}
Messages are events.
// Create event description
IMessageDescription fileCreatedEventDescription = new MessageDescription("FileCreated", 0x20012301, "File '{filename}' was created.");
// Create event
IMessage @event = fileCreatedEventDescription
.New("filename.txt")
.SetTime(DateTime.Now)
.SetId(IdGenerators.Guid.Next)
.SetUserData("EventSource", "Server-45")
.SetReadOnly();
Messages are throwable.
throw SystemMessages.ArgumentNull.Generic.New("argumentName").SetTime(DateTime.Now).NewException();
Messages are string.Format() printable.
// Create message
IMessage message = SystemMessages.ArgumentNull.Generic.New("argumentName");
// Get format text
string formatText = message.MessageDescription.Template.Breakdown.FormatTemplate();
// Formulate
string formulation = string.Format(formatText, message.Arguments);
// Print
WriteLine(formulation);
Messages are loggable.
SystemMessages.ArgumentNull.Generic.New("argumentName").LogTo(logger);
Messages are localizable.
// "You have no apples."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("en"), 0);
// "Sinulla ei ole omenoita."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("fi"), 0);
Message texts are pluralizable.
// "You have no apples."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("en"), 0);
// "You have an apple."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("en"), 1);
// "You have 3 apples."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("en"), 3);
Messages can have HResult code.
try
{
throw SystemMessages.InvalidOperation.Exception.NewException();
}
catch (Exception e) when (e.HResult == HResultIds.COR_E_INVALIDOPERATION)
{
}
Messages are serializable and are processable in-process and out-of-process.
IMessage message = HResult.S_OK.New().SetId(IdGenerators.Integer.Next);
// Serialize as csv line
string[] cells = { message.MessageDescription.Code.ToString(), message.Id.ToString(), Escaper.Comma.EscapeJoin(message.Arguments.Select(a=>a?.ToString()??"")) };
string csvLine = Escaper.Semicolon.EscapeJoin(cells);
Full Example
Full example
using System;
using System.Collections;
using System.Collections.Generic;
using System.Globalization;
using Avalanche.Service;
using Avalanche.Utilities;
using Avalanche.Message;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Serilog;
using Serilog.Core;
using Serilog.Events;
using static System.Console;
using Avalanche.StatusCode;
class messageindex
{
public static void Run()
{
{
// <01>
IMessage message = new Message()
.SetMessageDescription(SystemMessages.ArgumentNull.Generic)
.SetArguments("argumentName")
.SetNow()
.SetId(123)
.SetUserData("User-data", new object())
.SetReadOnly();
// </01>
}
{
try
{
// <08>
throw SystemMessages.ArgumentNull.Generic.New("argumentName").SetTime(DateTime.Now).NewException();
// </08>
}
catch (Exception) { }
}
{
// <09>
// Parse invalid format
IValidable validable = TemplateFormats.Brace.Breakdown["Welcome {?}."];
// Validate
IEnumerable<IMessage> statuscodes = validable.Validate();
// Handle status codes
foreach (IMessage statuscode in statuscodes)
{
// Parse error
if (statuscode.MessageDescription.Code == TemplateBreakdown.MalformedFormat.Code)
{ /* ... */ }
}
// </09>
}
{
// <10>
// Create message
IMessage message = SystemMessages.ArgumentNull.Generic.New("argumentName");
// Get format text
string formatText = message.MessageDescription.Template.Breakdown.FormatTemplate();
// Formulate
string formulation = string.Format(formatText, message.Arguments);
// Print
WriteLine(formulation);
// </10>
}
{
// Service collection
IServiceCollection serviceCollection = new ServiceCollection();
// Add logging
InitializeLogging(serviceCollection);
// Services
using var service = Services.Create((ServiceHandlers.Instance, serviceCollection));
// Create ILogger
var logger = service.GetRequiredService<Microsoft.Extensions.Logging.ILogger<messageindex>>();
// <11>
SystemMessages.ArgumentNull.Generic.New("argumentName").LogTo(logger);
// </11>
}
{
// Create message. TODO Finish localization
IMessage message = HResult.S_OK.New();
// <14>
// "You have no apples."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("en"), 0);
// "Sinulla ei ole omenoita."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("fi"), 0);
// </14>
}
{
// Create message. TODO Finish pluraliation
IMessage message = HResult.S_OK.New();
// <15>
// "You have no apples."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("en"), 0);
// "You have an apple."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("en"), 1);
// "You have 3 apples."
message.MessageDescription.Template.Print(CultureInfo.GetCultureInfo("en"), 3);
// </15>
}
{
// <21>
// Create event description
IMessageDescription fileCreatedEventDescription = new MessageDescription("FileCreated", 0x20012301, "File '{filename}' was created.");
// Create event
IMessage @event = fileCreatedEventDescription
.New("filename.txt")
.SetTime(DateTime.Now)
.SetId(IdGenerators.Guid.Next)
.SetUserData("EventSource", "Server-45")
.SetReadOnly();
// </21>
}
{
// <31>
try
{
throw SystemMessages.InvalidOperation.Exception.NewException();
}
catch (Exception e) when (e.HResult == HResultIds.COR_E_INVALIDOPERATION)
{
}
// </31>
}
{
// <41>
IMessage message = HResult.S_OK.New().SetId(IdGenerators.Integer.Next);
// Serialize as csv line
string[] cells = { message.MessageDescription.Code.ToString(), message.Id.ToString(), Escaper.Comma.EscapeJoin(message.Arguments.Select(a=>a?.ToString()??"")) };
string csvLine = Escaper.Semicolon.EscapeJoin(cells);
// </41>
WriteLine(csvLine); // "0;0"
}
}
static IServiceCollection InitializeLogging(IServiceCollection serviceCollection)
{
// Initial configuration
MemoryConfiguration memConfig = new MemoryConfiguration()
.Set("Logging:LogLevel:Default", "Debug")
.Set("Serilog:WriteTo:0:Name", "Console")
.Set("Serilog:WriteTo:0:Args:OutputTemplate", "[{EventIdHex} {Level:u1}] {Message:lj}{NewLine}{Exception}")
.Set("Serilog:WriteTo:0:Args:RestrictedToMinimumLevel", "Verbose")
.Set("Serilog:WriteTo:0:Args:Theme", "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console");
// Read configuration
IConfigurationRoot configuration = new ConfigurationBuilder()
.Add(memConfig)
.Build();
//
var switchableLogger = new Serilog.SwitchableLogger();
// Logging
serviceCollection.AddLogging(loggingBuilder =>
loggingBuilder
#if DEBUG
.SetMinimumLevel(LogLevel.Trace)
#else
.SetMinimumLevel(LogLevel.Information)
#endif
.AddSerilog(switchableLogger, true)
.AddSerilogConfigurationLoader(configuration, switchableLogger,
c => new Serilog.LoggerConfiguration()
#if DEBUG
.MinimumLevel.Verbose()
#else
.MinimumLevel.Information()
#endif
.Enrich.With(new EventIdEnricher())
.ReadFrom.Configuration(configuration)
.CreateLogger())
);
//
return serviceCollection;
}
/// <summary>Memory configuration</summary>
public class MemoryConfiguration : ConfigurationProvider, IEnumerable<KeyValuePair<string, string>>, IConfigurationSource
{
/// <summary>Expose inner configuration data</summary>
public new IDictionary<String, String> Data => base.Data;
/// <summary>Configuration data</summary>
public string this[string key] { get => base.Data[key]; set => base.Data[key] = value; }
/// <summary>Create memory configuration</summary>
public MemoryConfiguration() : base() { }
/// <summary>Assign <paramref name="value"/> to <paramref name="key"/></summary>
public new MemoryConfiguration Set(string key, string value) { base.Data[key] = value; return this; }
/// <summary>Build configuration provider.</summary>
public IConfigurationProvider Build(IConfigurationBuilder builder) => this;
/// <summary>Enumerate</summary>
public IEnumerator<KeyValuePair<string, string>> GetEnumerator() => Data.GetEnumerator();
/// <summary>Enumerate</summary>
IEnumerator IEnumerable.GetEnumerator() => Data.GetEnumerator();
}
/// <summary>Serilog enricher that reduces "EventId" to its "id" field.</summary>
public class EventIdEnricher : ILogEventEnricher
{
/// <summary>Reduce to EventId.id</summary>
public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
{
// Get properties
if (!logEvent.Properties.TryGetValue("EventId", out LogEventPropertyValue eventIdStructure)) return;
// Not structure field
if (eventIdStructure is not StructureValue structureValue || structureValue.Properties == null) return;
// Get list
IReadOnlyList<LogEventProperty> list = structureValue.Properties;
// Process each
for (int i = 0; i < list.Count; i++)
{
// Get property
LogEventProperty logEventProperty = list[i];
// Not id
if (logEventProperty.Name != "Id") continue;
// New property
LogEventProperty eventId = propertyFactory.CreateProperty("EventId", logEventProperty.Value);
// Add as new key
logEvent.AddOrUpdateProperty(eventId);
// Print as hex
string hex = logEventProperty.Value.ToString("X8", CultureInfo.InvariantCulture);
// New property
LogEventProperty eventIdHex = propertyFactory.CreateProperty("EventIdHex", hex);
// Add as new key
logEvent.AddOrUpdateProperty(eventIdHex);
// Completed
return;
}
}
}
}