通过创建故障排除工具箱简化 SharePoint 调试

引言

这一系列文章旨在帮助您快速掌握 SharePoint 编程。内容涵盖编写、排除故障和调试 SharePoint 代码。首先，您需要具备 .NET 开发，尤其是 ASP.NET 开发的先决技能，还应基本了解 SharePoint 及其用户界面的使用方法。您必须能够创建和部署功能，并应有处理内容类型和网站列的一些经验。

准备好了吗？让我们开始吧！

“Bug”和“Debugging”（调试）是程序员生活的常态。总的来说，调试是一项漫长而乏味的任务。我认为，要想成为一名优秀的 SharePoint 开发人员，您必须知道如何对您的应用程序进行故障排除。诀窍在于，对于新接触该平台的人来说，SharePoint 调试可能非常复杂，这就是为什么我决定通过讲解如何简化 SharePoint 代码调试来开始我的系列文章，然后再深入 SharePoint 编程的世界。在文章的最后，我们将创建“SharePoint 故障排除工具箱”，该工具箱将在我们的系列文章“SharePoint 编程入门”中经常使用。

通过创建故障排除工具箱来简化 SharePoint 调试

在 WSS 或 MOSS 中进行调试与调试 ASP.NET 应用程序类似，但不幸的是，调试 SharePoint 中的自定义代码不像在 Visual Studio 中那样简单地按 F5 键即可完成。虽然 SharePoint 为 Web 应用程序开发提供了出色的平台，但调试它们可能会有些麻烦。在本文中，我将为您提供一些调试技巧，这些技巧可以使您的工作更轻松，并帮助您处理那些恼人的“发生意外错误”屏幕。此外，我还将介绍一些 SharePoint 社区提供的工具，这些工具可以简化 SharePoint 应用程序的故障排除和错误隔离，从而提高您的生产力。

当您遇到问题时，有五个主要资源可供您使用

1. 详细的错误消息
2. 将 Visual Studio 调试器附加到 W3WP.EXE
3. SharePoint 跟踪日志
4. Windows 事件日志
5. 调试和跟踪

1. 详细的错误消息与令人讨厌的页面！

通常，错误消息将是您第一个意识到出现问题的迹象。不幸的是，SharePoint 使用一个用户友好的（黄色和蓝色）错误页面来显示问题发生。是的，他们称之为用户友好的页面，但我们作为开发人员，称之为令人讨厌的页面。当我第一次编写 SharePoint 代码时，我收到了如下所示的屏幕截图

此错误页面指出一个程序集抛出了未处理的 System.Exception。有时，如果抛出异常的代码使用的比 System.Exception 更具体，或者在 Exception 类的构造函数中包含了一条消息，用户友好的错误页面将指明错误的性质。

我们需要获得比令人讨厌的“发生意外错误”更详细的错误消息。这可以通过修改 SharePoint 应用程序所在的虚拟目录中的 Web.Config 文件来完成。这些修改列在下表中。

Tag	Attribute	默认值	新值
customErrors	模式	On	Off 或 Remote Only（关闭或仅限远程）
SafeMode	CallStack（调用堆栈）	假	True
SafeMode	AllowPageLevelTrace（允许页面级别跟踪）	假	True

无自定义错误会每次都向所有客户端显示完整的错误。这通常在开发环境中用于，因为没有客户端在使用它。

仅限远程的自定义错误允许您仅向远程客户端显示自定义错误。这意味着，如果您在本地浏览 SharePoint 网站，您将获得完全详细的错误消息。但是，其他人将收到标准的 SharePoint 页面。

我建议使用 Debug Config 功能来自动化此过程。这只是一个功能，当您在 Web 应用程序上激活它时，它会自动调整整个场中指定 Web 应用程序的 Web.Config。

2. 将 Visual Studio 调试器附加到 W3WP.EXE

现在您有了带有堆栈跟踪的标准 ASP.NET 错误页面。好的，这非常有帮助，但您不想猜测问题可能是什么，然后随意更改代码来修复它。

