Messages and Exceptions

.NewException(this message) creates an exception where the IMessage is attached.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Throw
throw argumentNull.New("argumentName").NewException();

.NewException<E>(this message) creates an E if possible, otherwise fallbacks to another exception.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Throw
throw argumentNull.New("argumentName").NewException<InvalidOperationException>();

Other fields can be attached to message before wrapped into exception.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Create exception with message (without throw)
Exception e =
    argumentNull
    .New("argumentName")
    .SetTime(DateTime.Now)
    .SetId(IdGenerators.Guid)
    .NewException();

.Throw(this message) throws message as exception. Note that compiler does not regard this as end of code path despite method's [DoesNotReturn] attribute.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Create message and throw
argumentNull.New("argumentName").Throw();

.Throw<E>(this message) throws an E if possible, otherwise fallbacks to another exception.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Throw
argumentNull.New("argumentName").Throw<InvalidOperationException>();

.NewException(this messageDescription, object[] args) creates a new message and exception from IMessageDescription.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Create exception with attached message
throw argumentNull.NewException("argumentName");

.NewException<E>(this messageDescription, args) creates an E if possible, otherwise fallbacks to another exception.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Create exception with attached message
throw argumentNull.NewException<InvalidOperationException>("argumentName");

.Throw(this messageDescription, args) creates a message, an exception and throws it.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Create exception with attached message
argumentNull.Throw("argumentName");

.Throw<E>(this messageDescription, args) creates a message, an E and throws it.

// Create message description
IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
// Create exception with attached message
argumentNull.Throw<InvalidOperationException>("argumentName");

.Code from message description is resolvable from exception.

try
{
    // Create message description
    IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
    // Create exception with attached message
    throw argumentNull.New("argumentName").NewException();
}
catch (Exception e) when (e.AttachedMessage()?.MessageDescription.Code == SystemMessages.ArgumentNull.Generic.Code)
{
}

.HResult from message description is passed to exception.

try
{
    // Create message description
    IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
    // Create exception with attached message
    throw argumentNull.New("argumentName").NewException();
}
catch (Exception e) when (e.HResult == HResultIds.COR_E_ARGUMENT)
{
}

.TryGetAttachedMessage() resolves the attached message.

try
{
    // Create message description
    IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
    // Create exception with attached message
    throw argumentNull
            .New("argumentName")
            .SetTime(DateTime.Now)
            .SetId(IdGenerators.Guid.Next)
            .SetUserData("Hello", "World")
            .NewException();
}
catch (Exception e) when (e.TryGetAttachedMessage(out IMessage message))
{
    // Print message
    WriteLine(message); // "Invalid argument 'argumentName'"
    // Print time
    WriteLine(message.Time); // ""
    // Print event id
    WriteLine(message.Id); // "9016d669-ef99-44cd-8184-be4f8ab594d4"
    // Print user-data
    WriteLine(message.UserData["Hello"]); // "World"
    // rethrow
    throw;
}

.AttachedMessage() also resolves the attached message.

try
{
    // Create message description
    IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
    // Create exception with attached message
    throw argumentNull
            .New("argumentName")
            .SetTime(DateTime.Now)
            .SetId(IdGenerators.Guid.Next)
            .SetUserData("Hello", "World")
            .NewException();
}
catch (Exception e) 
{
    // Get possible message
    IMessage message = e.AttachedMessage()!;
    // Print time
    WriteLine(message.Time); // "2.1.2022 12.31.06"
    // Print event id
    WriteLine(message.Id); // "9016d669-ef99-44cd-8184-be4f8ab594d4"
    // Print data
    WriteLine(message.UserData["Hello"]); // "World"
    // rethrow
    throw;
}

Full Example

Full example

using System;
using Avalanche.Utilities;
using static System.Console;
using Avalanche.Message;
using Avalanche.StatusCode;
using Avalanche.Template;

