EventLog.CreateEventSource 方法

定義

命名空間:

System.Diagnostics

組件:

System.Diagnostics.EventLog.dll

套件:

System.Diagnostics.EventLog v9.0.0-preview.5.24306.7

建立應用程式，以便將事件資訊寫入系統上的特定記錄檔。

多載

CreateEventSource(EventSourceCreationData)	使用事件來源和對應事件記錄檔的指定組態屬性，建立有效的事件來源，以撰寫本地化的事件訊息。
CreateEventSource(String, String)	將指定的來源名稱建立為有效的事件來源，以便將專案寫入本機計算機上的記錄檔。 這個方法也可以在本機計算機上建立新的自定義記錄檔。
CreateEventSource(String, String, String)	已淘汰. 將指定的來源名稱建立為有效的事件來源，以便將專案寫入指定計算機上的記錄檔。 這個方法也可以用來在指定的計算機上建立新的自定義記錄檔。

CreateEventSource(EventSourceCreationData)

來源:

EventLog.cs

使用事件來源和對應事件記錄檔的指定組態屬性，建立有效的事件來源，以撰寫本地化的事件訊息。

public:
 static void CreateEventSource(System::Diagnostics::EventSourceCreationData ^ sourceData);

public static void CreateEventSource (System.Diagnostics.EventSourceCreationData sourceData);

static member CreateEventSource : System.Diagnostics.EventSourceCreationData -> unit

Public Shared Sub CreateEventSource (sourceData As EventSourceCreationData)

參數

sourceData

EventSourceCreationData

事件來源及其目標事件記錄檔的組態屬性。

例外狀況

ArgumentException

sourceData 中指定的計算機名稱無效。

-或-

sourceData 中指定的來源名稱 null。

-或-

sourceData 中指定的記錄檔名稱無效。 事件記錄檔名稱必須包含可列印的字元，且不能包含字元 『*』、'？' 或 '\'。

-或-

sourceData 中指定的記錄名稱不適用於用戶記錄建立。 事件記錄檔名稱 AppEvent、SysEvent 和 SecEvent 會保留供系統使用。

-或-

記錄名稱符合現有的事件來源名稱。

-或-

sourceData 中指定的來源名稱會導致登錄機碼路徑超過 254 個字元。

-或-

sourceData 中所指定記錄檔名稱的前8個字元並不是唯一的。

-或-

sourceData 中指定的來源名稱已經註冊。

-或-

sourceData 中指定的來源名稱符合現有的事件記錄檔名稱。

InvalidOperationException

無法開啟事件記錄檔的登錄機碼。

ArgumentNullException

sourceData null。

範例

下列範例會判斷名為 SampleApplicationSource 的事件來源是否已在本機計算機上註冊。 如果事件來源不存在，此範例會設定來源的訊息資源檔，並建立新的事件來源。 最後，此範例會使用 DisplayNameMsgId 中的資源識別符值，以及 messageFile中的資源檔路徑，設定事件記錄檔的當地語系化顯示名稱。

void CreateEventSourceSample1( String^ messageFile )
{
   String^ myLogName;
   String^ sourceName = "SampleApplicationSource";
   
   // Create the event source if it does not exist.
   if (  !EventLog::SourceExists( sourceName ) )
   {
      
      // Create a new event source for the custom event log
      // named "myNewLog."  
      myLogName = "myNewLog";
      EventSourceCreationData ^ mySourceData = gcnew EventSourceCreationData( sourceName,myLogName );
      
      // Set the message resource file that the event source references.
      // All event resource identifiers correspond to text in this file.
      if (  !System::IO::File::Exists( messageFile ) )
      {
         Console::WriteLine( "Input message resource file does not exist - {0}", messageFile );
         messageFile = "";
      }
      else
      {
         
         // Set the specified file as the resource
         // file for message text, category text, and 
         // message parameter strings.  
         mySourceData->MessageResourceFile = messageFile;
         mySourceData->CategoryResourceFile = messageFile;
         mySourceData->CategoryCount = CategoryCount;
         mySourceData->ParameterResourceFile = messageFile;
         Console::WriteLine( "Event source message resource file set to {0}", messageFile );
      }

      Console::WriteLine( "Registering new source for event log." );
      EventLog::CreateEventSource( mySourceData );
   }
   else
   {
      
      // Get the event log corresponding to the existing source.
      myLogName = EventLog::LogNameFromSourceName( sourceName, "." );
   }

   
   // Register the localized name of the event log.
   // For example, the actual name of the event log is "myNewLog," but
   // the event log name displayed in the Event Viewer might be
   // "Sample Application Log" or some other application-specific
   // text.
   EventLog^ myEventLog = gcnew EventLog( myLogName,".",sourceName );
   if ( messageFile->Length > 0 )
   {
      myEventLog->RegisterDisplayName( messageFile, DisplayNameMsgId );
   }   
}

