调试插件

项目
03/04/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

以下步骤说明如何调试在本地 Microsoft Dynamics 365 上执行的插件。要调试 Microsoft Dynamics 365 (online) 上的沙盒中执行的插件，必须按本主题下文中所述使用跟踪功能。

本主题内容

Debug a plug-in

调试沙盒插件

日志记录和跟踪

调试插件

注册并部署插件程序集。

如果在同一位置还有另一个程序集副本，并且由于该副本被 Microsoft Dynamics 365 锁定而无法覆盖，则必须重新启动执行插件的服务进程。有关正确的服务进程，请参阅下表。详细信息：注册和部署插件

配置调试程序。

在要运行插件的 Microsoft Dynamics 365 服务器上，将调试程序附加到进程。要确定进程，请参阅下表。

插件注册配置	服务进程
联机	w3wp.exe
脱机	Microsoft.Crm.Application.Hoster.exe
异步已注册插件（或自定义工作流程序集）	CrmAsyncService.exe
沙盒（隔离模式）	Microsoft.Crm.Sandbox.WorkerProcess.exe

如果有多个进程运行同一个可执行文件（例如多个 w3wp.exe 进程），请将调试程序附加到正在运行的可执行进程的所有实例上。接下来，在插件代码中设置一个或多个断点。

测试插件。

运行 Microsoft Dynamics 365 应用程序或其他使用 SDK 的自定义应用程序，然后执行可以引发插件执行的任何操作。例如，如果插件是为客户创建事件而注册的，则请创建一个新客户。
调试插件代码。

对代码进行所需的更改，以便它可以按照您的需要执行。如果更改了代码，请将该代码编译为一个程序集，然后重复此过程中的步骤 1 到步骤 4（若有必要）。但是，如果您更改了插件程序集的主版本号或次版本号，则必须取消注册程序集的早期版本，然后注册新版本。详细信息：注册和部署插件
在数据库中注册插件。

在完成了插件的“编辑/编译/部署/测试/调试”周期后，请取消注册（磁盘上的）插件程序集，然后在 Microsoft Dynamics 365 数据库中重新注册该插件。详细信息：注册和部署插件

提示

可以调试数据库部署插件。必须将已编译的插件程序集的符号文件 (.pdb) 复制到服务器的 <crm-root>\Server\bin\assembly 文件夹下，且必须随后重新启动 Internet Information Services (IIS)。调试完成后，必须删除符号文件并重置 IIS，以免执行插件的进程占用额外的内存。

有关使用“插件探查器”工具调试插件的详细信息，请参阅分析插件性能。

调试沙盒插件

在首次执行沙盒插件之前，必须先执行以下步骤。如果已经执行过插件，则必须更改程序集的代码以更改服务器上的程序集哈希，或者在沙盒服务器上重新启动 Microsoft Dynamics 365 沙盒处理服务。

配置服务器

沙盒主机进程会监视执行插件的沙盒工作进程。主机进程将检查插件是否停止响应、是否超过内存阈值等。如果工作进程超过 30 秒未响应，则将关闭。为了调试沙盒插件，必须禁用此关闭功能。要禁用关闭功能，请将以下注册表项设置为 1 (DWORD)：

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM\SandboxDebugPlugins

调试插件

按照以下步骤调试沙盒插件。

在沙盒（隔离模式）中注册插件，并将其部署到 Microsoft Dynamics 365 服务器数据库中。
在运行名为 Microsoft.Crm.Sandbox.WorkerProcess.exe 的沙盒工作进程的服务器上，将已编译的插件程序集的符号文件 (.pdb) 复制到 server\bin\assembly 文件夹中。这是沙盒处理服务角色的宿主服务器。
按照本主题开始部分步骤 2 到步骤 4 中的说明进行操作。

有关使用“插件探查器”工具调试插件的详细信息，请参阅分析插件性能。

日志记录和跟踪

相对于在 Microsoft Visual Studio 中调试，排查插件或自定义工作流活动的另一种方法（自定义代码）是使用跟踪。跟踪功能可以记录运行时自定义信息，以帮助诊断代码失败的原因，从而为开发人员提供帮助。跟踪功能尤其适用于排查 Microsoft Dynamics 365 (online) 注册自定义代码，因为此方法是该情景所支持的唯一一种排查方法。在同步或异步执行期间，跟踪支持沙盒（部分信任）和完全信任注册的自定义代码。跟踪不支持在 Microsoft Dynamics 365 for Outlook 或其他移动客户端执行的自定义代码。

Microsoft Dynamics 365 运行时跟踪信息的记录由名为 ITracingService 的服务提供。自定义代码为此服务提供的信息可以在此处确定的三个不同位置记录。

