167 lines
6.3 KiB
Markdown
167 lines
6.3 KiB
Markdown
# <a id="CapyKit_CapyEventReporter"></a> Class CapyEventReporter
|
|
|
|
Namespace: [CapyKit](CapyKit.md)
|
|
Assembly: CapyKit.dll
|
|
|
|
The CapyEventReporter class is responsible for managing event subscriptions and emissions within CapyKit.
|
|
|
|
```csharp
|
|
public static class CapyEventReporter
|
|
```
|
|
|
|
#### Inheritance
|
|
|
|
[object](https://learn.microsoft.com/dotnet/api/system.object) ←
|
|
[CapyEventReporter](CapyKit.CapyEventReporter.md)
|
|
|
|
#### Inherited Members
|
|
|
|
[object.Equals\(object?\)](https://learn.microsoft.com/dotnet/api/system.object.equals\#system\-object\-equals\(system\-object\)),
|
|
[object.Equals\(object?, object?\)](https://learn.microsoft.com/dotnet/api/system.object.equals\#system\-object\-equals\(system\-object\-system\-object\)),
|
|
[object.GetHashCode\(\)](https://learn.microsoft.com/dotnet/api/system.object.gethashcode),
|
|
[object.GetType\(\)](https://learn.microsoft.com/dotnet/api/system.object.gettype),
|
|
[object.MemberwiseClone\(\)](https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone),
|
|
[object.ReferenceEquals\(object?, object?\)](https://learn.microsoft.com/dotnet/api/system.object.referenceequals),
|
|
[object.ToString\(\)](https://learn.microsoft.com/dotnet/api/system.object.tostring)
|
|
|
|
#### Extension Methods
|
|
|
|
[ObjectExtensions.UpdateProperties\(object, object\)](CapyKit.Extensions.ObjectExtensions.md\#CapyKit\_Extensions\_ObjectExtensions\_UpdateProperties\_System\_Object\_System\_Object\_)
|
|
|
|
## Remarks
|
|
|
|
Because consumers of CapyKit may have varied ways of handling logging, the <xref href="CapyKit.CapyEventReporter" data-throw-if-not-resolved="false"></xref> provides
|
|
a way for subscribers to recieve events for various "events" within the library. These can be thought of as
|
|
a logging solution for CapyKit. Consumers are free to treat these events however they see fit.
|
|
|
|
## Methods
|
|
|
|
### <a id="CapyKit_CapyEventReporter_EmitEvent_CapyKit_EventLevel_System_String_System_String_System_Object___"></a> EmitEvent\(EventLevel, string, string, params object\[\]\)
|
|
|
|
Emits an event with the given severity level, message, and method name.
|
|
|
|
```csharp
|
|
public static void EmitEvent(EventLevel eventLevel, string message, string method = null, params object[] args)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`eventLevel` [EventLevel](CapyKit.EventLevel.md)
|
|
|
|
The severity level of the event.
|
|
|
|
`message` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The message describing the reason for the event. String formatting for <code class="paramref">args</code>
|
|
is accepted.
|
|
|
|
`method` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
(Optional) The name of the method where the event was raised.
|
|
|
|
`args` [object](https://learn.microsoft.com/dotnet/api/system.object)\[\]
|
|
|
|
A variable-length parameters list containing arguments for formatting the message.
|
|
|
|
#### Examples
|
|
|
|
<pre><code class="lang-csharp">CapyEventReporter.EmitEvent(EventLevel.Error, "Could not find the description for {0}.", args: new[] { enumeration });</code></pre>
|
|
|
|
#### Remarks
|
|
|
|
In order to allow for efficient calling member access via <xref href="System.Runtime.CompilerServices.CallerMemberNameAttribute" data-throw-if-not-resolved="false"></xref>
|
|
, it is suggested that <code class="paramref">args</code> is defined explicitly for formatted messages.
|
|
|
|
#### See Also
|
|
|
|
[CallerMemberNameAttribute](https://learn.microsoft.com/dotnet/api/system.runtime.compilerservices.callermembernameattribute)
|
|
|
|
### <a id="CapyKit_CapyEventReporter_EmitEventOnce_CapyKit_EventLevel_System_String_System_String_System_String_System_Object___"></a> EmitEventOnce\(EventLevel, string, string, string, params object\[\]\)
|
|
|
|
Emits an event with the given severity level, message, unique identifier, and method name one
|
|
time.
|
|
|
|
```csharp
|
|
public static void EmitEventOnce(EventLevel eventLevel, string message, string uniqueIdentifier, string method = null, params object[] args)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`eventLevel` [EventLevel](CapyKit.EventLevel.md)
|
|
|
|
The severity level of the event.
|
|
|
|
`message` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The message describing the reason for the event. String formatting for <code class="paramref">args</code>
|
|
is accepted.
|
|
|
|
`uniqueIdentifier` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
A unique identifier for the event emission.
|
|
|
|
`method` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
(Optional) The name of the method where the event was raised.
|
|
|
|
`args` [object](https://learn.microsoft.com/dotnet/api/system.object)\[\]
|
|
|
|
A variable-length parameters list containing arguments for formatting the message.
|
|
|
|
#### Remarks
|
|
|
|
This method is similar to EmitEvent(EventLevel, string, string, string, object[])
|
|
, but requires a unique identifier (such as a <xref href="System.Guid" data-throw-if-not-resolved="false"></xref>) to prevent duplicate
|
|
emissions.
|
|
|
|
#### See Also
|
|
|
|
[CallerMemberNameAttribute](https://learn.microsoft.com/dotnet/api/system.runtime.compilerservices.callermembernameattribute),
|
|
[Guid](https://learn.microsoft.com/dotnet/api/system.guid)
|
|
|
|
### <a id="CapyKit_CapyEventReporter_Subscribe_CapyKit_CapyEventHandler_CapyKit_EventLevel_System_String_"></a> Subscribe\(CapyEventHandler, EventLevel, string\)
|
|
|
|
Subscribes the specified event handler to the event with the given subscription level and
|
|
origin.
|
|
|
|
```csharp
|
|
public static void Subscribe(CapyEventHandler callback, EventLevel subscriptionLevel, string origin = null)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`callback` [CapyEventHandler](CapyKit.CapyEventHandler.md)
|
|
|
|
The event handler to subscribe.
|
|
|
|
`subscriptionLevel` [EventLevel](CapyKit.EventLevel.md)
|
|
|
|
The severity level of the event to subscribe to.
|
|
|
|
`origin` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
(Optional) The name of the method or class where the subscription is made.
|
|
|
|
#### Remarks
|
|
|
|
If there is no existing list for the given subscription level, a new list is created and
|
|
added to the dictionary.
|
|
|
|
### <a id="CapyKit_CapyEventReporter_Unsubscribe_CapyKit_CapyEventHandler_System_String_"></a> Unsubscribe\(CapyEventHandler, string\)
|
|
|
|
Unsubscribes the specified event handler from the event with the given origin.
|
|
|
|
```csharp
|
|
public static void Unsubscribe(CapyEventHandler callback, string origin)
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
`callback` [CapyEventHandler](CapyKit.CapyEventHandler.md)
|
|
|
|
The event handler to unsubscribe.
|
|
|
|
`origin` [string](https://learn.microsoft.com/dotnet/api/system.string)
|
|
|
|
The name of the method or class where the subscription was made.
|
|
|