static void CreateEventSourceSample1(string messageFile)
{
    string myLogName;
    string sourceName = "SampleApplicationSource";

    // Create the event source if it does not exist.
    if(!EventLog.SourceExists(sourceName))
    {
        // Create a new event source for the custom event log
        // named "myNewLog."

        myLogName = "myNewLog";
        EventSourceCreationData mySourceData = new EventSourceCreationData(sourceName, myLogName);

        // Set the message resource file that the event source references.
        // All event resource identifiers correspond to text in this file.
        if (!System.IO.File.Exists(messageFile))
        {
            Console.WriteLine("Input message resource file does not exist - {0}",
                messageFile);
            messageFile = "";
        }
        else
        {
            // Set the specified file as the resource
            // file for message text, category text, and
            // message parameter strings.

            mySourceData.MessageResourceFile = messageFile;
            mySourceData.CategoryResourceFile = messageFile;
            mySourceData.CategoryCount = CategoryCount;
            mySourceData.ParameterResourceFile = messageFile;

            Console.WriteLine("Event source message resource file set to {0}",
                messageFile);
        }

        Console.WriteLine("Registering new source for event log.");
        EventLog.CreateEventSource(mySourceData);
    }
    else
    {
        // Get the event log corresponding to the existing source.
        myLogName = EventLog.LogNameFromSourceName(sourceName,".");
    }

    // Register the localized name of the event log.
    // For example, the actual name of the event log is "myNewLog," but
    // the event log name displayed in the Event Viewer might be
    // "Sample Application Log" or some other application-specific
    // text.
    EventLog myEventLog = new EventLog(myLogName, ".", sourceName);

    if (messageFile.Length > 0)
    {
        myEventLog.RegisterDisplayName(messageFile, DisplayNameMsgId);
    }
}

Public Shared Sub CreateEventSourceSample1(ByVal messageFile As String)

    Dim myLogName As String
    Dim sourceName As String = "SampleApplicationSource"

    ' Create the event source if it does not exist.
    If Not EventLog.SourceExists(sourceName)
    
        ' Create a new event source for the custom event log
        ' named "myNewLog."  

        myLogName = "myNewLog"
        Dim mySourceData As EventSourceCreationData = New EventSourceCreationData(sourceName, myLogName)

        ' Set the message resource file that the event source references.
        ' All event resource identifiers correspond to text in this file.
        If Not System.IO.File.Exists(messageFile)

            Console.WriteLine("Input message resource file does not exist - {0}", _
                messageFile)
            messageFile = ""
        Else 
            ' Set the specified file as the resource
            ' file for message text, category text and 
            ' message parameters strings.

            mySourceData.MessageResourceFile = messageFile
            mySourceData.CategoryResourceFile = messageFile
            mySourceData.CategoryCount = CategoryCount
            mySourceData.ParameterResourceFile = messageFile

            Console.WriteLine("Event source message resource file set to {0}", _
                messageFile)
        End If

        Console.WriteLine("Registering new source for event log.")
        EventLog.CreateEventSource(mySourceData)
    Else
        ' Get the event log corresponding to the existing source.
        myLogName = EventLog.LogNameFromSourceName(sourceName,".")
    End If

    ' Register the localized name of the event log.
    ' For example, the actual name of the event log is "myNewLog," but
    ' the event log name displayed in the Event Viewer might be
    ' "Sample Application Log" or some other application-specific
    ' text.
    Dim myEventLog As EventLog = New EventLog(myLogName, ".", sourceName)
    
    If messageFile.Length > 0
        myEventLog.RegisterDisplayName(messageFile, DisplayNameMsgId)
    End If