为了避免老式的试错技术，您需要做的第一件事是启用调试。这可以通过在 SharePoint 应用程序所在的虚拟目录的 Web.Config 中将 compilation 元素的 debug 属性设置为 true 来实现，否则，Visual Studio 中的断点将显示但永远不会被使用。

完成此操作后，您还需要在 Visual Studio 中调试 SharePoint 代码，那就是将调试器附加到 W3WP.EXE。在 Visual Studio 中附加调试器将允许您逐行执行代码并精确定位错误发生的位置。

这确实很方便，但当我的一位同事开始 SharePoint 编程时，我总是收到他们提出的三个问题，所以我决定与您分享答案。

第一个问题是：有时，我设置了断点并附加到进程，但如果我调试部署到 GAC 的程序集，Visual Studio 会跳过加载符号，导致我无法调试代码。

很简单，打开“工具”->“选项”->“调试”。

您会找到一个名为“启用仅我的代码(仅托管)”的选项，如图所示，它默认是勾选的。取消选中此选项即可调试位于 GAC 中的程序集。.NET 开发人员普遍存在一个误解，尤其是 SharePoint 开发人员，认为为了调试已部署到 GAC 的程序集，您还需要将调试符号（PDB 文件）复制到 GAC。这在 .NET 的早期是正确的，但现在不再如此。

第二个问题是：当我尝试将调试器附加到 W3WP.exe 进程进行调试时，我总是看到多个实例。应该附加到哪个？

好的，这个也很简单。只需按照以下步骤操作。

• 打开命令提示符窗口，运行 IISAPP 以获取当前 W3WP.exe 实例的列表。

• 记下与您的 Web 应用程序对应的实例的 PID。
• 现在返回 VS，选择“调试”->“附加到进程”，然后附加到 ID 等于您在第 2 步中获取的 PID 的 W3wp.exe 实例 -> 单击“附加”。
• 现在您可以轻松地跟踪代码并找到错误的根源。

但问题仍然存在：为什么有时会有多个 w3wp.exe 实例？这是因为 SharePoint 管理中心站点集和 SSP 管理中心站点始终拥有自己的应用程序池，用于错误隔离。

第三个问题是：是否可以调试内联代码块？

实际上，我讨厌内联代码块，并且由于 JIT 编译器编译它们时会产生性能问题，因此最好避免使用它们。但答案是：是的，您可以做到。

那么，您现在知道调试过程了吗？非常无聊且重复，对吧？嗯，不能自动化吗？
幸运的是，Jonathan Dibble，一位才华横溢的开发人员，创建了一个非常方便的“Debugger Feature”，可以安装并激活在 SharePoint 网站上以自动化此过程。激活后，Debugger Feature 会在“网站操作”菜单中添加一个“附加调试器”菜单项。这比在 Visual Studio 中操作要极其有用且更快。

3. 统一日志服务 (SharePoint 跟踪日志)

有时，在激活功能、创建网站集或部署包时，您会收到错误屏幕。例如，几个月前，我在从自定义模板创建网站集时遇到了一个恼人的错误“文件未找到！”

SharePoint 跟踪日志可供您在需要排除自定义代码之前和之后的错误时使用。它们在部署和配置操作中非常有用，因为它们是有关 SharePoint 内部发生的一切信息的主要来源。

大多数 SharePoint 组件都使用统一日志服务 (ULS)。这些日志是普通的文本文件，您可以在 12 hive 中的 12\Logs 处找到它们。您可以通过 SharePoint 管理中心“操作”部分的“日志记录和报告”下的“诊断日志记录”链接来调整 ULS 设置，以控制日志文件中捕获的事件的详细程度。您可以为每个类别或所有类别修改设置（如图所示），从而修改捕获的事件数量。列表条目按从最关键到最不关键的顺序列出。我总是将所有类别都设置为 verbose（详细），因为在问题发生时，有时很难确定需要更改的类别。

