為 Microsoft Windows SharePoint Services 中的文件庫建立事件記錄訊息

適用於：
Microsoft_ Windows_ SharePoint Services
Microsoft Office SharePoint Portal Server 2003

摘要：通過本文和程式碼範例，啟用 Microsoft Windows SharePoint Services 中的文件庫事件記錄訊息。本文將指導您如何建立要在 Microsoft Windows SharePoint Services 中使用的事件處理常式。下載程式碼範例並根據自己的環境修改它。（13 頁列印頁）

下載 CreatingEventsinaDocumentLibrarySample.exe。

本頁內容

概述
事件設定
啟用文件庫的事件
為事件建立 Microsoft Visual Studio .NET 2003 項目
將事件代碼與文件庫相關聯
小結
附錄 A — 樣本安裝
附錄 B — 樣本事件代碼

概述

Microsoft_ Windows_ SharePoint? Services 可提供允許您基於 Windows SharePoint Services 平台構建的文件庫事件。您可以建立為這些事件定義處理常式的Managed 程式碼程式集，然後將這些處理常式綁定到文件庫。事件處理常式可以通過調入物件模型 (OM) 來直接存取設定資料庫和內容資料庫，也可以將 Windows SharePoint Services 用作其他系統的使用者介面來調用外部服務。通過定義事件處理常式並為特定文件庫啟用事件記錄記錄，您可以使用 Microsoft 事件檢視器來查看事件訊息。

下表列出 Windows SharePoint Services 提供的文件庫的事件，您可以對這些事件啟用日誌記錄。

表 1. 文件庫事件

事件	說明
Cancel Check Out	撤消對已簽出文檔進行的更改。
Check In	將文檔簽入到文件庫中。
Check Out	從文件庫中籤出文檔。
Copy	複製文件庫中的文檔。
Delete	從文件庫中刪除文檔。
Insert	將新文檔儲存到文件庫中。
Move or Rename	移動或重新命名文檔。
Update	編輯庫中現有的文檔或自訂欄的值。

在 Windows SharePoint Services 的上下文中，事件處理常式是一個實現 IListEventSink 介面的 .NET 類，在事件處理常式中使用此介面的單一方法 OnEvent。SPListEvent 對象包含有關所發生事件的資訊。您可以通過 Type 屬性來識別事件的類型，並可以使用 Site 屬性來訪問處理常式中 Microsoft.SharePoint 命名空間的物件模型。

您必須將用來定義事件處理常式的託管程式集安裝到全域組件快取 (GAC) 或適當的虛擬伺服器 BIN 目錄中。

注 此外，在伺服器陣列配置中，每個前端網頁伺服器都必須安裝有託管程式集。

要在伺服器上部署事件處理常式，您必須啟用“SharePoint 管理中心”內的“虛擬伺服器常規設定”頁上的事件處理。

注 您必須是本地 Administrators 組或 SharePoint Administrators 組的成員，才能啟用文件庫的事件處理。

返回頁首 事件設定

文件庫的中繼資料可通過下表中指定的屬性，將事件處理常式的類綁定到該文件庫。您可以在“文件庫進階設定”頁上為文件庫指定這些屬性，也可以通過設定 SPList 對象的 EventSinkAssembly、EventSinkClass 和 EventSinkData 屬性的代碼來指定。

表 2. 可能的事件設定

設定	類型	說明
Assembly Name	String	事件處理常式的組件檔（位於 GAC 或 BIN 目錄中）的強式名稱
Class Name	String	程式集中完全限定且區分大小寫類名稱
Properties	String	由事件處理常式使用的自訂屬性的任一字元串，其長度不能超過 255 個字元

在安裝事件處理常式的程式集之後，您必須在文件庫“文件庫進階設定”頁的“程式集名稱”框中，採用以下格式指定程式集的強式名稱：

程式集名稱, Version=版本, Culture=地區性, PublicKeyToken=公開金鑰標記

您可以在 Microsoft Windows 資源管理員中瀏覽至 GAC 的預設位置 (%windir%\assembly) 來識別這些值。例如，在預設情況下，Windows SharePoint Services 程式集的強式名稱如下所示：

Microsoft.SharePoint, Version=11.0.0.0, Culture=Neutral, PublicKeyToken=71e9bce111e9429c

您為“類名”框指定的值必須是區分大小寫完整類名，該類在指定程式集中定義，並可實現 IListEventSink 介面。例如，在以下樣本中，類的全名如下：

WSSEventSink.EventSink

返回頁首 啟用文件庫的事件