End Sub

這個範例使用下列訊息文字檔，內建於資源庫 EventLogMsgs.dll。 訊息文本檔是訊息資源檔建立的來源。 訊息文字檔會定義類別、事件訊息和參數插入字串的資源識別碼和文字。 具體而言，會針對事件記錄檔的當地語系化名稱定義資源標識碼 5001。

; // EventLogMsgs.mc  
; // ********************************************************  

; // Use the following commands to build this file:  

; //   mc -s EventLogMsgs.mc  
; //   rc EventLogMsgs.rc  
; //   link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res   
; // ********************************************************  

; // - Event categories -  
; // Categories must be numbered consecutively starting at 1.  
; // ********************************************************  

MessageId=0x1  
Severity=Success  
SymbolicName=INSTALL_CATEGORY  
Language=English  
Installation  
.  

MessageId=0x2  
Severity=Success  
SymbolicName=QUERY_CATEGORY  
Language=English  
Database Query  
.  

MessageId=0x3  
Severity=Success  
SymbolicName=REFRESH_CATEGORY  
Language=English  
Data Refresh  
.  

; // - Event messages -  
; // *********************************  

MessageId = 1000  
Severity = Success  
Facility = Application  
SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000  
Language=English  
My application message text, in English, for message id 1000, called from %1.  
.  

MessageId = 1001  
Severity = Warning  
Facility = Application  
SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001  
Language=English  
My application message text, in English, for message id 1001, called from %1.  
.  

MessageId = 1002  
Severity = Success  
Facility = Application  
SymbolicName = GENERIC_INFO_MESSAGE_ID_1002  
Language=English  
My generic information message in English, for message id 1002.  
.  

MessageId = 1003  
Severity = Warning  
Facility = Application  
SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003  
Language=English  
My generic warning message in English, for message id 1003, called from %1.  
.  

MessageId = 1004  
Severity = Success  
Facility = Application  
SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004  
Language=English  
The update cycle is complete for %%5002.  
.  

MessageId = 1005  
Severity = Warning  
Facility = Application  
SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005  
Language=English  
The refresh operation did not complete because the connection to server %1 could not be established.  
.  

; // - Event log display name -  
; // ********************************************************  

MessageId = 5001  
Severity = Success  
Facility = Application  
SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID  
Language=English  
Sample Event Log  
.  

; // - Event message parameters -  
; //   Language independent insertion strings  
; // ********************************************************  

MessageId = 5002  
Severity = Success  
Facility = Application  
SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID  
Language=English  
SVC_UPDATE.EXE  
.  

備註

使用此多載來設定新的來源，以便將專案寫入本機計算機或遠端電腦上的事件記錄檔。 不需要使用這個方法從事件記錄檔讀取。

CreateEventSource 方法會使用輸入 sourceDataSource、LogName 和 MachineName 屬性，在目標計算機上為新來源及其相關聯的事件記錄檔建立登錄值。 新的來源名稱無法比對目標計算機上的現有來源名稱或現有的事件記錄檔名稱。 如果未設定 LogName 屬性，則會註冊應用程式事件記錄檔的來源。 如果未設定 MachineName，則會在本機計算機上註冊來源。

注意

若要在 Windows Vista 和更新版本或 Windows Server 2003 中建立事件來源，您必須具有系統管理許可權。

這項需求的原因是必須搜尋所有事件記錄檔，包括安全性，才能判斷事件來源是否是唯一的。 從 Windows Vista 開始，用戶沒有存取安全性記錄的許可權;因此，會擲回 SecurityException。

從 Windows Vista 開始，用戶帳戶控制 （UAC） 會決定用戶的許可權。 如果您是內建系統管理員群組的成員，系統會指派兩個運行時間存取令牌：標準使用者存取令牌和系統管理員存取令牌。 根據預設，您處於標準使用者角色。 若要執行存取安全性記錄的程式代碼，您必須先將許可權從標準使用者提升為系統管理員。 當您以滑鼠右鍵按下應用程式圖示，並指出您想要以系統管理員身分執行，即可啟動應用程式。

