第十一篇 Integration Services：日志记录

本篇文章是Integration Services系列的第十一篇，详细内容请参考原文。

---

简介
在前一篇，我们讨论了事件行为。我们分享了操纵事件冒泡默认行为的方法，介绍了父子模式。
在这一篇，我们会配置SSIS内置日志记录。我们会演示简单和高级日志配置，保存和查看日志配置，生成自定义日志消息。
SSIS任务事件
打开Precedence.dtsx包。你的控制流面板应该如图11.1所示：

图11.1
在第九篇和第十篇，我们关注在序列容器1.我们在Script Task 4和序列容器1上创建了OnError事件处理程序——我们描述为事件"监听器"。在第十篇，我们为Precedence.dtsx包添加一个OnError事件处理程序扩展了这个模式。对于每一个OnError事件处理程序，我们添加一个脚本任务来显示包含下面SSIS变量的消息对话框：
->System::ErrorCode
->System::ErrorDescription
->System::SourceName
在我们开始测试前，让我们验证和/或修改之前的Precedence.dtsx包的某些设置。首先，点击Precedence.dtsx包控制流的空白区并按F4显示属性。修改DisableEventHandlers属性为False，如图11.2所示：

图11.2
在我们做更多修改前，通过按F5在BIDS调试器下执行Precedence.dtsx包。对于"Succeed Script Task 2?"的选择不会影响演示的目的，但是现在以及这篇文章剩余部分我们会选择"是"按钮(图11.3)引起 Script Task 2成功。

图11.3
当提示"Succeed Script Task 4?"时，选择否按钮从Script Task 4引起一个错误事件：

图11.4
当Script Task 4产生一个错误事件，在第九篇中配置的OnError事件处理程序监听错误事件，然后执行，显示类似图11.5所示的消息对话框：

图11.5
但是错误事件并不会在这里停止，它会继续向上层冒泡，将执行结果传送到下一级：序列容器1，它包含Script Task 4.我们可以从序列容器1配置的OnError事件处理程序上看到类似图11.6的消息对话框:

图11.6
同样，错误继续冒泡到下一级：Precedence.dtsx，它包含序列容器1.我们可以从Precedence包配置的OnError事件处理程序上看到类似图11.7的消息对话框:

图11.7
一旦我们接受这个消息对话框，另一个显示Script Task 3完成的对话框会出现。接受Script Task 3的消息，让Precedence.dtsx包完成执行，最终如图10.8所示：

图10.8
事件监听者
SSIS中的任务、容器以及SSIS包对象被当作可执行文件。可执行文件产生/引起事件。SSIS事件处理程序监听并响应由任务和容器引起的事件。
SSIS事件以消息形式在可执行文件中传送。这些消息按照规则传送。其中一条规则是：消息从低级传送到高级。
SSIS日志也是监听者。
配置SSIS日志记录
为了配置SSIS日志记录，点击SSIS，在下拉菜单上选择日志记录，如图11.9所示：

图11.9
配置SSIS日志窗口显示如图11.10所示：

图11.10
可用的日志提供程序类型有：
->用于Windows事件日志的SSIS日志提供程序
->用于文本文件的SSIS日志提供程序
->用于XML文件的SSIS日志提供程序
->用于SQL Server的SSIS日志提供程序
->用于SQL Server Profiler的SSIS日志提供程序
选择文本文件提供程序，如图11.11所示：

图11.11
一旦选择"用于文本文件的SSIS日志提供程序"，点击添加按钮为Precedence.dtsx包添加一个文件文件日志，如图11.12所示：

图11.12
在配置SSIS日志窗口底部有一条重要的提示。它告诉我们接下来需要做什么，如图11.13所示：

图11.13
正如图11.13显示的消息说明，下一步是在容器树视图中选择复选框启用日志记录。为Precedence包启用SSIS日志记录功能，如图11.14所示：

