Class ActivityMonitorExtension

Provides extension methods for IActivityMonitor and other types from the Activity monitor framework.

Inheritance

Object

ActivityMonitorExtension

Inherited Members

Object.ToString()

Object.Equals(Object)

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Namespace: CK.Core

Assembly: CK.ActivityMonitor.dll

Syntax

public static class ActivityMonitorExtension

Methods

CloseGroup(IActivityMonitor, Object)

Closes the current Group. Optional parameter is polymorphic. It can be a string, a ActivityLogGroupConclusion, a List<T> or an IEnumerable<T> of ActivityLogGroupConclusion, or any object with an overridden ToString() method. See remarks (especially for List<ActivityLogGroupConclusion>).

Declaration

public static bool CloseGroup(this IActivityMonitor this, object userConclusion = null)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
Object	userConclusion	Optional string, ActivityLogGroupConclusion object, enumerable of ActivityLogGroupConclusion or object to conclude the group. See remarks.

Returns

Type	Description
Boolean

Remarks

An untyped object is used here to easily and efficiently accommodate both string and already existing ActivityLogGroupConclusion. When a List<ActivityLogGroupConclusion> is used, it will be directly used to collect conclusion objects (new conclusions will be added to it). This is an optimization.

CollectEntries(IActivityMonitor, Action<IReadOnlyList<ActivityMonitorSimpleCollector.Entry>>, LogLevelFilter)

Enables simple "using" syntax to easily collect any LogLevel (or above) entries (defaults to Error) around operations. The callback is called when the the returned IDisposable is disposed and there are at least one collected entry.

Declaration

public static IDisposable CollectEntries(this IActivityMonitor this, Action<IReadOnlyList<ActivityMonitorSimpleCollector.Entry>> errorHandler, LogLevelFilter level = LogLevelFilter.Error)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
Action<IReadOnlyList<ActivityMonitorSimpleCollector.Entry>>	errorHandler	An action that accepts a list of fatal or error ActivityMonitorSimpleCollector.Entry.
LogLevelFilter	level	Defines the level of the collected entries (by default fatal or error entries).

Returns

Type	Description
IDisposable	A IDisposable object used to manage the scope of this handler.

CreateBridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget)

Creates a bridge to another monitor's ActivityMonitorBridgeTarget. Only one bridge to the same monitor can exist at a time: if FindBridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget) is not null, this throws a InvalidOperationException. This bridge does not synchronize AutoTags and Topic (see CreateStrongBridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget)).

Declaration

public static IDisposable CreateBridgeTo(this IActivityMonitorOutput this, ActivityMonitorBridgeTarget targetBridge)

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput.
ActivityMonitorBridgeTarget	targetBridge	The target bridge that will receive our logs.

Returns

Type	Description
IDisposable	A IDisposable object that can be disposed to automatically call UnbridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget).

CreateStrongBridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget)

Creates a strong bridge to another monitor's ActivityMonitorBridgeTarget. Only one bridge to the same monitor can exist at a time: if FindBridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget) is not null, this throws a InvalidOperationException. A strong bridge synchronizes AutoTags and Topic between the two monitors. When created, the 2 properties of the local monitor are set to the ones of the target monitor.

Declaration

public static IDisposable CreateStrongBridgeTo(this IActivityMonitorOutput this, ActivityMonitorBridgeTarget targetBridge)

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput.
ActivityMonitorBridgeTarget	targetBridge	The target bridge that will receive our logs.

Returns

Type	Description
IDisposable	A IDisposable object that can be disposed to automatically call UnbridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget).

DependentActivity(IActivityMonitor, String, Int32)

Enables dependent activities token creation and activities launch. Use StartDependentActivity(IActivityMonitor, ActivityMonitor.DependentToken, String, Int32) to declare the start of a dependent activity on the target monitor.

Declaration