使用 WriteEvent 和 WriteEntry 將事件寫入事件記錄檔。 您必須指定事件來源來寫入事件;您必須先建立並設定事件來源，才能使用來源撰寫第一個專案。

在安裝應用程式期間建立新的事件來源。 這可讓操作系統重新整理其已註冊事件來源及其設定清單的時間。 如果操作系統尚未重新整理其事件來源清單，而且您嘗試使用新的來源寫入事件，寫入作業將會失敗。 您可以使用 EventLogInstaller或 CreateEventSource 方法來設定新的來源。 您必須擁有計算機上的系統管理許可權，才能建立新的事件來源。

您可以為現有的事件記錄檔或新的事件記錄檔建立事件來源。 當您為新的事件記錄檔建立新的來源時，系統會註冊該記錄檔的來源，但在寫入第一個專案之前不會建立記錄檔。

操作系統會將事件記錄檔儲存為檔案。 當您使用 EventLogInstaller 或 CreateEventSource 建立新的事件記錄檔時，相關聯的檔案會儲存在指定計算機上的 %SystemRoot%\System32\Config 目錄中。 檔名是使用 「.evt」 擴展名附加 Log 屬性的前 8 個字元來設定。

每個來源一次只能寫入一個事件記錄檔;不過，您的應用程式可以使用多個來源來寫入多個事件記錄檔。 例如，您的應用程式可能需要針對不同的事件記錄檔或不同的資源檔案設定多個來源。

您可以針對事件類別目錄和訊息字串，向本地化的資源文件註冊事件來源。 您的應用程式可以使用資源識別碼來寫入事件記錄檔專案，而不是指定實際的字串。 事件查看器會使用資源標識符，根據目前的語言設定，從本地化的資源文件尋找並顯示對應的字串。 您可以為事件類別、訊息和參數插入字串註冊個別的檔案，也可以註冊這三種字串類型的相同資源檔。 使用 CategoryCount、CategoryResourceFile、MessageResourceFile和 ParameterResourceFile 屬性，將來源設定為將當地語系化專案寫入事件記錄檔。 如果您的應用程式將字串值直接寫入事件記錄檔，則不需要設定這些屬性。

來源必須設定為撰寫本地化專案，或撰寫直接字串。 如果您的應用程式同時使用資源識別碼和字串值來寫入專案，您必須註冊兩個不同的來源。 例如，使用資源文件設定一個來源，然後在 WriteEvent 方法中使用該來源，使用資源標識符將專案寫入事件記錄檔。 然後建立不含資源檔的不同來源，並在 WriteEntry 方法中使用該來源，直接使用該來源將字串寫入事件記錄檔。

若要變更現有來源的組態詳細數據，您必須刪除來源，然後使用新的組態加以建立。 如果其他應用程式或元件使用現有的來源，請使用更新的組態建立新的來源，而不是刪除現有的來源。

注意

如果已針對事件記錄檔設定來源，而且您為另一個事件記錄檔重新設定來源，您必須重新啟動計算機，變更才會生效。

另請參閱

• EventSourceCreationData
• SourceExists(String)
• DeleteEventSource(String)
• Source
• EventLogInstaller

CreateEventSource(String, String)

來源:

EventLog.cs

將指定的來源名稱建立為有效的事件來源，以便將專案寫入本機計算機上的記錄檔。 這個方法也可以在本機計算機上建立新的自定義記錄檔。

public:
 static void CreateEventSource(System::String ^ source, System::String ^ logName);

public static void CreateEventSource (string source, string logName);

static member CreateEventSource : string * string -> unit

Public Shared Sub CreateEventSource (source As String, logName As String)

參數

source

String

應用程式在本機計算機上註冊的來源名稱。

logName

String

來源專案寫入的記錄檔名稱。 可能的值包括應用程式、系統或自定義事件記錄檔。

例外狀況

ArgumentException

source 是空字串 （“”） 或 null。

-或-

logName 不是有效的事件記錄檔名稱。 事件記錄檔名稱必須包含可列印的字元，而且不能包含字元 『*』、'？' 或 '\'。

-或-