在預設情況下，Windows SharePoint Services 不啟用文件庫的事件。要啟用文件庫的事件，請按照下列步驟操作。事件是基於每個虛擬伺服器啟用的。因此，當您啟用事件時，會針對指定虛擬伺服器上建立的所有網站啟用它們。

在虛擬伺服器上啟用事件

1. 在運行 Windows SharePoint Services 的伺服器上，單擊“開始”，指向“管理工具”，然後單擊“SharePoint 管理中心”。請參見圖 1。

   注 預設的“管理中心”頁是根據電腦上所安裝的 SharePoint 產品或技術決定的。如有必要，請在“連結”窗格中單擊“Windows SharePoint Services”，以轉至 Windows SharePoint Services 的“管理中心”頁：

   圖 1. Windows SharePoint Services 的“管理中心”頁

2. 在“虛擬伺服器配置”部分中，單擊“配置虛擬伺服器設定”。

3. 在“虛擬伺服器列表”上，單擊要設定的虛擬伺服器，例如，單擊“預設 Web 網站”。

4. 在“虛擬伺服器設定”頁的“虛擬伺服器管理”部分中，單擊“虛擬伺服器常規設定”。

5. 在“虛擬伺服器常規設定”頁的“事件處理常式”部分中，在“事件處理常式的狀態”框中選擇“開”，然後單擊“確定”。

現在，宿主 SharePoint 網站的虛擬伺服器便啟用了這些事件。

返回頁首 為事件建立 Microsoft Visual Studio .NET 2003 項目

本部分描述如何建立自訂事件處理常式。

要點 本部分假設 Microsoft Visual Studio_ .NET 2003 已安裝在運行 Windows SharePoint Services 的伺服器上。如果您要在沒有安裝 Windows SharePoint Services 的電腦上開發事件處理常式，則需要訪問運行 Windows SharePoint Services 的伺服器。在伺服器電腦上，從 < 系統磁碟機 >:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI 檔案夾複製 Microsoft.SharePoint.dll，並將其轉移到將在其上開發事件處理常式的電腦的檔案夾中。

在 Visual Studio .NET 2003 中建立自訂事件處理常式

1. 在 “ 檔案 ” 菜單上，指向 “ 建立 ” ，然後單擊 “ 項目 ” 。

2. 在“項目類型”視窗中，單擊“Visual Basic 項目”，然後在“模板”視窗中單擊“類庫”。

3. 在“名稱”欄位中，鍵入 WSSEventSink，然後單擊“確定”。

4. 在“方案總管”中，單擊 Class.vb，然後在“屬性”視窗的“雜項”下，將“檔案名稱”更改為 EventSink.vb。

   下一步是添加對 Microsoft.SharePoint.dll 的引用。

5. 為此，請在“項目”菜單上單擊“添加引用”。在 .NET 列表中，單擊 Microsoft.SharePoint.dll，然後單擊“確定”。如果此電腦上沒有安裝 Windows SharePoint Services，則在“.NET”選項卡上單擊“瀏覽”，然後按上面描述的方法導航至將 Microsoft.SharePoint.DLL 複製到其中的檔案夾。選擇該 .DLL 並單擊“開啟”。

6. 複製附錄 B 中的範例程式碼並將其粘貼到 EventSink.vb 的代碼視窗中，替換專案檔中已存在的任何預設代碼，然後單擊“儲存”。

7. 在“工具”菜單上，單擊“建立 GUID”，以建立一個 GUID。

8. 單擊“4. 註冊表格式 (即，{xxxxxxx-xxxx. . . xxxx})”，單擊“複製”，然後單擊“退出”。

9. 在方案總管中，單擊 AssemblyInfo.vb 以開啟 AssemblyInfo.vb 的代碼視窗。

10. 在 AssemblyInfo.vb 的代碼視窗中，找到程式集的 GUID 項並將該字串替換為所複製的 GUID。

11. 在 AssemblyInfo.vb 中，找到以下代碼並添加一個版本號碼。

    <Assembly: AssemblyVersion("1.0.*")>

    例如，<Assembly: AssemblyVersion("1.0.0.1")>

12. 儲存該專案檔。

    接著，您需要賦予該項目一個強式名稱，然後才能在 Windows SharePoint Services 中使用它：

13. 在開發電腦上，單擊“開始”，指向“所有程式”，指向“Microsoft Visual Studio .NET 2003”，指向“Visual Studio .NET 工具”，然後單擊“Visual Studio .NET 2003 命令提示”。

