Class StateManager

This class maintains run-time information about the executing assembly, assumed to be a desktop application, that calls it into being. Since it implements the Singleton design pattern, there is never more than one instance.

Inheritance

System.Object

GenericSingletonBase<StateManager>

StateManager

Inherited Members

GenericSingletonBase<StateManager>.s_genTheOnlyInstance

GenericSingletonBase<StateManager>.TheOnlyInstance

GenericSingletonBase<StateManager>.GetTheSingleInstance()

Namespace: WizardWrx.DLLConfigurationManager

Assembly: WizardWrx.DLLConfigurationManager.dll

Syntax

public class StateManager : GenericSingletonBase<StateManager>

Remarks

This class has several read-write properties, all of which are protected by thread-safe accessors. Both the Get and Set methods are protected, so that a get request blocks until a set request executing in another thread completes.

Fields

ASSEMBLYVERSION_COMPLETE

Specify this constant to the ToString method of a System.Version object (e. g., of an Assembly) to cause it to return the entire version string.

Declaration

public const int ASSEMBLYVERSION_COMPLETE = null

Field Value

Type	Description
System.Int32

ASSEMBLYVERSION_EXCEPT_REVISION

Specify this constant to the ToString method of a System.Version object (e. g., of an Assembly) to cause it to return all but the build number.

Declaration

public const int ASSEMBLYVERSION_EXCEPT_REVISION = null

Field Value

Type	Description
System.Int32

ASSEMBLYVERSION_MAJOR_AND_MINOR

Specify this constant to the ToString method of a System.Version object (e. g., of an Assembly) to cause it to return only the major and minor version numbers.

Declaration

public const int ASSEMBLYVERSION_MAJOR_AND_MINOR = null

Field Value

Type	Description
System.Int32

ASSEMBLYVERSION_MAJOR_ONLY

Specify this constant to the ToString method of a System.Version object (e. g., of an Assembly) to cause it to return only the major version number.

Declaration

public const int ASSEMBLYVERSION_MAJOR_ONLY = null

Field Value

Type	Description
System.Int32

UNSUPPORTED_EXE_SUBSYSTEM

The DWLastDllError property returns this value when StandardHandleState is called by code running in anything except the Windows character mode subsystem.

Declaration

public const int UNSUPPORTED_EXE_SUBSYSTEM = null

Field Value

Type	Description
System.Int32

Properties

AppErrorMessages

Make the array of error messages available, for reading only, under guard of a lock, to ensure that another thread isn't adding to the array while it is being returned.

Declaration

public string[] AppErrorMessages { get; }

Property Value

Type	Description
System.String[]

AppExceptionLogger

This property returns a reference to the singleton ExceptionLogger, which is created immediately following creation of this instance. Hence, by the time the reference is returned, this reference is guaranteed to be valid and read only for work.

Declaration

public ExceptionLogger AppExceptionLogger { get; }

Property Value

Type	Description
ExceptionLogger

AppReturnCode

Use this read/write property to set the application return code from anywhere, so that you don't have to use another, potentially awkward, method to get the word back to the main routine.

Declaration

public int AppReturnCode { get; set; }

Property Value

Type	Description
System.Int32

Remarks

Access to this property is synchronized by an internally managed object lock.

AppRootAssemblyFileBaseName

This property is a shortcut to the AssemblyFileBaseName property of the AppRootAssembly property.

Declaration

public string AppRootAssemblyFileBaseName { get; }

Property Value

Type	Description
System.String

Remarks

Since the underlying property is read only, and has a static initializer, it is thread-safe without the overhead of a lock.

AppRootAssemblyFileDirName

This property is a shortcut to the AssembyDirName property of the AppRootAssembly property.

Declaration

public string AppRootAssemblyFileDirName { get; }

Property Value

Type	Description
System.String

Remarks

Since the underlying property is read only, and has a static initializer, it is thread-safe without the overhead of a lock.

AppRootAssemblyFileName

This property is a shortcut to the AssemblyFileName property of the AppRootAssembly property.

Declaration

public string AppRootAssemblyFileName { get; }

Property Value

Type	Description
System.String

Remarks

Since the underlying property is read only, and has a static initializer, it is thread-safe without the overhead of a lock.

AppRootAssemblyName

This property returns the fully qualified name of the root assembly, the first assembly that loaded into the default application domain.

Declaration

public _AssemblyName AppRootAssemblyName { get; }

Property Value

Type	Description
_AssemblyName

Remarks

This property yields a wealth of information about the assembly, including all four parts of its version number, its public key token, if it has one, and its culture.

See Also

GetAssemblyProductAndVersion()

GetAssemblyProductAndVersion(StateManager.AssemblyVersionRequest)

AppStartupTimeLocal

This property is a shortcut to the StartupTime property of the AppRootAssembly property.

Declaration

public DateTime AppStartupTimeLocal { get; }

Property Value

Type	Description
DateTime

Remarks

Since the underlying property is read only, and has a static initializer, it is thread-safe without the overhead of a lock.

