Muokkaa

Jaa

ChannelType Complex Type

  • Artikkeli

Defines a channel to which providers can log events.

<xs:complexType name="ChannelType"
    mixed="true"
>
    <xs:sequence>
        <xs:element name="logging"
            type="ChannelLoggingType"
            minOccurs="0"
         />
        <xs:element name="publishing"
            type="ChannelPublishingType"
            minOccurs="0"
         />
    </xs:sequence>
    <xs:attribute name="name"
        type="anyURI"
        use="required"
     />
    <xs:attribute name="chid"
        type="token"
        use="optional"
     />
    <xs:attribute name="type"
        type="string"
        use="required"
     />
    <xs:attribute name="symbol"
        type="CSymbolType"
        use="optional"
     />
    <xs:attribute name="access"
        type="string"
        use="optional"
     />
    <xs:attribute name="isolation"
        type="string"
        use="optional"
     />
    <xs:attribute name="enabled"
        type="boolean"
        default="false"
        use="optional"
     />
    <xs:attribute name="value"
        type="UInt8Type"
        use="optional"
     />
    <xs:attribute name="message"
        type="string"
        use="optional"
     />
</xs:complexType>

Child elements

Element Type Description
logging ChannelLoggingType Defines the properties of the log file that backs the channel, such as its capacity and whether the log file is sequential or circular.
publishing ChannelPublishingType Defines the logging properties for the session that the channel uses. Only Debug and Analytic channels and channels that use Custom isolation can specify logging properties for their session.

Attributes

Name Type Description
access string A Security Descriptor Definition Language (SDDL) access descriptor that controls access to the log file that backs the channel. If the isolation attribute is set to Application or System, the access descriptor controls read access to the file (the write permissions are ignored). If the isolation attribute is set to Custom, the access descriptor controls write access to the channel and read access to the file.
chid token An identifier that uniquely identifies the channel in the list of channels that the provider defines or imports. Use this value when referencing the channel in an event. If you do not specify a channel identifier, use the channel's name to reference this channel in an event definition.
enabled boolean Determines whether the channel is enabled. Set to true to allow logging to the channel; otherwise, false. The default is false (logging is disabled).
Because Debug and Analytic channel types are high volume channels, you should enable the channel only when investigating an issue with a component that writes to that channel; otherwise, the channel should remain disabled.
Each time you enable a Debug and Analytic channel, the service clears the events from the channel.
isolation string The isolation value defines the default access permissions for the channel. You can specify one of the following values:
  • Application
  • System
  • Custom
The default isolation is Application. The default permissions for Application are (shown using SDDL):
Text 
            L"O:BAG:SYD:"
            L"(A;;0xf0007;;;SY)"                // local system               (read, write, clear)
            L"(A;;0x7;;;BA)"                    // built-in admins            (read, write, clear)
            L"(A;;0x7;;;SO)"                    // server operators           (read, write, clear)
            L"(A;;0x3;;;IU)"                    // INTERACTIVE LOGON          (read, write)
            L"(A;;0x3;;;SU)"                    // SERVICES LOGON             (read, write)
            L"(A;;0x3;;;S-1-5-3)"               // BATCH LOGON                (read, write)
            L"(A;;0x3;;;S-1-5-33)"              // write restricted service   (read, write)
            L"(A;;0x1;;;S-1-5-32-573)";         // event log readers          (read)

The default permissions for System are (shown using SDDL):

Text 
            L"O:BAG:SYD:"
            L"(A;;0xf0007;;;SY)"                // local system             (read, write, clear)
            L"(A;;0x7;;;BA)"                    // built-in admins          (read, write, clear)
            L"(A;;0x3;;;BO)"                    // backup operators         (read, write)
            L"(A;;0x5;;;SO)"                    // server operators         (read, clear) 
            L"(A;;0x1;;;IU)"                    // INTERACTIVE LOGON        (read)
            L"(A;;0x3;;;SU)"                    // SERVICES LOGON           (read, write)
            L"(A;;0x1;;;S-1-5-3)"               // BATCH LOGON              (read)
            L"(A;;0x2;;;S-1-5-33)"              // write restricted service (write)
            L"(A;;0x1;;;S-1-5-32-573)";         // event log readers        (read)

The default permissions for Custom isolation is the same as Application.

Channels that specify Application isolation use the same ETW session. The same is true for System isolation. However, if you specify Custom isolation, the service creates a separate ETW session for the channel. Using Custom isolation lets you control the access permissions for the channel and backing file. Because there are only 64 ETW sessions available, you should limit your use of Custom isolation.
message string

The localized display name for the channel. The message string references a localized string in the stringTable section of the manifest.
name anyURI

The name of the channel. The name must be unique within the list of channels that the provider uses. The convention for naming channels is to append the channel type to the provider's name. For example. if the provider's name is Company-Product-Component and you are defining an operational channel, the name would be Company-Product-Component/Operational.

Channel names must be less that 255 characters and cannot contain the following characters: '>', '<', '&', '"', '|', '\', ':', '`', '?', '*', or characters with codes less than 31.
symbol CSymbolType

The symbol to use to reference the channel in your application. The Message Compiler (MC.exe) uses the symbol to create a constant for the channel in the header file that the compiler generates. If you do not specify a symbol, the compiler generates the name for you.
type string

Identifies the channel's type. You can specify one of the following types:

  • Admin
  • Operational
  • Analytic
  • Debug

Admin type channels support events that target end users, administrators, and support personnel. Events written to the Admin channels should have a well-defined solution on which the administrator can act. An example of an admin event is an event that occurs when an application fails to connect to a printer. These events are either well-documented or have a message associated with them that gives the reader direct instructions of what must be done to rectify the problem.

Operational type channels support events that are used for analyzing and diagnosing a problem or occurrence. They can be used to trigger tools or tasks based on the problem or occurrence. An example of an operational event is an event that occurs when a printer is added or removed from a system.

Analytic type channels support events that are published in high volume. They describe program operation and indicate problems that cannot be handled by user intervention.

Debug type channels support events that are used solely by developers to diagnose a problem for debugging.

Analytic and debug channels are disabled by default and should only enabled to determine the cause of an issue. For example, you would enable the channel, run the scenario that is causing the issue, disable the channel, and then query the events. Note that enabling the channel clears the channel of existing events. If the analytic and debug channel uses a circular backing file, you must disable the channel to query its events.

All Admin channels use the same ETW session; the same is true for Operational channels. However, each Analytic and Debug channel uses a separate ETW session, which is another reason to only enable these channel types when needed (there is a limited number of ETW sessions available).
value UInt8Type

A numeric identifier that uniquely identifies the channel within the list of channels that the provider defines. The message compiler assigns the value if not specified.

Remarks

If the channel's name follows the channel naming convention, the Windows Event Viewer will list the channel using the string that follows the backslash. For example, if the channel name is Company-Product-Component/Operational, then the Event Viewer will list the channel as Operational under the Company-Product-Component provider. Otherwise, the entire channel name is shown under the provider. The localized display name is used if provided.

Requirements

Requirement Value
Minimum supported client
 Windows Vista [desktop apps only]
Minimum supported server
 Windows Server 2008 [desktop apps only]

`