class messageexception
{
    public static void Run()
    {
        {
            try
            {
                // <01>
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Throw
                throw argumentNull.New("argumentName").NewException();
                // </01>
            }
            catch (Exception)
            {
            }
        }
        {
            try
            {
                // <01B>
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Throw
                throw argumentNull.New("argumentName").NewException<InvalidOperationException>();
                // </01B>
            }
            catch (Exception)
            {
            }
        }
        {
            // <02>
            // Create message description
            IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
            // Create exception with message (without throw)
            Exception e =
                argumentNull
                .New("argumentName")
                .SetTime(DateTime.Now)
                .SetId(IdGenerators.Guid)
                .NewException();
            // </02>
        }
        {
            try
            {
                // <03>
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Create message and throw
                argumentNull.New("argumentName").Throw();
                // </03>
            }
            catch (Exception)
            {
            }
        }
        {
            try
            {
                // <04>
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Throw
                argumentNull.New("argumentName").Throw<InvalidOperationException>();
                // </04>
            }
            catch (Exception)
            {
            }
        }
        {
            try
            {
                // <05>
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Create exception with attached message
                throw argumentNull.NewException("argumentName");
                // </05>
            }
            catch (Exception)
            {
            }
        }
        {
            try
            {
                // <06>
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Create exception with attached message
                throw argumentNull.NewException<InvalidOperationException>("argumentName");
                // </06>
            }
            catch (Exception)
            {
            }
        }
        {
            try
            {
                // <07>
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Create exception with attached message
                argumentNull.Throw("argumentName");
                // </07>
            }
            catch (Exception)
            {
            }
        }
        {
            try
            {
                // <08>
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Create exception with attached message
                argumentNull.Throw<InvalidOperationException>("argumentName");
                // </08>
            }
            catch (Exception)
            {
            }
        }

        {
            // <09>
            try
            {
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Create exception with attached message
                throw argumentNull.New("argumentName").NewException();
            }
            catch (Exception e) when (e.AttachedMessage()?.MessageDescription.Code == SystemMessages.ArgumentNull.Generic.Code)
            {
            }
            // </09>
        }

        {
            // <10>
            try
            {
                // Create message description
                IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                // Create exception with attached message
                throw argumentNull.New("argumentName").NewException();
            }
            catch (Exception e) when (e.HResult == HResultIds.COR_E_ARGUMENT)
            {
            }
            // </10>
        }

        {
            try
            {
                // <11>
                try
                {
                    // Create message description
                    IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                    // Create exception with attached message
                    throw argumentNull
                            .New("argumentName")
                            .SetTime(DateTime.Now)
                            .SetId(IdGenerators.Guid.Next)
                            .SetUserData("Hello", "World")
                            .NewException();
                }
                catch (Exception e) when (e.TryGetAttachedMessage(out IMessage message))
                {
                    // Print message
                    WriteLine(message); // "Invalid argument 'argumentName'"
                    // Print time
                    WriteLine(message.Time); // ""
                    // Print event id
                    WriteLine(message.Id); // "9016d669-ef99-44cd-8184-be4f8ab594d4"
                    // Print user-data
                    WriteLine(message.UserData["Hello"]); // "World"
                    // rethrow
                    throw;
                }
                // </11>
            }
            catch (Exception) { }
        }

        {
            try
            {
                // <12>
                try
                {
                    // Create message description
                    IMessageDescription argumentNull = new MessageDescription("mscorlib.ArgumentNull_Generic", 0xA3450267, "Value cannot be null.").SetHResult(0x80070057).SetSeverity(MessageLevel.Error).SetException(typeof(ArgumentException));
                    // Create exception with attached message
                    throw argumentNull
                            .New("argumentName")
                            .SetTime(DateTime.Now)
                            .SetId(IdGenerators.Guid.Next)
                            .SetUserData("Hello", "World")
                            .NewException();
                }
                catch (Exception e) 
                {
                    // Get possible message
                    IMessage message = e.AttachedMessage()!;
                    // Print time
                    WriteLine(message.Time); // "2.1.2022 12.31.06"
                    // Print event id
                    WriteLine(message.Id); // "9016d669-ef99-44cd-8184-be4f8ab594d4"
                    // Print data
                    WriteLine(message.UserData["Hello"]); // "World"
                    // rethrow
                    throw;
                }
                // </12>
            }
            catch (Exception) { }
        }

    }
}