如果您想按类别调整详细程度设置，请确保将“常规”类别对于跟踪日志记录的默认值（Verbose）保持不变，因为有关配置和部署过程的条目都记录在“常规”类别下。还要注意，更新所有类别会使您丢失对单个类别的更改。

当您选择增加 ULS 捕获的事件数量时，会发现日志文件非常混乱且难以使用，SharePoint 也没有内置的查看器。为了填补这一空白并简化故障排除，存在免费的第三方工具，如 LogViewer、SPTraceView 和 WSS/MOSS Log File Reader。一些实用工具（包括 SPTraceView）会聚合场中多个服务器的日志数据。

下一张图显示了 LogViewer 的实际运行情况。

我还要指出，您可以编写代码将日志记录到 MOSS 日志中。写入相同的跟踪日志消除了开发人员需要在其他地方（例如更常由系统管理员使用的 Windows 事件日志）记录其开发信息的需要。

使用上述代码片段的唯一限制是您无法设置日志事件级别（例如低、中、高），因为它在跟踪日志中始终显示为 High（高）。Logger 位于 12\ISAPI \Microsoft.Office.Server.dll 中，因此仅随 MOSS 安装提供，而不随 WSS 3.0 提供。

如果您需要在拥有错误级别完全控制的情况下写入 SharePoint 跟踪日志怎么办？这很容易做到，因为 MSDN 有一个很棒的 代码示例供您重用。我总是在我的功能中使用这段代码。

只需将该类添加到您的项目中，然后您就可以使用类似以下代码的内容写入日志。

TraceProvider.RegisterTraceProvider();
TraceProvider.WriteTrace(TraceProvider.TagFromString(”XXXX (必须是 4 个字母的标签)”), TraceProvider.StringToSeverity(”Exception 或 Information”), Guid.NewGuid(), “方法名称”, “程序集名称”, “项目名称”, “消息”);
TraceProvider.UnregisterTraceProvider();

4. Windows 事件日志

您应该将 Windows 事件日志包含在您的常规故障排除中，因为它有时包含 SharePoint 无法通过 ULS 记录的有价值条目。您可以像调整 ULS 的详细程度一样调整日志记录的详细程度。

可以从自定义代码将错误记录到系统事件日志，但您需要提升权限，如下所示。

5. 调试和跟踪

在您的 SharePoint 网站上线后，您将不再是唯一的使用者（希望如此），因此您需要有效的计划来追踪错误。

在这种情况下，System.Diagnostics.Debug 和 Trace 语句非常有用。与 DebugView 结合使用，您可以确定哪里出了问题！Debug 调用会从发布版本中删除，因此您应该在开发环境中使用它们。但是 Trace 调用会保留在发布代码中，因此会增加代码执行的开销，但当您无法附加调试器时（例如在暂存或生产环境中）它们非常有帮助。由于手动添加跟踪调用可能耗时，我强烈建议使用 ReSharper 等工具快速插入这些语句，而不是依赖于键入或复制粘贴。下一张图显示了使用 DebugView 的跟踪输出。

SharePoint 故障排除工具箱！

好的，让我们创建我们的调试工具箱。以下实用程序应该包含在我们的 SharePoint 调试工具箱中；在 SharePoint 开发漫长的旅程中，我们肯定会需要它们。

• Debug Config 功能
• Debugger Feature（调试器功能）
• LogViewer
• SharePoint Manager
• SPTraceView
• WSS/MOSS Log File Reader（WSS/MOSS 日志文件读取器）
• DebugView
• SPDisposeCheck
• ReSharper
• Fiddler（记录您计算机与互联网之间所有 HTTP 流量的 HTTP 调试代理）
• LogParser（用于 IIS 日志分析）
• Araxis（文件比较工具）
• CLR Profiler（CLR Profiler 允许开发人员查看其托管应用程序的分配配置文件）

摘要

这是帮助您开始 SharePoint 编程的系列文章的第一篇。在深入研究 SharePoint 代码之前，我决定向您介绍一些可以真正让您的工作更轻松的故障排除实用程序和工具，因为对于刚接触该平台的人来说，故障排除确实可能是一场噩梦。