logName 對用戶記錄建立無效。 事件記錄檔名稱 AppEvent、SysEvent 和 SecEvent 會保留供系統使用。

-或-

記錄名稱符合現有的事件來源名稱。

-或-

來源名稱會導致登錄機碼路徑超過 254 個字元。

-或-

前8個字元 logName 符合現有事件記錄檔名稱的前8個字元。

-或-

來源無法註冊，因為它已存在於本機計算機上。

-或-

來源名稱符合現有的事件記錄檔名稱。

InvalidOperationException

無法在本機計算機上開啟事件記錄檔的登錄機碼。

範例

下列範例會在來源不存在時建立來源 MySource，並將專案寫入事件記錄檔 MyNewLog。

#using <System.dll>

using namespace System;
using namespace System::Diagnostics;
using namespace System::Threading;
int main()
{
   
   // Create the source, if it does not already exist.
   if (  !EventLog::SourceExists( "MySource" ) )
   {
      //An event log source should not be created and immediately used.
      //There is a latency time to enable the source, it should be created
      //prior to executing the application that uses the source.
      //Execute this sample a second time to use the new source.
      EventLog::CreateEventSource( "MySource", "MyNewLog" );
      Console::WriteLine( "CreatingEventSource" );
      // The source is created.  Exit the application to allow it to be registered.
      return 0;
   }

   
   // Create an EventLog instance and assign its source.
   EventLog^ myLog = gcnew EventLog;
   myLog->Source = "MySource";
   
   // Write an informational entry to the event log.    
   myLog->WriteEntry( "Writing to event log." );
}

using System;
using System.Diagnostics;
using System.Threading;

class MySample{

    public static void Main(){

        // Create the source, if it does not already exist.
        if(!EventLog.SourceExists("MySource"))
        {
             //An event log source should not be created and immediately used.
             //There is a latency time to enable the source, it should be created
             //prior to executing the application that uses the source.
             //Execute this sample a second time to use the new source.
            EventLog.CreateEventSource("MySource", "MyNewLog");
            Console.WriteLine("CreatedEventSource");
            Console.WriteLine("Exiting, execute the application a second time to use the source.");
            // The source is created.  Exit the application to allow it to be registered.
            return;
        }

        // Create an EventLog instance and assign its source.
        EventLog myLog = new EventLog();
        myLog.Source = "MySource";

        // Write an informational entry to the event log.
        myLog.WriteEntry("Writing to event log.");
    }
}

Option Explicit
Option Strict

Imports System.Diagnostics
Imports System.Threading

Class MySample
    Public Shared Sub Main()
        
        If Not EventLog.SourceExists("MySource") Then
            ' Create the source, if it does not already exist.
            ' An event log source should not be created and immediately used.
            ' There is a latency time to enable the source, it should be created
            ' prior to executing the application that uses the source.
            ' Execute this sample a second time to use the new source.
            EventLog.CreateEventSource("MySource", "MyNewLog")
            Console.WriteLine("CreatingEventSource")
            'The source is created.  Exit the application to allow it to be registered.
            Return
        End If
        
        ' Create an EventLog instance and assign its source.
        Dim myLog As New EventLog()
        myLog.Source = "MySource"
        
        ' Write an informational entry to the event log.    
        myLog.WriteEntry("Writing to event log.")
    End Sub
End Class

備註

使用此多載來建立自定義記錄檔，或建立並註冊本機計算機上的現有記錄檔 Source。

如果您在呼叫 CreateEventSource時，logName 是 null 或空字串 （“”），則記錄會默認為應用程式記錄檔。 如果本機計算機上沒有記錄檔，系統會建立自定義記錄檔，並將您的應用程式註冊為該記錄的 Source。

注意

若要在 Windows Vista 和更新版本或 Windows Server 2003 中建立事件來源，您必須具有系統管理許可權。

這項需求的原因是必須搜尋所有事件記錄檔，包括安全性，才能判斷事件來源是否是唯一的。 從 Windows Vista 開始，用戶沒有存取安全性記錄的許可權;因此，會擲回 SecurityException。

