diff --git a/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/etwtrace.csproj b/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/etwtrace.csproj index 0bcc5100df7..a15a29bf12c 100644 --- a/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/etwtrace.csproj +++ b/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/etwtrace.csproj @@ -2,7 +2,7 @@ Exe - netcoreapp5.0 + net10.0 - \ No newline at end of file + diff --git a/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/etwtrace.vbproj b/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/etwtrace.vbproj new file mode 100644 index 00000000000..a15a29bf12c --- /dev/null +++ b/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/etwtrace.vbproj @@ -0,0 +1,8 @@ + + + + Exe + net10.0 + + + diff --git a/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb b/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb index 4b1ff312cc4..b2f97954965 100644 --- a/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb +++ b/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb @@ -6,7 +6,7 @@ Enum MyColor Red Yellow Blue -End Enum 'MyColor +End Enum 'MyColor _ Class MyCompanyEventSource Inherits EventSource @@ -117,4 +117,4 @@ Class Program ' End Sub End Class -' \ No newline at end of file +' diff --git a/xml/System.Diagnostics.Tracing/EventAttribute.xml b/xml/System.Diagnostics.Tracing/EventAttribute.xml index 1f82db48fa8..e3015ffa9e6 100644 --- a/xml/System.Diagnostics.Tracing/EventAttribute.xml +++ b/xml/System.Diagnostics.Tracing/EventAttribute.xml @@ -59,28 +59,17 @@ Specifies additional event schema information for an event. - -derived class, you must call the method on the base class, passing the event ID, followed by the same arguments as the defined method is passed. You should follow the pattern shown in the following examples. - - - -## Examples - The following example shows how to use the class to define a variety of events. This code example is part of a larger example provided for the class. - + -derived class, you must call the method on the base class, passing the event ID, followed by the same arguments as the defined method is passed. Follow the pattern shown in the examples. + +## Examples + +The following example shows how to use the class to define an event. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet6"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet7"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: + ]]> @@ -126,17 +115,17 @@ The event identifier for the event. Initializes a new instance of the class with the specified event identifier. - constructor to specify events. This code example is part of a larger example provided for the class. - + constructor to specify events. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet2"::: + ]]> @@ -264,11 +253,10 @@ Gets or sets the identifier for the event. The event identifier. This value should be between 0 and 65535. - should be greater than 0 or less than 65535 or errors can occur in a tracing operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - + should be greater than 0 or less than 65535 or errors can occur in a tracing operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. + ]]> @@ -314,23 +302,17 @@ Gets or sets the keywords for the event. A bitwise combination of the enumeration values. - property to define event keywords. This code example is part of a larger example provided for the class. - + property to define event keywords. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet6"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: + ]]> @@ -376,20 +358,15 @@ Gets or sets the level for the event. One of the enumeration values that specifies the level for the event. - property to specify event levels. This code example is part of a larger example provided for the class. - + property to specify an event level. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet6"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: + ]]> @@ -436,31 +413,22 @@ Gets or sets the message for the event. The message for the event. - property to specify event messages. This code example is part of a larger example provided for the class. - + property to specify an event message. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet6"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: + ]]> @@ -506,20 +474,18 @@ Gets or sets the operation code for the event. One of the enumeration values that specifies the operation code. - property to specify operation codes. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet8"::: - + property to specify operation codes. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet9"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet10"::: + ]]> @@ -606,20 +572,18 @@ Gets or sets the task for the event. The task for the event. - property to define event tasks. This code example is part of a larger example provided for the class. - + property to define event tasks. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet4"::: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet9"::: + ]]> diff --git a/xml/System.Diagnostics.Tracing/EventKeywords.xml b/xml/System.Diagnostics.Tracing/EventKeywords.xml index 676a72d3d3a..36c562597c4 100644 --- a/xml/System.Diagnostics.Tracing/EventKeywords.xml +++ b/xml/System.Diagnostics.Tracing/EventKeywords.xml @@ -54,19 +54,19 @@ Defines the standard keywords that apply to events. - class to redefine event keywords. This code example is part of a larger example provided for the class. - + class to redefine event keywords. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Diagnostics.Tracing/EventLevel.xml b/xml/System.Diagnostics.Tracing/EventLevel.xml index 9e9dd867311..c2d133ef942 100644 --- a/xml/System.Diagnostics.Tracing/EventLevel.xml +++ b/xml/System.Diagnostics.Tracing/EventLevel.xml @@ -48,29 +48,26 @@ Identifies the level of an event. - class. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: + +The following example shows how to use the `Informational` enumeration member to identify an informational message. This example is part of a larger example provided for the class. -The following example shows how to use the `Informational` enumeration member to identify an informational message. This example is part of a larger example provided for the class. - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet6"::: + +The following example shows how to use the `Verbose` enumeration member to identify a verbose message. This example is part of a larger example provided for the class. -The following example shows how to use the `Verbose` enumeration member to identify a verbose message. This example is part of a larger example provided for the class. - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet11"::: ]]> diff --git a/xml/System.Diagnostics.Tracing/EventOpcode.xml b/xml/System.Diagnostics.Tracing/EventOpcode.xml index 12bc4bd9faa..78640c03ef1 100644 --- a/xml/System.Diagnostics.Tracing/EventOpcode.xml +++ b/xml/System.Diagnostics.Tracing/EventOpcode.xml @@ -48,17 +48,17 @@ Defines the standard operation codes that the event source attaches to events. - class. - +The following example shows how to use the `Start` enumeration member to specify a start operation. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet7"::: - -The following example shows how to use the `Stop` enumeration member to specify a stop operation. This example is part of a larger example provided for the class. - +:::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet7"::: + +The following example shows how to use the `Stop` enumeration member to specify a stop operation. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet8"::: diff --git a/xml/System.Diagnostics.Tracing/EventSource.xml b/xml/System.Diagnostics.Tracing/EventSource.xml index 22a8e1c499a..3d837d8b017 100644 --- a/xml/System.Diagnostics.Tracing/EventSource.xml +++ b/xml/System.Diagnostics.Tracing/EventSource.xml @@ -254,11 +254,9 @@ Creates a new instance of the class with the specified name. attribute on that type. Otherwise, the GUIDs returned by the property and the method will be different. If the event source names differ, the property returns the GUID used to register this EventSource with ETW. - ]]> @@ -1304,7 +1302,7 @@ In such cases, the GUID that is used to register the @@ -1358,7 +1356,7 @@ In such cases, the GUID that is used to register the if the event source is enabled for the specified event level, keywords and channel; otherwise, . - The result of this method is only an approximation of whether a particular event is active. Use it to avoid expensive computation for logging when logging is disabled. Event sources may have additional filtering that determines their activity. + The result of this method is only an approximation of whether a particular event is active. Use it to avoid expensive computation for logging when logging is disabled. Event sources may have additional filtering that determines their activity. The friendly name of the class that is derived from the event source. - The friendly name of the derived class. The default is the simple name of the class. + The friendly name of the derived class. The default is the simple name of the class. To be added. @@ -1523,7 +1521,7 @@ In such cases, the GUID that is used to register the forwards the command to the callback. What the does with the command and its arguments is specific to the event source. The command and command arguments are passed to the callback of the specified event source. If possible, the current event source should not affect other event listeners' filtering events; however, that may not be possible if the command causes a garbage collection, a system flush, or some other global activity. + Calling forwards the command to the callback. What the does with the command and its arguments is specific to the event source. The command and command arguments are passed to the callback of the specified event source. If possible, the current event source should not affect other event listeners' filtering events; however, that may not be possible if the command causes a garbage collection, a system flush, or some other global activity. ]]> @@ -2304,10 +2302,9 @@ public void Info1(string arg1) } ``` - - ## Examples - The following example shows how to use this method overload to write an event. This code example is part of a larger example provided for the class. + + The following example shows how to use this method overload to write an event. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: @@ -2363,7 +2360,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A byte array argument. Writes an event by using the provided event identifier and byte array argument. @@ -2475,16 +2472,15 @@ public void Info1(byte[] arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. An integer argument. Writes an event by using the provided event identifier and 32-bit integer argument. -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. +When you implement a method that is identified as an ETW event in an -derived class. You must call the base class method passing the and the same arguments as the implemented method similar to the following example. ```csharp [Event(2, Level = EventLevel.Informational)] @@ -2494,10 +2490,9 @@ public void Info1(int arg1) } ``` - - ## Examples - The following example shows how to use this method overload to write an event. This code example is part of a larger example provided for the class. + + The following example shows how to use this method overload to write an event. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet8"::: @@ -2554,7 +2549,7 @@ public void Info1(int arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A 64 bit integer argument. Writes an event by using the provided event identifier and 64-bit integer argument. @@ -2641,7 +2636,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. An array of objects. Writes an event by using the provided event identifier and array of arguments. @@ -2650,15 +2645,15 @@ public void Info1(string arg1) ## Remarks By default, the compiler calls this overload if the parameters for the call do not match one of the other method overloads. This overload is much slower than the other overloads, because it does the following: -1. It allocates an array to hold the variable argument. +1. It allocates an array to hold the variable argument. -2. It casts each parameter to an object (which causes allocations for primitive types). +2. It casts each parameter to an object (which causes allocations for primitive types). -3. It assigns these objects to the array. +3. It assigns these objects to the array. -4. It calls the function, which then determines the type of each argument so it can be serialized for ETW. +4. It calls the function, which then determines the type of each argument so it can be serialized for ETW. - The high overhead for this overload is not significant when tracing low-volume events, because the method is used only when the provider is enabled. However, for high-volume events, the performance overhead can be significant. You can avoid using for high-volume payloads by creating a new, faster overload with the method. + The high overhead for this overload is not significant when tracing low-volume events, because the method is used only when the provider is enabled. However, for high-volume events, the performance overhead can be significant. You can avoid using for high-volume payloads by creating a new, faster overload with the method. `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. @@ -2725,7 +2720,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A string argument. Writes an event by using the provided event identifier and string argument. @@ -2744,10 +2739,9 @@ public void Info1(string arg1) } ``` - - ## Examples - The following example shows how to use this method overload to write an event. This code example is part of a larger example provided for the class. + +The following example shows how to use this method overload to write an event. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: @@ -2805,7 +2799,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. An integer argument. An integer argument. Writes an event by using the provided event identifier and 32-bit integer arguments. @@ -2932,7 +2926,7 @@ public void Info1(int arg1, int arg2, int arg3) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A 64-bit integer argument. A byte array argument. Writes the event data using the specified identifier and 64-bit integer and byte array arguments. @@ -3005,7 +2999,7 @@ public void Info1(Int64 arg1, Byte[] arg2) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A 64 bit integer argument. A 64 bit integer argument. Writes an event by using the provided event identifier and 64-bit arguments. @@ -3077,7 +3071,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A 64-bit integer argument. A string argument. Writes an event by using the provided event identifier and 64-bit integer, and string arguments. @@ -3151,7 +3145,7 @@ public void Info1(Int64 arg1, string arg2) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A string argument. A 32 bit integer argument. Writes an event by using the provided event identifier and arguments. @@ -3225,7 +3219,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A string argument. A 64 bit integer argument. Writes an event by using the provided event identifier and arguments. @@ -3299,7 +3293,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A string argument. A string argument. Writes an event by using the provided event identifier and string arguments. @@ -3373,7 +3367,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. An integer argument. An integer argument. An integer argument. @@ -3448,7 +3442,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A 64 bit integer argument. A 64 bit integer argument. A 64 bit integer argument. @@ -3524,7 +3518,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A string argument. A 32 bit integer argument. A 32 bit integer argument. @@ -3600,7 +3594,7 @@ public void Info1(string arg1) - The event identifier. This value should be between 0 and 65535. + The event identifier. This value should be between 0 and 65535. A string argument. A string argument. A string argument. @@ -3691,7 +3685,7 @@ public void Info1(string arg1) ## Remarks `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. - This protected method enables users to define new overloads that are faster than the provided overloads. Creating a new overload involves unsafe code. The basic procedure is to stack-allocate an array of event data descriptors that matches the number of payload items. For each payload item, set the correct size and value in the event data array.Call with the initialized array. + This protected method enables users to define new overloads that are faster than the provided overloads. Creating a new overload involves unsafe code. The basic procedure is to stack-allocate an array of event data descriptors that matches the number of payload items. For each payload item, set the correct size and value in the event data array.Call with the initialized array. The following example shows how to add a overload that accepts four arguments. An example would be if you have a logging event that logs a string and 3 integers. @@ -3917,18 +3911,15 @@ fixed(byte* ptr = arg) Your ETW event method calling this function must follow these guidelines: -1. Specify the first parameter as a named `relatedActivityId`. - -2. Specify either or as the property. - -3. Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. +- Specify the first parameter as a named `relatedActivityId`. +- Specify either or as the property. +- Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. If `args` is not used, it is converted to an empty array for the resulting call to ETW. - - ## Examples - The following code example shows how you might can specify an event source that calls . + +The following code example shows how you might can specify an event source that calls . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventSource/WriteEventWithRelatedActivityId/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventSource/WriteEventWithRelatedActivityId/module1.vb" id="Snippet1"::: @@ -4013,16 +4004,15 @@ fixed(byte* ptr = arg) Your ETW event method calling this function must follow these guidelines: -1. Specify the first parameter as a named `relatedActivityId`. - -2. Specify either or as the property. - -3. Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. +- Specify the first parameter as a named `relatedActivityId`. +- Specify either or as the property. +- Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. This method uses the same rules as for the `args` parameter. See WriteEventCore documentation for more details. ## Examples - The following C# code example shows how to define a method overload that calls . + +The following C# code example shows how to define a method overload that calls . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventSource/WriteEventWithRelatedActivityId/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventSource/WriteEventWithRelatedActivityId/module1.vb" id="Snippet5"::: diff --git a/xml/System.Diagnostics.Tracing/EventTask.xml b/xml/System.Diagnostics.Tracing/EventTask.xml index 81c93d89a91..f0779b3fbd9 100644 --- a/xml/System.Diagnostics.Tracing/EventTask.xml +++ b/xml/System.Diagnostics.Tracing/EventTask.xml @@ -48,19 +48,19 @@ Defines the tasks that apply to events. - class to define event tasks. This code example is part of a larger example provided for the class. - + class to define event tasks. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Net.Mail/MailAddress.xml b/xml/System.Net.Mail/MailAddress.xml index 344f47d5854..4ead79a9a4d 100644 --- a/xml/System.Net.Mail/MailAddress.xml +++ b/xml/System.Net.Mail/MailAddress.xml @@ -51,26 +51,25 @@ class is used by the and classes to store address information for email messages. -A mail address is composed of a name, name and optionally, a . The can contain non-ASCII characters if you encode them. +A mail address is composed of a [user name](xref:System.Net.Mail.MailAddress.User), [host name](xref:System.Net.Mail.MailAddress.Host), and an optional [display name](xref:System.Net.Mail.MailAddress.DisplayName). can contain non-ASCII characters if you encode them. The class supports the following mail address formats: -- A simple address format of `user@host`. If a is not set, this is the mail address format generated. -- A standard quoted display name format of `"display name" `. If a is set, this is the format generated. +- A simple address format of `user@host`. If a is not set, this is the mail address format that's generated. +- A standard quoted display name format of `"display name" `. If a is set, this is the format that's generated. - - Angle brackets are added around the name and name, if these are not included. For example, `"display name" user@host` is changed to `"display name" `. - - Quotes are added around the , if these are not included. For example, `display name ` is changed to `"display name" `. - - Unicode characters are supported in the property. + - If they're not already included, angle brackets are added around the name and name. For example, `"display name" user@host` is changed to `"display name" `. + - If they're not already included, quotes are added around the . For example, `display name ` is changed to `"display name" `. + - Unicode characters are supported in the property. Within these two formats, the following elements are allowed: -- A name with quotes. For example, `"user name"@host`. -- Consecutive and trailing dots in user names. For example, `user...name..@host`. +- A name with quotes. For example, `"user name"@host`. - Bracketed domain literals. For example, ``. - Comments. For example, `(comment)"display name"(comment)<(comment)user(comment)@(comment)domain(comment)>(comment)`. Comments are removed before transmission. +- .NET 9 and earlier ONLY: Consecutive and trailing dots in user names. For example, `user...name..@host`. (Starting in .NET 10, consecutive dots aren't allowed.) A comma is used to separate elements in a list of mail addresses. As a result, a comma should not be used in unquoted display names in a list. The following mail addresses would be allowed: @@ -90,19 +89,21 @@ The following mail address would not be allowed: `"John "Jr" Doe" ` -When the username is not quoted, all text between the start of the string (or comma) and the address are considered part of the , including comments. For example: +When the username is not quoted, all text between the start of the string (or comma) and the address is considered part of the , including comments. For example: `(non comment) unquoted display (non comment) name (non comment) ` -Although the class accepts a mail address as valid, other mail servers may not accept the mail address. +Although the class accepts a mail address as valid, other mail servers might not accept the mail address. The class does not support the following mail address formats: - Mixed quoted and unquoted display names. For example, `display "name" `. - Groups, as defined in RFC 2822 Section 3.4 published by the IETF. - The obsolete user name formats of `"user"."name"@host`, `user."name"@host` or `"user".name@host`. +- .NET 10 and later versions only: Consecutive dots in the user name, for example, `user...name@host.com`. ## Examples + The following code example demonstrates sending an email message by using the , , and classes. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: @@ -167,28 +168,26 @@ The following code example demonstrates sending an email message by using the "` +The `address` parameter can contain a display name and the associated email address if you enclose the address in angle brackets. For example: - White space is permitted between the display name and the angle brackets. +`"Tom Smith "` - The following table shows the property values for a object constructed using the preceding example address. - -|Property|Value| -|--------------|-----------| -||`"Tom Smith"`| -||`"contoso.com"`| -||`"tsmith"`| -||`"tsmith@contoso.com"`| +White space is permitted between the display name and the angle brackets. +The following table shows the property values for a object constructed using the preceding example address. +| Property | Value | +| ---------------------------------------------- | ---------------------- | +| | `"Tom Smith"` | +| | `"contoso.com"` | +| | `"tsmith"` | +| | `"tsmith@contoso.com"` | ## Examples - The following code example uses this constructor to create a object for the recipient of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: +The following code example uses this constructor to create a object for the recipient of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: ]]> @@ -256,19 +255,17 @@ The following code example demonstrates sending an email message by using the , `displayName` overrides the value specified in `address`. +Leading and trailing white space in the display name is preserved. +If `displayName` contains non-ASCII characters, the iso-8859-1 character set is used for the `displayName` encoding. Encoding non-ASCII characters is discussed in RFC 1522, which is available at [https://www.ietf.org/](https://www.ietf.org/). +If `address` contains a display name, and `displayName` is not `null` and is not equal to , `displayName` overrides the value specified in `address`. ## Examples - The following code example uses this constructor to create instances for the sender and recipient of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: +The following code example uses this constructor to create instances for the sender and recipient of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: ]]> @@ -336,22 +333,20 @@ The following code example demonstrates sending an email message by using the , `displayName` overrides the value specified in `address`. - - The method does not check if the `displayName` parameter is valid. This method removes surrounding quotes not displayed by the property. Quotes will be added before transmission, except where or is specified in the `displayNameEncoding` parameter. The encoding specified in the `displayNameEncoding` parameter will be applied to the property before transmission or is specified in the `displayNameEncoding` parameter. is the default encoding if none is specified. - - For more information on supported mail address formats, see . +If `address` contains a display name, and `displayName` is not `null` and is not equal to , `displayName` overrides the value specified in `address`. +The constructor does not check if the `displayName` parameter is valid. This method removes surrounding quotes not displayed by the property. Quotes will be added before transmission, except where or is specified in the `displayNameEncoding` parameter. The encoding specified in the `displayNameEncoding` parameter will be applied to the property before transmission or is specified in the `displayNameEncoding` parameter. is the default encoding if none is specified. +For more information on supported mail address formats, see . ## Examples - The following code example uses this constructor to create instances for the sender of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/MailAddress/.ctor/mailasync.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailAddress/.ctor/mailasync.vb" id="Snippet2"::: +The following code example uses this constructor to create instances for the sender of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/MailAddress/.ctor/mailasync.cs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailAddress/.ctor/mailasync.vb" id="Snippet2"::: ]]> @@ -415,15 +410,13 @@ The following code example demonstrates sending an email message by using the information. - - +The value returned by this property does not include the information. ## Examples - The following code example displays the address for an email message recipient. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: +The following code example displays the address for an email message recipient. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: ]]> @@ -475,17 +468,15 @@ The following code example demonstrates sending an email message by using the method to get the encoded form of the . - - Some software programs that are used to read email display the property value instead of, or in addition to, the email address. - +Display names that contain non-ASCII characters are returned in human-readable form. Use the method to get the encoded form of the . +Some software programs that are used to read email display the property value instead of, or in addition to, the email address. ## Examples - The following code example displays the for the recipient of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: +The following code example displays the for the recipient of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: ]]> @@ -585,8 +576,7 @@ The following code example demonstrates sending an email message by using the method returns a hash code of the mail address. This value can be used as a key in hash tables. +The method returns a hash code of the mail address. This value can be used as a key in hash tables. ]]> @@ -638,15 +628,13 @@ The following code example demonstrates sending an email message by using the @@ -693,19 +681,17 @@ The following code example demonstrates sending an email message by using the property is not `null` and not equal to (""), returns a string composed using the following syntax: - - \<@> - - If is `null` or is equal to , returns the value of the property. +The string returned by this method is not necessarily identical to the string specified when the instance was created. If the property is not `null` and not equal to (""), returns a string composed using the following syntax: + \<@> +If is `null` or is equal to , returns the value of the property. ## Examples - The following code example displays the destination of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet7"::: +The following code example displays the destination of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet7"::: ]]> @@ -916,15 +902,13 @@ The following code example demonstrates sending an email message by using the