图11.14
现在我们可以配置日志本身了。第一件我们要做的是为包(在容器树视图选择的)分配日志。我们通过日志前的复选框分配日志，如图11.15所示：

图11.15
一旦日志复制框勾选，就可以编辑名称和说明属性。配置属性是必须的。点击配置列的下拉菜单，选择"新建连接…"，如图11.16所示：

图11.16
连接管理器会创建一个新的文件连接管理器，并打开文件连接管理器编辑器，如图11.17所示：

图11.17
这个文件连接管理器用于配置文本文件日志的文件。在使用类型下拉列表选择"创建文件"。日志文件并不是每次SSIS包执行都会创建，只有当它不存在时才会创建。如果日志文件存在，日志数据会追加到后面。
当选择文件窗口出现，导航到My_First_SSIS_Project解决方案文件夹并创建一个名为"log"的新文件夹，如图11.18所示：

图11.18
打开新文件夹，键入文件名称MyLog.csv，如图11.19所示：

图11.19
点击"打开"按钮完成文件配置，如图11.20所示：

图11.20
点击确定按钮完成文件连接管理器配置。你的连接管理器页签应该如图11.21所示：

图11.21
我们已经为Precedence.dtsx包配置了一个文本文件日志。在BIDS调试器下执行包，然后用记录本打开MyLog.csv
记住，SSIS日志是能够监听事件的监听者。默认，日志监听者监听PackageStart和PackageEnd事件，如图11.22所示：

图11.22
添加事件
点击SSIS，在下拉菜单选择日志记录。当打开配置SSIS日志窗口，点击详细信息页签。这个列表看起来很熟悉。它就是我们在第九篇遇到的事件列表(图9.16)。如果你记得的话，所有的可执行文件引发事件。监听者——SSIS事件处理程序和SSIS日志记录，访问SSIS包中可执行文件收集的事件。如果我们往SSIS控制流添加不同的任务，我们就会在这个列表及事件处理程序列表看到额外的事件。
选择OnError和OnInformation事件，如图11.23所示：

图11.23
在BIDS调试器下执行Precedence.dtsx，Script Task 2成功，Script Task 4失败。打开MyLog.csv查看内容，如图11.24所示：

图11.24
跟随在最初PackageEnd事件之后的第一个条目是PackageStart事件，证明了日志文件不存在时创建，存在时追加。接下来三行是OnError事件。这里我们看到另一个事件冒泡现象，第一条OnError事件记录由Script Task 4引发，接着是序列容器1的OnError事件，然后是Precedence.dtsx包的OnError事件。最后事件记录是另一个PackageEnd事件。
高级日志配置
打开Precedence.dtsx包的配置日志窗口，点击详细信息页签。在详细信息页签的底部有三个按钮：高级、加载和保存，如图11.25所示：

图11.25
点击高级按钮显示SSIS日志记录信息/领域。图11.26显示了我们之前选择的OnError和OnInformation事件的所有信息/领域。

图11.26
让我们做些修改。去掉OnError和OnInformation事件的ExecutionID列。去掉OnError事件的DataBytes列,OnInformation事件的SourceID列。你的日志记录配置高级页面应该如图11.27所示：

图11.27
在我们离开高级页面前，点击保存按钮。当显示另存为对话框时，在文件名文本框中键入MyLogConfig，如图11.28所示：

图11.28
点击保存按钮将日志记录高级配置存储到XML文件中。为了演示它如何工作，清除日志记录高级配置如图11.29所示：

图11.29
点击加载按钮。当显示打开对话框，选择MyLogConfig文件并点击打开按钮，如图11.30所示：