在 Windows Vista 和更新版本中，用戶帳戶控制 （UAC） 會決定用戶的許可權。 如果您是內建系統管理員群組的成員，系統會指派兩個運行時間存取令牌：標準使用者存取令牌和系統管理員存取令牌。 根據預設，您處於標準使用者角色。 若要執行存取安全性記錄的程式代碼，您必須先將許可權從標準使用者提升為系統管理員。 當您以滑鼠右鍵按下應用程式圖示，並指出您想要以系統管理員身分執行，即可啟動應用程式。

只有在寫入事件記錄檔時，才需要建立事件來源。 將專案寫入事件記錄檔之前，您必須將事件來源註冊為事件記錄檔的有效事件來源。 當您寫入記錄專案時，系統會使用 Source 來尋找放置專案的適當記錄檔。 如果您要讀取事件記錄檔，您可以指定 Source或 Log 和 MachineName。

注意

如果您要連線到本機計算機上的記錄檔，則不需要指定 MachineName。 如果您未在從記錄檔讀取時指定 MachineName，則會假設本機計算機 （“.”）。

使用 WriteEvent 和 WriteEntry 將事件寫入事件記錄檔。 您必須指定事件來源來寫入事件;您必須先建立並設定事件來源，才能使用來源撰寫第一個專案。

在安裝應用程式期間建立新的事件來源。 這可讓操作系統重新整理其已註冊事件來源及其設定清單的時間。 如果操作系統尚未重新整理其事件來源清單，而且您嘗試使用新的來源寫入事件，寫入作業將會失敗。 您可以使用 EventLogInstaller或 CreateEventSource 方法來設定新的來源。 您必須擁有計算機上的系統管理許可權，才能建立新的事件來源。

您可以為現有的事件記錄檔或新的事件記錄檔建立事件來源。 當您為新的事件記錄檔建立新的來源時，系統會註冊該記錄檔的來源，但在寫入第一個專案之前不會建立記錄檔。

操作系統會將事件記錄檔儲存為檔案。 當您使用 EventLogInstaller 或 CreateEventSource 建立新的事件記錄檔時，相關聯的檔案會儲存在指定計算機上的 %SystemRoot%\System32\Config 目錄中。 檔名是使用 「.evt」 擴展名附加 Log 屬性的前 8 個字元來設定。

來源在本機計算機上必須是唯一的;新的來源名稱不符合現有的來源名稱或現有的事件記錄檔名稱。 每個來源一次只能寫入一個事件記錄檔;不過，您的應用程式可以使用多個來源來寫入多個事件記錄檔。 例如，您的應用程式可能需要針對不同的事件記錄檔或不同的資源檔案設定多個來源。

來源必須設定為撰寫本地化專案，或撰寫直接字串。 如果您的應用程式同時使用資源識別碼和字串值來寫入專案，您必須註冊兩個不同的來源。 例如，使用資源文件設定一個來源，然後在 WriteEvent 方法中使用該來源，使用資源標識符將專案寫入事件記錄檔。 然後建立不含資源檔的不同來源，並在 WriteEntry 方法中使用該來源，直接使用該來源將字串寫入事件記錄檔。

若要變更現有來源的組態詳細數據，您必須刪除來源，然後使用新的組態加以建立。 如果其他應用程式或元件使用現有的來源，請使用更新的組態建立新的來源，而不是刪除現有的來源。

注意

如果來源已經對應至記錄檔，而且您將它重新對應至新的記錄檔，您必須重新啟動計算機，變更才會生效。

另請參閱

• DeleteEventSource(String)
• SourceExists(String)
• Source
• Log
• Delete(String)

CreateEventSource(String, String, String)

來源:

EventLog.cs

警告

EventLog.CreateEventSource has been deprecated. Use System.Diagnostics.EventLog.CreateEventSource(EventSourceCreationData sourceData) instead.

將指定的來源名稱建立為有效的事件來源，以便將專案寫入指定計算機上的記錄檔。 這個方法也可以用來在指定的計算機上建立新的自定義記錄檔。

public:
 static void CreateEventSource(System::String ^ source, System::String ^ logName, System::String ^ machineName);

[System.Obsolete("EventLog.CreateEventSource has been deprecated. Use System.Diagnostics.EventLog.CreateEventSource(EventSourceCreationData sourceData) instead.")]
public static void CreateEventSource (string source, string logName, string machineName);