AppStartupTimeUtc

This property is a shortcut to the StartupTimeUTC property of the AppRootAssembly property.

Declaration

public DateTime AppStartupTimeUtc { get; }

Property Value

Type	Description
DateTime

Remarks

Since the underlying property is read only, and has a static initializer, it is thread-safe without the overhead of a lock.

AppSubsystemID

Return the ID of the subsystem in which the assembly runs. Call the GetAppSubsystemString method to translate the ID into a human readable message. The translation is way too expensive to expose as a property, and too infrequently needed to justify having the constructor store it in a string.

Declaration

public Int16 AppSubsystemID { get; }

Property Value

Type	Description
Int16

See Also

GetAppSubsystemID()

GetAppSubsystemString()

AppUptime

Gets the elapsed time since the application started.

Declaration

public TimeSpan AppUptime { get; }

Property Value

Type	Description
TimeSpan

ConsoleMessageTimeFormat

Use this property to get a reference to the FormattedLocalTime object that governs the formatting of the times displayed in the BOJ and EOJ messages.

Declaration

public TimeDisplayFormatter ConsoleMessageTimeFormat { get; }

Property Value

Type	Description
TimeDisplayFormatter

DefaultEventSourceID

Gets the registered default event source ID.

Declaration

public string DefaultEventSourceID { get; }

Property Value

Type	Description
System.String

Remarks

If no event source is registered, this property returns the WIZARDWRX_EVENT_SOURCE_ID string static ExceptionLogger string.

DWLastDllError

Query this property for the value returned by GetLastError.

Declaration

public int DWLastDllError { get; }

Property Value

Type	Description
System.Int32

Remarks

Strictly speaking, the value is returned by Marshal.GetLastWin32Error.

InitialWorkingDirectoryName

Gets the initial working directory, which reflects its value when the application started.

Declaration

public string InitialWorkingDirectoryName { get; }

Property Value

Type	Description
System.String

Remarks

This property has a static initializer, and is never changed.

ShowUTCTime

Set this property to TRUE to cause UTC times to be displayed in all time stamps included in console BOJ and EOJ messages.

Set it to FALSE to display only local times. The class default setting is TRUE.

See the Remarks listed with the class definition.

Declaration

public bool ShowUTCTime { get; set; }

Property Value

Type	Description
System.Boolean

Methods

FormatSystemErrorMessage(Int32)

Return the message associated with a system status code.

Declaration

public static string FormatSystemErrorMessage(int pdwLastError)

Parameters

Type	Name	Description
System.Int32	pdwLastError	Specify the status code for which the system message is desired.

Returns

Type	Description
System.String	A new Win32Exception exception is constructed from the specified status code, and its Message property is returned.

Remarks

This convenience method amounts to syntactic sugar. Since it is very unlikely to ever be called by the method that motivated me to create it, I'll let it go ahead and call through it, even though calling the constructor directly, passing in the static member that holds the status code would be a couple of orders of magnitude more efficient.

GetAppSubsystemID()

Return the AppSubsystemID property, explicitly cast to a PESubsystemID.

Declaration

public PESubsystemInfo.PESubsystemID GetAppSubsystemID()

Returns

Type	Description
PESubsystemInfo.PESubsystemID	The return value is the AppSubsystemID property, cast to a member of the ESubsystemInfo.PESubsystemID enumeration.

Remarks

This method provides a more meaningful interpretation of the AppSubsystemID value.

This routine is implemented as an instance method, so that its code runs only as needed.

See Also

AppSubsystemID

GetAppSubsystemString()

GetAppSubsystemString()

Return a sentence that identifies the subsystem in which the assembly that started the current process runs.

Declaration

public string GetAppSubsystemString()

Returns

Type	Description
System.String	The return value is a short sentence that describes the subsystem in which the assembly that started the current process runs.

Remarks

I made this a method so that it is computed strictly as needed, even in a debugging session when the Visual Studio Hosting process runs all the property getters when an object is expanded in the locals or watch window.

This method is much more expensive than GetAssemblyFQFN, because it gets the returned string from a string resource.

GetAssemblyFQFN()

Return the fully qualified name of the assembly that started the current process.

Declaration

public string GetAssemblyFQFN()

Returns

Type	Description
System.String	The return value is a string that contains the fully qualified name of the assembly that started the current process.

Remarks

I made this a method so that it is computed as needed, even in a debugging session when the Visual Studio Hosting process runs all the property getters when an object is expanded in the locals and watch windows.

GetAssemblyProductAndVersion()

Get the assembly product name and version number is a string that is suitable for use as a window caption.

Declaration

public string GetAssemblyProductAndVersion()

Returns

Type	Description
System.String	The return value is a string, suitable for use as the caption of a window, such as a form or message box. The returned string contains the product name, followed by the entire 4-part version string.

GetAssemblyProductAndVersion(StateManager.AssemblyVersionRequest)

Get the assembly product name and version number is a string that is suitable for use as a window caption.

