Usage

Contents

Project Description Usage

Requirements

In order to use the framework you must:
  1. Add a reference to CodePlex.ErrorManagement in your project
  2. Add using CodePlex.ErrorManagement; in any source file that will be using the error string retrieval extension methods

Resource Files

Linking Enumerations to Resource Files

By default the framework will use the resource file named ErrorStrings.resx in the same namespace as the enumeration. (See Resource File Namespaces.)

You can use ErrorStringResourceAttribute to explicity set the resource file to use. If the attribute is applied to the assembly the specified file will be used for all enumerations that are not otherwise decorated with ErrorStringResourceAttribute. For example:

using CodePlex.ErrorManagement;

[assembly: ErrorStringResource("<projectnamespace>.ResourceOne")]

namespace FooSpace
{
    [ErrorStringResource("ResourceTwo", typeof(Bar1)]
    enum Bar1
    {
        ...
    }

    enum Bar2
    {
    }
}

Enum Bar1 will use ResourceTwo.resx for string lookup while Enum Bar2 will use the assembly specified ResourceOne.resx.

String Lookups within Resource Files

The framework searches for strings by first looking for a string assigned to <enumerationTypeName>.<fieldName> and if not found then searches for <fieldName>. For example, with a resource file definition of:

Resource String Name Resource String Value
bar Default value
Foo2.bar Specific value


and code of:

enum Foo1
{
    bar,
}

enum Foo2
{
    bar,
}

then a lookup of Foo1.bar will yield "Default value" while a lookup of Foo2.bar will yield "Specific Value".

Resource File Namespace

The namespace for a resource file is equal to the project default namespace (as specified in the project properties) plus any project folder hierarchy for the resource file (folders names are separated by periods, spaces in names are replaced with underscores).

Error String Format Control

Creating an error message string is a to step process. In the first step the string retrieved from resources is formatted (see string.Format) using the arguments passed in to the Exception or FormatErrorString extension methods. The resulting string is then formatted again with an Error Message Format to produce the final message string. This second step is used to add heading (or footing) information common to all message strings withough requiring that information to be included in all strings. The format string for this second step is specified in the resources file using the name _ErrorMessageFormat. If not specified, the format string "{2}({1}): {0}" will be used.

Within the format string the following format codes are assigned:

Format code Meaning
{0} The format string, loaded from resources, with parameters substituted in.
{1} The Int32 value of the enumeration field used to lookup the error message.
{2} The name of the enumeration type.
{3} The namespace of the enumeration type.
{4} The name of the enumeration field used to lookup the error message.


So if your _ErrorMessageFormat in resources is set to "CS{1}: {2}.{3}.{4}: {0} : End Stuff", then:

namespace Namespace
{
    enum Test
    {
        Field = 30
    }
    static class Foo
    {
        public static void Bar()
        {
            Console.WriteLine(Test.Field.FormatErrorString());
        }
    }
}

Would yield: "CS30: Namespace.Test.Field: <<some string from resources>> : End Stuff"

Culture Settings

Resource lookups and string formatting is influenced by the CultureInfo assignment. Unless otherwise overridden, the CultureInfo assigned to CodePlex.ErrorManagement.Settings.GlobalCultureOverride will be used. You can specifically set a CultureInfo for an enumeration with the SetErrorManagementCultureInfoOverride extension method (setting to null will cause the framework to use the GlobalCultureOverride setting again). The same CultureInfo setting is used for both the string lookup in resources (which may affect the resource file used) and for the string.Format method used to format the error message. You can also specify a particular CultureInfo to use in your FormatErrorString extension method call.

The Error Message Format is unaffected by CultureInfo settings.

Specifying Exceptions

The Exception extension method is a short form way of creating an exception. The exception created for any given field is determined by the ErrorExceptionAttribute applied to the field (or to the enumeration if the field is not so decorated). If no ErrorExceptionAttribute has been applied to either the field or enumeration then the NotSupportedException is used. Any exception can be used provided the exception has a constructor that takes a string argument as the exception's message.

For example:

[ErrorException(typeof(ApplicationException))]
enum Foo1
{
    bar1,

    [ErrorException(typeof(DataMisalignedException))]
    bar2,
}

enum Foo2
{
    bar,
}

then,
  • Foo1.bar1.Exception(somedata) will return an ApplicationException
  • Foo1.bar2.Exception(somedata) will return a DataMisalignedException
  • Foo2.bar.Exception(somedata) will returh a NotSupportedException

Last edited Aug 28, 2009 at 10:08 PM by tulebast, version 4

Comments

tgswilson Feb 17, 2012 at 5:46 PM 
I have now coded a snippet in my test app and now appreciate that the resource string key is not a number but the actual name of the enumerated value. As a C++ developer, I overlook the C# feature
of being able to use the enumeration name as a string rather than its value - cool

string errorCode = ErrorCode.MissingStringDefinition.ToString();
int errorCodeValue = (Int32)ErrorCode.MissingStringDefinition;

Perhaps a screen shot of Name/Value pairs from Resources.resx would make this clearer to people like me.

Or just a snippet of the XML
<!-- Don't do this -->
<data name="1000" xml:space="preserve">
<value>1000 value</value>
</data>
<!-- Do this -->
<data name="MissingStringDefinition" xml:space="preserve">
<value>MissingStringDefinition value</value>
</data>

tgswilson Feb 17, 2012 at 5:35 PM 
Linking Enumerations to Resource Files
=========================
In this section you appear to use Bar as the enum type but in later sections, Bar is the resource string key. I find this confusing and inconsistent.

tgswilson Feb 17, 2012 at 4:21 PM 
Well thought out and should prove useful - thanks.

Did you mean?
So if your _ErrorMessageFormat in resources is set to "CS{1}: {3}.{2}.{4}: {0} : End Stuff", then:
Would yield: "CS30: Namespace.Test.Field: <<some string from resources>> : End Stuff"