跟踪日志

类型 PluginTraceLog 的跟踪日志记录可以在 Web 应用程序中通过导航到“设置”并选择“插件跟踪日志”磁贴找到。只能当您在分派的安全角色中有权访问跟踪日志实体记录时磁贴才可见。编写这些记录由下一节中所述的跟踪设置控制。有关 PluginTraceLog 实体所需权限的信息，请参阅实体特权。

备注

特别是当许多跟踪和异常生成时，跟踪日志记录占用组织储存空间。应只在调试和排查时打开跟踪日志记录，并在完成调查后将其关闭。
错误对话

将异常返回给平台的同步注册插件或自定义工作流活动会导致在呈现给登录用户的 Web 应用程序中出现错误对话框。用户可以选择对话框中的“下载日志文件”按钮查看包含异常和跟踪输出的日志。
系统作业

对于返回异常的异步注册插件或自定义工作流活动，跟踪信息会显示在 Web 应用程序“系统作业”窗体的“详细信息”区域中。

启用跟踪日志记录

若要在支持此功能的组织中启用跟踪日志记录，在 Web 应用程序中导航到“设置” > “管理” > 系统设置。在“自定义”选项卡中，找到标有“启用插件跟踪日志的日志记录”的下拉菜单并选择其中一个可用选项。

选项	说明
关闭	写入跟踪日志禁用。不会创建 PluginTraceLog 记录。但是，自定义代码仍可以调用 Trace 方法，但不写入日志。
异常	如果异常从自定义代码传递回平台，跟踪信息将写入到日志。
所有	代码完成或异常从自定义代码传递回平台后，跟踪信息将写入到日志。

如果记录设置为“异常”，您的自定义代码会将异常返回给平台，跟踪日志记录将创建，然后跟踪信息也会写入到另一个位置。对于同步执行的自定义代码，信息在错误对话框中呈现给用户，对于异步代码，信息写入到相关系统作业中。

默认情况下，系统管理员和系统定制员角色都具有更改跟踪日志记录设置的所需权限，此设置存储在 TraceSettings 实体记录中。跟踪设置有一个组织范围。

写入到跟踪服务

在写入到跟踪服务之前，必须先从传递的执行上下文中提取跟踪服务对象。之后，只需将 Trace 调用添加到您的自定义代码，在该方法调用中将相应传递所有相关诊断信息。


//Extract the tracing service for use in debugging sandboxed plug-ins.
ITracingService tracingService =
    (ITracingService)serviceProvider.GetService(typeof(ITracingService));

// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

// For this sample, execute the plug-in code only while the client is online. 
tracingService.Trace("AdvancedPlugin: Verifying the client is not offline.");
if (context.IsExecutingOffline || context.IsOfflinePlayback)
    return;

// The InputParameters collection contains all the data passed 
// in the message request.
if (context.InputParameters.Contains("Target") &amp;&amp;
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the Input Parameters.
    tracingService.Trace
        ("AdvancedPlugin: Getting the target entity from Input Parameters.");
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the image entity from the Pre Entity Images.
    tracingService.Trace
        ("AdvancedPlugin: Getting image entity from PreEntityImages.");
    Entity image = (Entity)context.PreEntityImages["Target"];

接下来，构建并部署插件或自定义工作流活动。在自定义代码执行期间，在 Trace 方法调用中提供的信息将由 ITracingService 写入到跟踪日志实体记录中，前提是您的组织支持并启用，也可以在 Web 对话或系统作业中对用户可用，前面部分有述。写入跟踪日志的跟踪信息在跟踪设置中配置。有关详细信息，请参阅启用跟踪日志记录。

备注

如果您的自定义代码是在数据库事务内执行的，并且发生了导致事务回滚的异常，那么将撤消由您的代码所进行的所有实体数据更改。但是，回滚完成后，PluginTraceLog 记录将保持不变。

关于跟踪服务

ITracingService 通过 Trace 方法将为其提供的信息分批。自定义代码运行成功完成或发生异常后，信息将写入到新 PluginTraceLog 记录中。

PluginTraceLog 记录具有有限的生命周期。批量删除后台作业每天运行一次以删除从创建开始计算早于 24 小时的记录。如果需要，该作业可以禁用。

另请参阅

插件开发
 分析插件性能
 注册和部署插件
 事件执行管道
 编写插件
 插件隔离、信任和统计信息
 PluginTraceLog 实体消息和方法

Microsoft Dynamics 365

通过

调试插件

本主题内容

调试插件

调试沙盒插件

日志记录和跟踪

启用跟踪日志记录

写入到跟踪服务

关于跟踪服务

另请参阅

其他资源