Declaration

public string GetAssemblyProductAndVersion(StateManager.AssemblyVersionRequest penmAssemblyVersionRequest)

Parameters

Type	Name	Description
StateManager.AssemblyVersionRequest	penmAssemblyVersionRequest	Use a member of the AssemblyVersionRequest enumeration to indicate how many parts of the four-part version number to include.

Returns

Type	Description
System.String	The return value is a string, suitable for use as the caption of a window, such as a form or message box. The returned string contains the product name, followed by the specified number of parts of the product version.

See Also

AppRootAssemblyName

GetStdHandleFQFN(StandardHandleInfo.StandardConsoleHandle)

Report the file, if any, to which the specified standard handle is redirected.

Declaration

public string GetStdHandleFQFN(StandardHandleInfo.StandardConsoleHandle penmStdHandle)

Parameters

Type	Name	Description
StandardHandleInfo.StandardConsoleHandle	penmStdHandle	Specify the StandardHandleInfo.StandardConsoleHandle member that corresponds to the handle for which you wish to know whether it is attached or redirected.

Returns

Type

Description

System.String

If the function succeeds and the handle is redirected, the return value is the name of the file to which the specified handle is redirected. Otherwise, the return value is one of two strings that explain the error. Properties.Resources.MSG_APP_CHARACTER_MODE_APPS_ONLY is the complete text of the message displayed when the calling routine is running in the Windows graphical mode subsystem. Properties.Resources.ERRMSG_STD_HANDLE_STATE is the beginning of a message, which is followed by the returned system status code, shown in both hexadecimal and decimal notation, followed by the associated system message.

GetTheSingleInstance(System.Reflection.Assembly)

Call this method from any class that exposes a reference to the singleton as a read only property. Please see the Remarks section.

Declaration

public static StateManager GetTheSingleInstance(System.Reflection.Assembly pasmCallingAssembly)

Parameters

Type	Name	Description
System.Reflection.Assembly	pasmCallingAssembly	Pass in a reference to the assembly that is calling this method on behalf of an object that exposes a reference to this object as a read only property. Please see the Remarks section.

Returns

Type	Description
StateManager	The return value is a reference to the singleton, which is created the first time the method is called. Subsequent calls return a reference to the singleton.

Remarks

Since making a protected constructor safe for use by a class that implements the Singleton design pattern, and a class that calls this method causes System.Reflection.Assembly.GetCalllingAssembly to report the assembly in which the call executes as the calling assembly, any such method must explicitly identify the assembly that contains the process entry point.

When the Visual Studio Hosting Process is enabled, it becomes the entry assembly, hiding the "real" entry assembly (the assembly under test), System.Reflection.Assembly.GetEntryAssembly cannot be used safely. Moreover, since the Visual Studio Hosting Process runs in the graphical (Windows) subsystem, the entry assembly cannot be used to correctly determine whether the entry assembly runs in the character mode subsystem.

Although the class needs only the Location property off the Assembly instance, I elected to call for the entire Assembly to be passed in, to make the needs of this method unambiguous. Since the calling method must call one of two static methods on the Assembly class, both of which return instances of Assembly, this doesn't impose any extra burden on the calling assembly.

LoadErrorMessageTable(String[])

Load the table of error messages for use with the ErrorExit method.

Declaration

public int LoadErrorMessageTable(string[] pastrErrorMessages)

Parameters

Type	Name	Description
System.String[]	pastrErrorMessages	Array of strings, for use as error messages. See Remarks.

Returns

Type	Description
System.Int32	Count of error messages loaded into the object. Hence, the Ubound of the array is one less than the return value, and its LBound is zero.

Remarks

Error message numbers are array subscripts. This imposes two requirements on the list.

1. You must supply a message for the default exit code of zero, even if you don't use it.

2. Status codes must be sequentially numbered.

The second requirement can be relaxed, at the cost of inserting one or more dummy error messages, which may be empty strings, to account for the skipped numbers. The obvious disadvantage is some bloat in the message table.

You must call this method before your program can get a useful error message from ErrorExit. Although the call to ErrorExit succeeds, the message is "Internal error: Unknown status code," followed by the supplied raw exit code.

StandardHandleState(StandardHandleInfo.StandardConsoleHandle)

Evaluate whether a standard handle is attached to a console or redirected.

Declaration

public StandardHandleInfo.StandardHandleState StandardHandleState(StandardHandleInfo.StandardConsoleHandle penmStdHandle)

Parameters

Type	Name	Description
StandardHandleInfo.StandardConsoleHandle	penmStdHandle	Specify the StandardHandleInfo.StandardConsoleHandle member that corresponds to the handle for which you wish to know whether it is attached or redirected.

Returns

Type	Description
StandardHandleInfo.StandardHandleState	If the function succeeds, the return value is either ShsAttached or ShsRedirected. Otherwise, there was an error, and you should call Marshal.GetLastWin32Error to determine exactly what happened. The singleton has a private property where the return value is stored.