public static ActivityMonitorExtension.DependentSender DependentActivity(this IActivityMonitor this, string fileName = null, int lineNumber = 0)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
String	fileName	Source file name of the emitter (automatically injected by C# compiler but can be explicitly set).
Int32	lineNumber	Line number in the source file (automatically injected by C# compiler but can be explicitly set).

Returns

Type	Description
ActivityMonitorExtension.DependentSender	Sender object.

FindBridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget)

Finds an existing bridge to another monitor.

Declaration

public static ActivityMonitorBridge FindBridgeTo(this IActivityMonitorOutput this, ActivityMonitorBridgeTarget targetBridge)

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput.
ActivityMonitorBridgeTarget	targetBridge	The target bridge that receives our logs.

Returns

Type	Description
ActivityMonitorBridge	The existing ActivityMonitorBridge or null if no such bridge exists.

MonitorEnd(IActivityMonitor, String, String, Int32)

Closes all opened groups and sends an unfiltered MonitorEnd log.

Declaration

public static void MonitorEnd(this IActivityMonitor this, string text = null, string fileName = null, int lineNumber = 0)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
String	text	Optional log text (defaults to "Done.").
String	fileName	Source file name of the emitter (automatically injected by C# compiler but can be explicitly set).
Int32	lineNumber	Line number in the source file (automatically injected by C# compiler but can be explicitly set).

NextLogTime(IActivityMonitor)

Returns a valid CK.Core.DateTimeStamp that will be used for a log: it is based on UtcNow and has a CK.Core.DateTimeStamp.Uniquifier that will not be changed when emitting the next log.

Declaration

public static DateTimeStamp NextLogTime(this IActivityMonitor this)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.

Returns

Type	Description
CK.Core.DateTimeStamp	The next log time for the monitor.

OnError(IActivityMonitor, Action)

Enables simple "using" syntax to easily detect Fatal or Error.

Declaration

public static IDisposable OnError(this IActivityMonitor this, Action onFatalOrError)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
Action	onFatalOrError	An action that is called whenever an Error or Fatal error occurs.

Returns

Type	Description
IDisposable	A IDisposable object used to manage the scope of this handler.

OnError(IActivityMonitor, Action, Action)

Enables simple "using" syntax to easily detect Fatal or Error.

Declaration

public static IDisposable OnError(this IActivityMonitor this, Action onFatal, Action onError)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
Action	onFatal	An action that is called whenever a Fatal error occurs.
Action	onError	An action that is called whenever an Error occurs.

Returns

Type	Description
IDisposable	A IDisposable object used to manage the scope of this handler.

RegisterClient(IActivityMonitorOutput, IActivityMonitorClient)

Registers an IActivityMonitorClient to the Clients list. Duplicates IActivityMonitorClient are silently ignored.

Declaration

public static IActivityMonitorClient RegisterClient(this IActivityMonitorOutput this, IActivityMonitorClient client)

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput object.
IActivityMonitorClient	client	An IActivityMonitorClient implementation.

Returns

Type	Description
IActivityMonitorClient	The registered client.

RegisterClient<T>(IActivityMonitorOutput, T)

Registers a typed IActivityMonitorClient. Duplicate IActivityMonitorClient instances are ignored.

Declaration

public static T RegisterClient<T>(this IActivityMonitorOutput this, T client)where T : IActivityMonitorClient

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput object.
T	client	Client to register.

Returns

Type	Description
T	The registered client.

Type Parameters

Name	Description
T	Any type that specializes IActivityMonitorClient.

RegisterClients(IActivityMonitorOutput, IActivityMonitorClient[])

Registers multiple IActivityMonitorClient. Duplicate IActivityMonitorClient instances are ignored.

Declaration

public static IActivityMonitorOutput RegisterClients(this IActivityMonitorOutput this, params IActivityMonitorClient[] clients)

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput object.
IActivityMonitorClient[]	clients	Multiple clients to register.

Returns

Type	Description
IActivityMonitorOutput	This registrar to enable fluent syntax.

RegisterClients(IActivityMonitorOutput, IEnumerable<IActivityMonitorClient>)

Registers multiple IActivityMonitorClient. Duplicate IActivityMonitorClient instances are ignored.

Declaration

public static IActivityMonitorOutput RegisterClients(this IActivityMonitorOutput this, IEnumerable<IActivityMonitorClient> clients)

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput object.
IEnumerable<IActivityMonitorClient>	clients	Multiple clients to register.

Returns

Type	Description
IActivityMonitorOutput	This registrar to enable fluent syntax.

RegisterUniqueClient<T>(IActivityMonitorOutput)

Registers a unique client for a type that must have a public default constructor. CreateInstance<T>() is called if necessary.

Declaration

public static T RegisterUniqueClient<T>(this IActivityMonitorOutput this)where T : IActivityMonitorClient, new ()

Parameters

Type	Name	Description
IActivityMonitorOutput	this

Returns

Type	Description
T	The found or newly created client.

Type Parameters

Name	Description
T

ShouldLogGroup(IActivityMonitor, LogLevel, String, Int32)

Challenges source filters based on FileName/LineNumber, ActualFilter and application domain's DefaultFilter filters to test whether a log group should actually be emitted.

Declaration

public static bool ShouldLogGroup(this IActivityMonitor this, LogLevel level, string fileName = null, int lineNumber = 0)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
LogLevel	level	Log level.
String	fileName	Source file name of the emitter (automatically injected by C# compiler but can be explicitly set).
Int32	lineNumber	Line number in the source file (automatically injected by C# compiler but can be explicitly set).

Returns

Type	Description
Boolean	True if the log should be emitted.

ShouldLogLine(IActivityMonitor, LogLevel, String, Int32)

Challenges source filters based on FileName/LineNumber, ActualFilter and application domain's DefaultFilter filters to test whether a log line should actually be emitted.

Declaration

public static bool ShouldLogLine(this IActivityMonitor this, LogLevel level, string fileName = null, int lineNumber = 0)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
LogLevel	level	Log level.
String	fileName	Source file name of the emitter (automatically injected by C# compiler but can be explicitly set).
Int32	lineNumber	Line number in the source file (automatically injected by C# compiler but can be explicitly set).

Returns

Type	Description
Boolean	True if the log should be emitted.

StartDependentActivity(IActivityMonitor, ActivityMonitor.DependentToken, String, Int32)

Starts a dependent activity. This sets the Topic if it is not null and opens a group tagged with StartDependentActivity with a message that can be parsed back thanks to TryParseStartMessage(String, out Guid, out DateTimeStamp).

Declaration

public static IDisposable StartDependentActivity(this IActivityMonitor this, ActivityMonitor.DependentToken token, string fileName = null, int lineNumber = 0)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
ActivityMonitor.DependentToken	token	Token that describes the origin of the activity.
String	fileName	Source file name of the emitter (automatically injected by C# compiler but can be explicitly set).
Int32	lineNumber	Line number in the source file (automatically injected by C# compiler but can be explicitly set).

Returns

Type	Description
IDisposable	A disposable object. It must be disposed at the end of the activity.

TemporarilySetAutoTags(IActivityMonitor, CKTrait, SetOperation)

Alter tags of this IActivityMonitor. Current AutoTags will be automatically restored when the returned IDisposable will be disposed. Even if, when a Group is closed, the IActivityMonitor.AutoTags is automatically restored to its original value (captured when the Group was opened), this may be useful to locally change the tags level without bothering to restore the initial value (this is close to what OpenGroup/CloseGroup do with both the MinimalFilter and the AutoTags).

Declaration

public static IDisposable TemporarilySetAutoTags(this IActivityMonitor this, CKTrait tags, SetOperation operation = SetOperation.Union)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor object.
CK.Core.CKTrait	tags	Tags to combine with the current one.
CK.Core.SetOperation	operation	Defines the way the new tags must be combined with current ones.

Returns

Type	Description
IDisposable	A IDisposable object that will restore the current tag when disposed.

TemporarilySetMinimalFilter(IActivityMonitor, LogFilter)

Sets a filter level on this IActivityMonitor. The current MinimalFilter will be automatically restored when the returned IDisposable will be disposed. Even if, when a Group is closed, the IActivityMonitor.Filter is automatically restored to its original value (captured when the Group was opened), this may be useful to locally change the filter level without bothering to restore the initial value (this is what OpenGroup/CloseGroup do with both the Filter and the AutoTags).

Declaration

public static IDisposable TemporarilySetMinimalFilter(this IActivityMonitor this, LogFilter f)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor object.
LogFilter	f	The new filter.

Returns

Type	Description
IDisposable	A IDisposable object that will restore the current level.

TemporarilySetMinimalFilter(IActivityMonitor, LogLevelFilter, LogLevelFilter)

Sets filter levels on this IActivityMonitor. The current MinimalFilter will be automatically restored when the returned IDisposable will be disposed. Note that even if closing a Group automatically restores the IActivityMonitor.MinimalFilter to its original value (captured when the Group was opened), this may be useful to locally change the filter level without bothering to restore the initial value (this is what OpenGroup/CloseGroup do with both the Filter and the AutoTags).

Declaration

public static IDisposable TemporarilySetMinimalFilter(this IActivityMonitor this, LogLevelFilter group, LogLevelFilter line)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor object.
LogLevelFilter	group	The new filter level for group.
LogLevelFilter	line	The new filter level for log line.

Returns

Type	Description
IDisposable	A IDisposable object that will restore the current level.

ToStringGroupConclusion(IEnumerable<ActivityLogGroupConclusion>, String)

Gets this Group conclusions as a readable string.

Declaration

public static string ToStringGroupConclusion(this IEnumerable<ActivityLogGroupConclusion> this, string conclusionSeparator = " - ")

Parameters

Type	Name	Description
IEnumerable<ActivityLogGroupConclusion>	this	This group conclusion. Can be null.
String	conclusionSeparator	Conclusion separator.

Returns

Type	Description
String	A lovely concatenated string of conclusions.

ToStringPath(IEnumerable<ActivityMonitorPathCatcher.PathElement>, String, String, String, String, String, String, String, String, String, String)

Gets the path as a readable string.

Declaration

public static string ToStringPath(this IEnumerable<ActivityMonitorPathCatcher.PathElement> this, string elementSeparator = "> ", string withoutConclusionFormat = "{0}{1} ", string withConclusionFormat = "{0}{1} -{{ {2} }}", string conclusionSeparator = " - ", string fatal = "[Fatal]- ", string error = "[Error]- ", string warn = "[Warning]- ", string info = "[Info]- ", string trace = "", string debug = "[Debug]- ")

Parameters

Type	Name	Description
IEnumerable<ActivityMonitorPathCatcher.PathElement>	this	This path. Can be null.
String	elementSeparator	Between elements.
String	withoutConclusionFormat	There must be 3 placeholders {0} for the level, {1} for the text and {2} for the conclusion.
String	withConclusionFormat	There must be 2 placeholders {0} for the level and {1} for the text.
String	conclusionSeparator	Conclusion separator.
String	fatal	For Fatal errors.
String	error	For Errors.
String	warn	For Warnings.
String	info	For Infos.
String	trace	For Traces.
String	debug	For Debugs.

Returns

Type	Description
String	A lovely path.

UnbridgeTo(IActivityMonitorOutput, ActivityMonitorBridgeTarget)

Removes an existing ActivityMonitorBridge to another monitor if it exists (silently ignores it if not found).

Declaration

public static ActivityMonitorBridge UnbridgeTo(this IActivityMonitorOutput this, ActivityMonitorBridgeTarget targetBridge)

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput.
ActivityMonitorBridgeTarget	targetBridge	The target bridge that will no more receive our logs.

Returns

Type	Description
ActivityMonitorBridge	The unregistered ActivityMonitorBridge if found, null otherwise.

UnfilteredLog(IActivityMonitor, CKTrait, LogLevel, String, DateTimeStamp, Exception, String, Int32)

Logs a text regardless of ActualFilter level.

Declaration

public static void UnfilteredLog(this IActivityMonitor this, CKTrait tags, LogLevel level, string text, DateTimeStamp logTime, Exception ex, string fileName = null, int lineNumber = 0)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
CK.Core.CKTrait	tags	Tags (from ActivityMonitor.Tags) to associate to the log. These tags will be union-ed with the current AutoTags.
LogLevel	level	Log level. Must not be None.
String	text	Text to log. Must not be null or empty.
CK.Core.DateTimeStamp	logTime	Time-stamp of the log entry. You can use CK.Core.DateTimeStamp.UtcNow or NextLogTime(IActivityMonitor) extension method.
Exception	ex	Optional exception associated to the log. When not null, a Group is automatically created.
String	fileName	The source code file name from which the log is emitted.
Int32	lineNumber	The line number in the source from which the log is emitted.

Remarks

The text can not be null or empty.

Each call to log is considered as a unit of text: depending on the rendering engine, a line or a paragraph separator (or any appropriate separator) should be appended between each text if the level is the same as the previous one.

If needed, the special text ParkLevel ("PARK-LEVEL") can be used as a convention to break the current LogLevel and resets it: the next log, even with the same LogLevel, should be treated as if a different LogLevel is used.

UnfilteredOpenGroup(IActivityMonitor, CKTrait, LogLevel, Func<String>, String, DateTimeStamp, Exception, String, Int32)

Opens a group regardless of ActualFilter level. CloseGroup(IActivityMonitor, Object) must be called in order to close the group, and/or the returned object must be disposed (both safely can be called: the group is closed on the first action, the second one is ignored).

Declaration

public static IDisposable UnfilteredOpenGroup(this IActivityMonitor this, CKTrait tags, LogLevel level, Func<string> getConclusionText, string text, DateTimeStamp logTime, Exception ex, string fileName = null, int lineNumber = 0)

Parameters

Type	Name	Description
IActivityMonitor	this	This IActivityMonitor.
CK.Core.CKTrait	tags	Tags (from ActivityMonitor.Tags) to associate to the log. It will be union-ed with current AutoTags.
LogLevel	level	Log level. The None level is used to open a filtered group. See remarks.
Func<String>	getConclusionText	Optional function that will be called on group closing.
String	text	Text to log (the title of the group). Null text is valid and considered as Empty or assigned to the Message if it exists.
CK.Core.DateTimeStamp	logTime	Time of the log entry. You can use CK.Core.DateTimeStamp.UtcNow or NextLogTime(IActivityMonitor) extension method.
Exception	ex	Optional exception associated to the group.
String	fileName	The source code file name from which the group is opened.
Int32	lineNumber	The line number in the source from which the group is opened.

Returns

Type	Description
IDisposable	A disposable object that can be used to close the group.

Remarks

Opening a group does not change the current MinimalFilter, except when opening a Fatal or Error group: in such case, the Filter is automatically sets to Trace to capture all potential information inside the error group.

Changes to the monitor's current Filter or AutoTags that occur inside a group are automatically restored to their original values when the group is closed. This behavior guaranties that a local modification (deep inside unknown called code) does not impact caller code: groups are a way to easily isolate such configuration changes.

Note that this automatic configuration restoration works even if the group is filtered (when the level is None).

UnregisterClient<T>(IActivityMonitorOutput, Func<T, Boolean>)

Unregisters the first IActivityMonitorClient from the Clients list that satisfies the predicate.

Declaration

public static T UnregisterClient<T>(this IActivityMonitorOutput this, Func<T, bool> predicate)where T : IActivityMonitorClient

Parameters

Type	Name	Description
IActivityMonitorOutput	this	This IActivityMonitorOutput.
Func<T, Boolean>	predicate	A predicate that will be used to determine the first client to unregister.

Returns

Type	Description
T	The unregistered client, or null if no client has been found.

Type Parameters

Name	Description
T