[<System.Obsolete("EventLog.CreateEventSource has been deprecated. Use System.Diagnostics.EventLog.CreateEventSource(EventSourceCreationData sourceData) instead.")>]
static member CreateEventSource : string * string * string -> unit

Public Shared Sub CreateEventSource (source As String, logName As String, machineName As String)

參數

source

String

應用程式在指定計算機上註冊的來源。

logName

String

來源專案寫入的記錄檔名稱。 可能的值包括應用程式、系統或自定義事件記錄檔。 如果您未指定值，logName 預設為 Application。

machineName

String

要向本機計算機註冊此事件來源的計算機名稱，或 “.”。

屬性

ObsoleteAttribute

例外狀況

ArgumentException

machineName 不是有效的計算機名稱。

-或-

source 是空字串 （“”） 或 null。

-或-

logName 不是有效的事件記錄檔名稱。 事件記錄檔名稱必須包含可列印的字元，而且不能包含字元 『*』、'？' 或 '\'。

-或-

logName 對用戶記錄建立無效。 事件記錄檔名稱 AppEvent、SysEvent 和 SecEvent 會保留供系統使用。

-或-

記錄名稱符合現有的事件來源名稱。

-或-

來源名稱會導致登錄機碼路徑超過 254 個字元。

-或-

前8個字元 logName 符合指定電腦上現有事件記錄檔名稱的前8個字元。

-或-

來源無法註冊，因為它已存在於指定的計算機上。

-或-

來源名稱符合現有的事件來源名稱。

InvalidOperationException

無法在指定的電腦上開啟事件記錄檔的登錄機碼。

範例

下列範例會在 MyServer電腦上建立來源 MySource，並將專案寫入事件記錄檔 MyNewLog。

#using <System.dll>

using namespace System;
using namespace System::Diagnostics;
using namespace System::Threading;
int main()
{
   
   // Create the source, if it does not already exist.
   if (  !EventLog::SourceExists( "MySource", "MyServer" ) )
   {
      EventLog::CreateEventSource( "MySource", "MyNewLog", "MyServer" );
      Console::WriteLine( "CreatingEventSource" );
   }

   
   // Create an EventLog instance and assign its source.
   EventLog^ myLog = gcnew EventLog;
   myLog->Source = "MySource";
   
   // Write an informational entry to the event log.    
   myLog->WriteEntry( "Writing to event log." );
   Console::WriteLine( "Message written to event log." );
}

using System;
using System.Diagnostics;
using System.Threading;

class MySample{

    public static void Main(){

        // Create the source, if it does not already exist.
        if(!EventLog.SourceExists("MySource", "MyServer"))
        {
            // An event log source should not be created and immediately used.
            // There is a latency time to enable the source, it should be created
            // prior to executing the application that uses the source.
            // Execute this sample a second time to use the new source.
            EventLog.CreateEventSource("MySource", "MyNewLog", "MyServer");
            Console.WriteLine("CreatingEventSource");
            Console.WriteLine("Exiting, execute the application a second time to use the source.");
            // The source is created.  Exit the application to allow it to be registered.
            return;
        }

        // Create an EventLog instance and assign its source.
        EventLog myLog = new EventLog();
        myLog.Source = "MySource";

        // Write an informational entry to the event log.
        myLog.WriteEntry("Writing to event log.");

        Console.WriteLine("Message written to event log.");
    }
}

Imports System.Diagnostics
Imports System.Threading

Class MySample
    Public Shared Sub Main()
        ' Create the source, if it does not already exist.
        If Not EventLog.SourceExists("MySource", "MyServer") Then
            EventLog.CreateEventSource("MySource", "MyNewLog", "MyServer")
            Console.WriteLine("CreatingEventSource")
        End If
        
        ' Create an EventLog instance and assign its source.
        Dim myLog As New EventLog()
        myLog.Source = "MySource"
        
        ' Write an informational entry to the event log.    
        myLog.WriteEntry("Writing to event log.")
        
        Console.WriteLine("Message written to event log.")
    End Sub
End Class

備註