14. 鍵入以下命令：sn.exe –k c:\keypair.snk

    注 您可以將路徑更改為任何所需路徑。

15. 在事件接收項目中，開啟 AssemblyInfo.vb 檔案，並將下行添加到模組的末尾

    <Assembly: AssemblyKeyFile("c:\\keypair.snk")>

16. 現在，您可以對該項目進行編譯。為此，請在“產生”菜單上單擊“產生解決方案”。

17. 檢驗並解決所有建置錯誤，然後儲存所有更改。如果需要，重新構建解決方案。

18. 下一步是將新的 .dll 複製到運行 Windows SharePoint Services 的伺服器的全域組件快取 (GAC) 中。為此，請瀏覽至該項目在開發電腦上的位置，然後將 Windows SharePoint Services EventSink.DLL 檔案複製到 Windows SharePoint Services 伺服器的 GAC 中，GAC 位於與 Windows 2003 和 Windows XP 相對應的以下位置：

    %windir%\assembly

19. 將程式集複製到 GAC 之後，請注意“公開金鑰標記”的值，因為將代碼與 Windows SharePoint Services 中的文件庫相關聯時，該值是必需的。要尋找託管程式集的公開金鑰標記，請在 Windows 資源管理員中開啟 GAC，然後觀察“公開金鑰標記”列。

現在，您已經成功建立了要在 Windows SharePoint Services 中使用的事件處理常式。

注 有關此程式碼範例的完整版本，請下載 CreatingEventsinaDocumentLibrarySample.exe。

返回頁首 將事件代碼與文件庫相關聯

建立自訂事件處理常式之後，您必須將它與要在其中執行該代碼的相關文件庫相關聯。這一步驟還充當 Windows SharePoint Services 的 SafeControl 項；因此，您不必修改其他 SharePoint 檔案，如 Web.config。

關聯事件代碼

1. 在 SharePoint 網站上，瀏覽至要與該事件代碼相關聯的文件庫。

2. 在連結列中，單擊“修改設定和欄”。

3. 在“常規設定”部分中，單擊“更改進階設定”。

4. 如果您使用本文中提供的樣本託管程式集，則在“事件處理常式”部分的“程式集名稱”文字框中，鍵入以下內容：

   WSSEventSink, Version=1.0.0.2, Culture=neutral, PublicKeyToken=25a7f6c72becfbbb

   注 如果您建立了自己的代碼，則需要用與您的託管程式集相應的值來更新 Version 和 PublicKeyToken 值。

5. 在“類名”文字框中，鍵入以下內容：

   WSSEventSink.EventSink

6. 單擊“確定”。

現在，您已經將自訂的事件處理常式代碼與文件庫相關聯。

返回頁首 小結

本文概述了如何啟用 Microsoft Windows SharePoint Services 中文件庫的事件記錄訊息。本文深入介紹了如何使用 Microsoft Visual Studio .NET 2003 來建立事件處理常式，並提供了一個可讓您用於部署 Microsoft SharePoint 產品和技術的程式碼範例。要查看該代碼的樣本結果集，請參閱“附錄 A — 樣本安裝”。

返回頁首 附錄 A — 樣本安裝

以下樣本事件基於本文中使用的自訂事件代碼。要開啟事件檢視器，請單擊“開始”，指向“管理工具”，然後單擊“事件檢視器”。顯示事件檢視器的預設視圖。

圖 2. 事件檢視器的預設視圖

顯示樣本事件的屬性。

圖 3. 樣本事件

以下樣本顯示該事件的完整說明：