图11.30
注意日志记录高级配置恢复为选择保存时的样子(图11.26)。You can use this functionality to encourage developers in an enterprise to collect similar logging fields from SSIS’ built-in logging.
点击确定按钮关闭配置SSIS日志窗口。
Raising Custom Events On-Demand, Part 1
SSIS自动产生的日志记录消息非常少。但是你可以手动增加被日志监听的事件，也就是生成自定义日志消息。
为了演示，打开Script Task 3的编辑器点击编辑脚本按钮。Public Sub Main()中的代码应该类似于代码11.1：

    Public Sub Main()
        Dim sTaskName As String = Dts.Variables("TaskName").Value.ToString
        MsgBox(sTaskName & " completed.")
        Dts.TaskResult = ScriptResults.Success
    End Sub

代码11.1
用代码11.2编辑代码：

    Public Sub Main()
        Dim sTaskName As String = Dts.Variables("TaskName").Value.ToString
        Dim sMsg As String = sTaskName & " completed."

        Dts.Events.FireInformation(, sTaskName, sMsg, "", , True)
        MsgBox(sMsg)

        Dts.TaskResult = ScriptResults.Success
    End Sub

代码11.2
首先，我们添加一个名为sMsg字符串类型的变量，并将它的值分配为sTaskName & " completed.然后，我们添加代码手动引发一个Information事件：Dts.Events.FireInformation(101,sTaskName,sMsg,"",0,True)。Dts.Events对象能够引发很多不同类型的事件，包括我们当前日志配置在监听的Error和Information事件。FireInformation有六个参数：informationCode (Integer),subComponent(String),description(String),helpFile(String),helpContext (Integer),and fireAgain(Boolean).InformationCode用于分组信息。我使用子组件来识别/区分任务事件。Description是我们想要记录的信息。HelpFile和helpContext用于链接到帮助主题。我从来不配置这些主题，因此我也不知道它们如何/是否工作。目前我所知道的是，FireAgain已被弃用——我把它设置为默认值True.脚本中的最后一处修改是用sMsg变量代替MsgBox语句。
关闭ssisscript编辑器，点击确定按钮关闭脚本任务编辑器。在BIDS调试器下执行Precedence.dtsx包，Script Task 2成功，Script Task 4失败。接受Script Task 3的完成消息框。
打开日志文件检查最新的消息记录，如图11.31所示：

图11.31
注意OnInformation事件也会冒泡，从Script Task 3到序列容器1，然后到Precedence.dtsx包。Script Task 3的OnInformation事件日志条目的完整文本如下：
OnInformation,WORK,WORK\Administrator,Script Task 3,,,2015/10/16 12:20:20,2015/10/16 12:20:20,101,0x,Script Task 3 completed.
Raising Custom Events On-Demand, Part 2
如果我们检查日志文件中的所有Error消息，我们看到类似下面的消息：
OnError,WORK,WORK\Administrator,Script Task 4,{223ec2c7-6a62-4faf-8069-48202668655c},,2015/10/16 12:20:18,2015/10/16 12:20:18,-1001,0x,Script Task 4 failed!
和Information事件相似，我们可以增加自定义Error事件。为了演示，打开Script Task 4的编辑器并点击编辑脚本按钮。我们看到这个操作已经在Script Task 4的Public Sub Main()代码中，如代码11.3所示：

    Public Sub Main()

        Dim sTaskName As String = Dts.Variables("TaskName").Value.ToString

        Dim iResponse As Integer
        iResponse = MsgBox("Succeed " & sTaskName & "?", _
                           MsgBoxStyle.YesNo + MsgBoxStyle.Question, _
                           sTaskName & " Success Question")
        If iResponse = vbYes Then
            Dts.TaskResult = ScriptResults.Success
        Else
            'Dts.TaskResult = ScriptResults.Failure
            Dts.Events.FireError(-, "Script Task 4", _
                                 "Script Task 4 failed!", "", )
        End If

    End Sub

代码11.3
日志文件中的OnError消息就是由代码11.3中的Dts.Events.FireError方法产生的。
总结
在这一篇，我们配置了SSIS内置日志记录，演示了简单和高级日志配置，保存并查看日志配置，生成自定义日志消息。