使用此多載來建立自定義記錄檔，或建立並註冊指定計算機上的現有記錄檔 Source。

如果您在呼叫 CreateEventSource時，logName 是 null 或空字串 （“”），則記錄會默認為應用程式記錄檔。 如果指定的計算機上沒有記錄檔，系統會建立自定義記錄檔，並將您的應用程式註冊為該記錄的 Source。

只有在寫入事件記錄檔時，才需要建立事件來源。 將專案寫入事件記錄檔之前，您必須將事件來源註冊為事件記錄檔的有效事件來源。 當您寫入記錄專案時，系統會使用 Source 來尋找放置專案的適當記錄檔。 如果您要讀取事件記錄檔，您可以指定 Source或 Log 和 MachineName。

注意

若要在 Windows Vista 和更新版本或 Windows Server 2003 中建立事件來源，您必須具有系統管理許可權。

這項需求的原因是必須搜尋所有事件記錄檔，包括安全性，才能判斷事件來源是否是唯一的。 在 Windows Vista 和更新版本中，用戶沒有存取安全性記錄的許可權;因此，會擲回 SecurityException。

在 Windows Vista 和更新版本中，用戶帳戶控制 （UAC） 會決定用戶的許可權。 如果您是內建系統管理員群組的成員，系統會指派兩個運行時間存取令牌：標準使用者存取令牌和系統管理員存取令牌。 根據預設，您處於標準使用者角色。 若要執行存取安全性記錄的程式代碼，您必須先將許可權從標準使用者提升為系統管理員。 當您以滑鼠右鍵按下應用程式圖示，並指出您想要以系統管理員身分執行，即可啟動應用程式。

使用 WriteEvent 和 WriteEntry 將事件寫入事件記錄檔。 您必須指定事件來源來寫入事件;您必須先建立並設定事件來源，才能使用來源撰寫第一個專案。

在安裝應用程式期間建立新的事件來源。 這可讓操作系統重新整理其已註冊事件來源及其設定清單的時間。 如果操作系統尚未重新整理其事件來源清單，而且您嘗試使用新的來源寫入事件，寫入作業將會失敗。 您可以使用 EventLogInstaller或 CreateEventSource 方法來設定新的來源。 您必須擁有計算機上的系統管理許可權，才能建立新的事件來源。

您可以為現有的事件記錄檔或新的事件記錄檔建立事件來源。 當您為新的事件記錄檔建立新的來源時，系統會註冊該記錄檔的來源，但在寫入第一個專案之前不會建立記錄檔。

操作系統會將事件記錄檔儲存為檔案。 當您使用 EventLogInstaller 或 CreateEventSource 建立新的事件記錄檔時，相關聯的檔案會儲存在指定計算機上的 %SystemRoot%\System32\Config 目錄中。 檔名是使用 「.evt」 擴展名附加 Log 屬性的前 8 個字元來設定。

來源在本機計算機上必須是唯一的;新的來源名稱不符合現有的來源名稱或現有的事件記錄檔名稱。 每個來源一次只能寫入一個事件記錄檔;不過，您的應用程式可以使用多個來源來寫入多個事件記錄檔。 例如，您的應用程式可能需要針對不同的事件記錄檔或不同的資源檔案設定多個來源。

來源必須設定為撰寫本地化專案，或撰寫直接字串。 如果您的應用程式同時使用資源識別碼和字串值來寫入專案，您必須註冊兩個不同的來源。 例如，使用資源文件設定一個來源，然後在 WriteEvent 方法中使用該來源，使用資源標識符將專案寫入事件記錄檔。 然後建立不含資源檔的不同來源，並在 WriteEntry 方法中使用該來源，直接使用該來源將字串寫入事件記錄檔。

若要變更現有來源的組態詳細數據，您必須刪除來源，然後使用新的組態加以建立。 如果其他應用程式或元件使用現有的來源，請使用更新的組態建立新的來源，而不是刪除現有的來源。

注意

如果來源已經對應至記錄檔，而且您將它重新對應至新的記錄檔，您必須重新啟動計算機，變更才會生效。

另請參閱

• DeleteEventSource(String)
• SourceExists(String)
• MachineName
• Source
• Log
• Delete(String)