Event occurred in <Shared Documents>Event type was <Insert>Item that caused the event was <Shared Documents/sample.docItem field details are as follows ->Field name = <Created Date>    Value = <08/07/2003 12:00:58>Field name = <Created By>    Value = <1; user_name\administrator>Field name = <Last Modified>    Value = <08/07/2003 12:00:58>Field name = <Modified By>    Value = <1; user_name\administrator>Field name = <Approval Status>    Value = <0>Field name = <Approver Comments>    Value = <>Field name = <URL Path>    Value = </sites/site_name/Shared Documents/Steps to enable events for sample.doc>Field name = <URL Dir Name>    Value = <11; sites/site_name/Shared Documents>Field name = <Modified>    Value = <08/07/2003 12:00:58>Field name = <Created>    Value = <08/07/2003 12:00:58>Field name = <File Size>    Value = <193024>Field name = <File System Object Type>    Value = <0>Field name = <ID of the User who has the item checked out>    Value = <11; >Field name = <Name>    Value = <Steps to enable events for sample.doc>Field name = <Virus Status>    Value = <11; 193024>Field name = <Checked Out To>    Value = <11; >Field name = <Checked Out To>    Value = <11; >Field name = <Document Modified By>    Value = <user_name\administrator>Field name = <Document Created By>    Value = <user_name\administrator>Field name = <File Type>    Value = <doc>Field name = <HTML File Type>    Value = <>Field name = <Source Url>    Value = <>Field name = <Shared File Index>    Value = <>Field name = <Name>    Value = <Steps to enable events for sample.doc>Field name = <Name>    Value = <Steps to enable events for sample.doc>Field name = <Select>    Value = <11>Field name = <Select>    Value = <11>Field name = <Edit>    Value = <>Field name = <Type>    Value = <doc>Field name = <Server-based Relative URL>    Value = </sites/site_name/Shared Documents/sample.doc>Field name = <Encoded Absolute URL>    Value = <http://server_name/sites/site_name/Shared%20Documents/sample.doc>Field name = <Name>    Value = <Steps to enable events for sample.doc>Field name = <File Size>    Value = <193024>Field name = <InstanceID>    Value = <>Field name = <Title>    Value = <Steps to enable events for sample.doc>

返回頁首 附錄 B — 樣本事件代碼

以下範例程式碼可用於建立自訂事件處理常式。該代碼使用 Microsoft Visual Studio .NET 2003 以 Microsoft Visual Basic_ .NET 編寫。

Option Explicit On Imports SystemImports System.IOImports Microsoft.SharePointPublic Class EventSink : Implements IListEventSink    Public Sub OnEvent(ByVal listEvent As Microsoft.SharePoint.SPListEvent) ImplementsMicrosoft.SharePoint.IListEventSink.OnEvent        On Error Resume Next        Dim SharePointWeb As SPWeb = listEvent.Site.OpenWeb()        Dim SharePointEventItem As SPFile = SharePointWeb.GetFile(listEvent.UrlAfter)        Dim oItem As SPListItem = SharePointEventItem.Item        Dim oField As SPField        Dim oFields As SPFieldCollection        Dim sLog As String        'Check to make sure that we actually have the event item!        If SharePointEventItem Is Nothing Then            EventLog.WriteEntry("Event Log Test", "Cannot retrieve event item", EventLogEntryType.Information, listEvent.Type)            Exit Sub        End If        'Get the fields collection for the Event Item        oFields = oItem.Fields        'Inform the user of some top-level information such as the source of the event        sLog = "Event occurred in <" + listEvent.Title + ">" + vbCrLf        sLog = sLog + "Event type was <" + listEvent.Type.ToString + ">" + vbCrLf + vbCrLf        'The delete event carries no useful information to log in the fields collection        If (Len(listEvent.UrlAfter.ToString) > 1) Then            sLog = sLog + "Item that caused the event was <" + listEvent.UrlAfter.ToString + ">" + vbCrLf + vbCrLf            sLog = sLog + "Item field details are as follows ->" + vbCrLf + vbCrLf            'Iterate through the items fields and detail them            For Each oField In oFields                sLog = sLog + "Field name = <" + oField.Title.ToString + "> " + vbCrLf + vbTab + "Value = <" + oItem(oField.Title.ToString) + ">" + vbCrLf            Next        End If        'Event Id Explanation        '  -1 : Invalid        '   0 : Insert        '   1 : Update        '   2 : Delete()        '   3 : Move or Rename        '   4 : Copy        '   5 : CheckIn        '   6 : CheckOut        '   7 : UnCheckOut        'Write out the collected information to the Application Log        EventLog.WriteEntry("Event Log Test", sLog, EventLogEntryType.Information, listEvent.Type)        'This is just some sample code that shows how to operate on the different        '  event types.        Select Case listEvent.Type            Case SPListEventType.CheckIn                'Perform necessary actions for the CheckIn event            Case SPListEventType.CheckOut                'Perform necessary actions for the CheckOut event            Case SPListEventType.Copy                'Perform necessary actions for the Copy event            Case SPListEventType.Delete                'Perform necessary actions for the Delete event            Case SPListEventType.Insert                'Perform necessary actions for the Insert event            Case SPListEventType.Invalid                'Perform necessary actions for the Invalid event            Case SPListEventType.Move                'Perform necessary actions for the Move event            Case SPListEventType.UncheckOut                'Perform necessary actions for the UnCheckOut event            Case SPListEventType.Update                'Perform necessary actions for the Update event        End Select    End Sub 'OnEventEnd Class 'EventSink