summaryrefslogtreecommitdiff
path: root/src/mscorlib/src/System/Diagnostics/Eventing/TraceLogging/EventDataAttribute.cs
blob: cdedf13c641750231766843f2a0da729f9faac25 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

using System;

#if ES_BUILD_STANDALONE
namespace Microsoft.Diagnostics.Tracing
#else
namespace System.Diagnostics.Tracing
#endif
{
    /// <summary>
    /// Used when authoring types that will be passed to EventSource.Write.
    /// EventSource.Write&lt;T> only works when T is either an anonymous type
    /// or a type with an [EventData] attribute. In addition, the properties
    /// of T must be supported property types. Supported property types include
    /// simple built-in types (int, string, Guid, DateTime, DateTimeOffset,
    /// KeyValuePair, etc.), anonymous types that only contain supported types,
    /// types with an [EventData] attribute, arrays of the above, and IEnumerable
    /// of the above.
    /// </summary>
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct, Inherited = false)]
    public class EventDataAttribute
        : Attribute
    {
        private EventLevel level = (EventLevel)(-1);
        private EventOpcode opcode = (EventOpcode)(-1);

        /// <summary>
        /// Gets or sets the name to use if this type is used for an
        /// implicitly-named event or an implicitly-named property.
        /// 
        /// Example 1:
        /// 
        ///     EventSource.Write(null, new T()); // implicitly-named event
        ///     
        /// The name of the event will be determined as follows:
        /// 
        /// if (T has an EventData attribute and attribute.Name != null)
        ///     eventName = attribute.Name;
        /// else
        ///     eventName = typeof(T).Name;
        ///     
        /// Example 2:
        /// 
        ///     EventSource.Write(name, new { _1 = new T() }); // implicitly-named field
        ///     
        /// The name of the field will be determined as follows:
        /// 
        /// if (T has an EventData attribute and attribute.Name != null)
        ///     fieldName = attribute.Name;
        /// else
        ///     fieldName = typeof(T).Name;
        /// </summary>
        public string Name
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the level to use for the event.
        /// Invalid levels (outside the range 0..255) are treated as unset.
        /// Note that the Level attribute can bubble-up, i.e. if a type contains
        /// a sub-object (a field or property), and the sub-object's type has a
        /// TraceLoggingEvent attribute, the Level from the sub-object's attribute
        /// can affect the event's level.
        /// 
        /// Example: for EventSource.Write(name, options, data), the level of the
        /// event will be determined as follows:
        /// 
        /// if (options.Level has been set)
        ///     eventLevel = options.Level;
        /// else if (data.GetType() has a TraceLoggingEvent attribute and attribute.Level has been set)
        ///     eventLevel = attribute.Level;
        /// else if (a field/property contained in data has a TraceLoggingEvent attribute and attribute.Level has been set)
        ///     eventLevel = attribute.Level;
        /// else
        ///     eventLevel = EventLevel.LogAlways;
        /// </summary>
        internal EventLevel Level
        {
            get { return this.level; }
            set { this.level = value; }
        }

        /// <summary>
        /// Gets or sets the opcode to use for the event.
        /// Invalid opcodes (outside the range 0..255) are treated as unset.
        /// Note that the Opcode attribute can bubble-up, i.e. if a type contains
        /// a sub-object (a field or property), and the sub-object's type has a
        /// TraceLoggingEvent attribute, the Opcode from the sub-object's attribute
        /// can affect the event's opcode.
        /// 
        /// Example: for EventSource.Write(name, options, data), the opcode of the
        /// event will be determined as follows:
        /// 
        /// if (options.Opcode has been set)
        ///     eventOpcode = options.Opcode;
        /// else if (data.GetType() has a TraceLoggingEvent attribute and attribute.Opcode has been set)
        ///     eventOpcode = attribute.Opcode;
        /// else if (a field/property contained in data has a TraceLoggingEvent attribute and attribute.Opcode has been set)
        ///     eventOpcode = attribute.Opcode;
        /// else
        ///     eventOpcode = EventOpcode.Info;
        /// </summary>
        internal EventOpcode Opcode
        {
            get { return this.opcode; }
            set { this.opcode = value; }
        }

        /// <summary>
        /// Gets or sets the keywords to use for the event.
        /// Note that the Keywords attribute can bubble-up, i.e. if a type contains
        /// a sub-object (a field or property), and the sub-object's type has a
        /// TraceLoggingEvent attribute, the Keywords from the sub-object's attribute
        /// can affect the event's keywords.
        /// 
        /// Example: for EventSource.Write(name, options, data), the keywords of the
        /// event will be determined as follows:
        /// 
        /// eventKeywords = options.Keywords;
        /// if (data.GetType() has a TraceLoggingEvent attribute)
        ///     eventKeywords |= attribute.Keywords;
        /// if (a field/property contained in data has a TraceLoggingEvent attribute)
        ///     eventKeywords |= attribute.Keywords;
        /// </summary>
        internal EventKeywords Keywords
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the flags for an event. These flags are ignored by ETW,
        /// but can have meaning to the event consumer.
        /// </summary>
        internal EventTags Tags
        {
            get;
            set;
        }
    }
}