排查本地应用程序预配问题

排查测试连接问题

配置预配代理和 Extensible Connectivity（ECMA）主机后，可以测试从 Microsoft Entra 预配服务到预配代理、ECMA 主机和应用程序的连接。若要执行此端到端测试，请在 Azure 门户中的应用程序中选择 “测试连接 ”。在测试连接之前，请确保在分配初始代理或更改代理后等待 10 到 20 分钟。如果在此之后测试连接失败，请尝试以下故障排除步骤：

检查代理和 ECMA 主机是否正在运行：
1. 在安装了代理的服务器上，打开服务，通过转到开始>运行>Services.msc。
2. 在 “服务”下，确保 Microsoft Entra Connect 预配代理，并 Microsoft ECMA2Host 服务存在，其状态为 “正在运行”。
检查 ECMA 连接器主机服务是否正在响应请求。
1. 在安装了代理的服务器上，启动 PowerShell。
2. 更改为安装了 ECMA 主机的文件夹，例如 C:\Program Files\Microsoft ECMA2Host。
3. 更改为子目录 Troubleshooting。
4. 在该目录中运行脚本 TestECMA2HostConnection.ps1 。出现提示时，提供连接器名称和机密令牌作为参数。
```
PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> .\TestECMA2HostConnection.ps1
Supply values for the following parameters:
ConnectorName: CORPDB1
SecretToken: ************
```
5. 此脚本发送 SCIM GET 或 POST 请求，以验证 ECMA 连接器主机是否正在运行并响应请求。如果输出未显示 HTTP 连接成功，请检查服务是否正在运行，并提供正确的机密令牌。
请前往 Azure 门户中的应用程序，选择 管理员连接，从代理的下拉列表中确认代理已激活。
检查提供的机密令牌是否与本地机密令牌相同。转到本地，再次提供机密令牌，然后将其复制到 Azure 门户。
确保已在 Azure 门户中向应用程序分配了一个或多个代理。
分配代理后，需要等待 10 到 20 分钟才能完成注册。在注册完成之前，连接性测试将无法正常工作。
确保使用的是尚未过期的有效证书。转到 ECMA 主机的 “设置” 选项卡以查看证书到期日期。如果证书已过期，请单击 Generate certificate 以生成新证书。
通过搜索 Microsoft Entra Connect 预配代理，转到 VM 上的任务栏来重启预配代理。右键单击“ 停止”，然后选择“ 开始”。
如果在重启 ECMA 连接器主机和预配代理，并等待初始导入完成后，仍然看到 The ECMA host is currently importing data from the target application，那么您可能需要在 Azure 门户中取消并重新开始配置应用程序的预配。
在 Azure 门户中提供租户 URL 时，请确保它遵循以下模式。您可以将 localhost 替换为您的主机名，但这不是必须的。将 connectorName 替换为您在 ECMA 主机中指定的连接器名称。错误消息“无效资源”通常表示 URL 不遵循预期格式。
```
https://localhost:8585/ecma2host_connectorName/scim
```
导航到以下文件夹以查看预配代理日志：

C:\ProgramData\Microsoft\Azure AD Connect Provisioning Agent\Trace
如果看到以下错误，请将服务帐户“NT SERVICE\AADConnectProvisioningAgent”添加到名为“性能日志用户”的本地组。这消除了“无法初始化指标收集器”异常错误，方法是允许帐户访问所需的注册表项：HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib
```
Unable to initialize metrics collector, exception: 'System.UnauthorizedAccessException: Access to the registry key 'Global' is denied.
```

配置 ECMA 主机时，请确保您提供的证书具有与 Windows 服务器主机名匹配的主题名称。 ECMA 主机生成的证书会自动执行此操作，但应仅用于测试目的。

Error code: SystemForCrossDomainIdentityManagementCredentialValidationUnavailable

Details: We received this unexpected response from your application: Received response from Web resource. Resource: https://localhost/Users?filter=PLACEHOLDER+eq+"8646d011-1693-4cd3-9ee6-0d7482ca2219" Operation: GET Response Status Code: InternalServerError Response Headers: Response Content: An error occurred while sending the request. Please check the service and try again.

无法配置 ECMA 主机、查看事件查看器中的日志或启动 ECMA 主机服务

若要解决以下问题，请以管理员身份运行 ECMA 主机配置向导：

打开 ECMA 主机向导时，我收到错误。
可以配置 ECMA 主机向导，但看不到 ECMA 主机日志。在这种情况下，需要以管理员身份打开 ECMA 主机配置向导，并设置连接器端到端。可以通过导出现有连接器并再次导入它来简化此步骤。
我可以配置 ECMA 主机向导，但无法启动 ECMA 主机服务。

启用详细日志记录

默认情况下，对于 ECMA 连接器主机， switchValue 设置为 Verbose。此设置将发出详细的日志记录，以帮助排查问题。如果您想将日志输出限制为仅显示错误，可以更改详细级别至Error。使用没有 Windows 集成身份验证的 SQL 连接器时，建议将其设置为switchValueError，以确保不会在日志中发出连接字符串。若要将详细级别更改为错误，请将两个位置的switchValue更新为“Error”，如下所示。

详细服务日志记录的文件位置是 C:\Program Files\Microsoft ECMA2Host\Service\Microsoft.ECMA2Host.Service.exe.config。

<?xml version="1.0" encoding="utf-8"?> 
<configuration> 
    <startup>  
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6" /> 
    </startup> 
    <appSettings> 
      <add key="Debug" value="true" /> 
    </appSettings> 
    <system.diagnostics> 
      <sources> 
    <source name="ConnectorsLog" switchValue="Error"> 
          <listeners> 
            <add initializeData="ConnectorsLog" type="System.Diagnostics.EventLogTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ConnectorsLog" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack"> 
              <filter type=""/> 
            </add> 
          </listeners> 
        </source> 
        <!-- Choose one of the following switchTrace:  Off, Error, Warning, Information, Verbose --> 
        <source name="ECMA2Host" switchValue="Error"> 
          <listeners>  
            <add initializeData="ECMA2Host" type="System.Diagnos

向导日志记录的文件位置 C:\Program Files\Microsoft ECMA2Host\Wizard\Microsoft.ECMA2Host.ConfigWizard.exe.config。

      <source name="ConnectorsLog" switchValue="Error"> 
        <listeners> 
          <add initializeData="ConnectorsLog" type="System.Diagnostics.EventLogTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ConnectorsLog" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack"> 
            <filter type=""/> 
          </add> 
        </listeners> 
      </source> 
      <!-- Choose one of the following switchTrace:  Off, Error, Warning, Information, Verbose --> 
      <source name="ECMA2Host" switchValue="Error"> 
        <listeners> 
          <add initializeData="ECMA2Host" type="System.Diagnostics.EventLogTraceListener, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ECMA2HostListener" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack" />

查询 ECMA 主机缓存

ECMA 主机在应用程序中具有一个用户缓存，该缓存根据在 ECMA 主机向导的属性页中指定的计划进行更新。若要查询缓存，请执行以下步骤：

将调试标志设置为 true.

请注意，将调试标志设置为 true 禁用 ECMA 主机上的身份验证。完成查询缓存后，需要将其设置回 false 并重启 ECMA 主机服务。

详细服务日志记录的文件位置为 C:\Program Files\Microsoft ECMA2Host\Service\Microsoft.ECMA2Host.Service.exe.config。
```
<?xml version="1.0" encoding="utf-8"?>
<configuration>
   <startup>  
       <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6" /> 
   </startup> 
   <appSettings> 
     <add key="Debug" value="true" /> 
   </appSettings> 
```
重新启动 Microsoft ECMA2Host 服务。
等待 ECMA 主机连接到目标系统，并从每个连接的系统重新读取其缓存。如果这些连接的系统中有许多用户，则此导入过程可能需要几分钟时间。
从安装了 ECMA 主机的服务器上查询此端点，将 {connector name} 替换为在 ECMA 主机的属性页中指定的连接器名称https://localhost:8585/ecma2host_{connectorName}/scim/cache。
1. 在安装了代理的服务器上，启动 PowerShell。
2. 更改为安装了 ECMA 主机的文件夹，例如 C:\Program Files\Microsoft ECMA2Host。
3. 更改为子目录 Troubleshooting。
4. 在该目录中运行脚本 TestECMA2HostConnection.ps1 ，并提供连接器名称和 ObjectTypePath 值 cache作为参数。出现提示时，键入为该连接器配置的机密令牌。
```
PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> .\TestECMA2HostConnection.ps1 -ConnectorName CORPDB1 -ObjectTypePath cache
Supply values for the following parameters:
SecretToken: ************
```
5. 此脚本发送 SCIM GET 请求来验证 ECMA 连接器主机是否正在运行并响应请求。如果输出未显示 HTTP 连接成功，请检查服务是否正在运行，并提供正确的机密令牌。
在查询缓存后，将调试标志设置回 false 或删除该设置。
重新启动 Microsoft ECMA2Host 服务。

缺少目标属性

预配服务会自动发现目标应用程序中的属性。如果在 Azure 门户中的目标属性列表中看到目标属性缺失，请执行以下步骤：

查看 ECMA 主机配置的 “选择属性 ”页，检查是否已选择该属性，以便将其公开到 Azure 门户。
确保 ECMA 主机服务正在运行。
将代理分配给企业应用程序后，完成测试连接步骤并保存管理员凭据，刷新浏览器。这将强制预配服务发出 /schemas 请求并发现目标属性。
查看 ECMA 主机日志，检查是否已发出 /schemas 请求，并查看响应中的属性。此信息对于支持排查问题非常有用。

以 zip 文件的形式从事件查看器收集日志

可以使用包含的脚本捕获 zip 文件中的事件日志并导出它们。

在安装了代理的服务器上，右键单击“开始”菜单中的 PowerShell，然后选择Run as administrator。
更改为安装了 ECMA 主机的文件夹，例如 C:\Program Files\Microsoft ECMA2Host。
更改为子目录 Troubleshooting。
在该目录中运行脚本 CollectTroubleshootingInfo.ps1 。
该脚本将在包含事件日志的目录中创建 ZIP 文件。

查看事件查看器中的事件

配置 ECMA 连接器主机架构映射后，启动服务，以便侦听传入连接。然后，监视传入请求。

选择 “开始 ”菜单，输入 事件查看器，然后选择 “事件查看器”。
在 事件查看器中，展开 应用程序和服务 日志，然后选择 Microsoft ECMA2Host 日志。
连接器主机收到更改后，事件将写入应用程序日志。

常见错误

Error	解决方案
无法加载文件或程序集“file:///C:\Program Files\Microsoft ECMA2Host\Service\ECMA\Cache\8b514472-c18a-4641-9a44-732c296534e8\Microsoft.IAM.Connector.GenericSql.dll”或其依赖项之一。访问被拒绝。	确保网络服务帐户对缓存文件夹具有“完全控制”权限。如果帐户具有权限，但 .NET 尝试创建连接器 DLL 的副本，则可能需要将 DLL 添加到全局程序集缓存。
对象的 DN 的 LDAP 样式无效。 DN： username@domain.com“或 `Target Site: ValidByLdapStyle`	确保在 ECMA 主机的“连接”页中未选中“DN 为定位点”复选框。确保在 ECMA 主机的“对象类型”页中选择“自动生成”复选框。有关详细信息，请参阅关于定位点属性和可分辨名称。
导出错误：自定义继续运行。 objectClass：根据语法，值的编号无效	确保映射到 `objectClass` 属性的预配仅包含目录服务器识别的对象类的名称。

了解传入 SCIM 请求的内容

Microsoft Entra ID 对预配代理和连接器主机发出的请求使用 SCIM 协议。从主机向应用发出的请求使用应用支持的协议。从主机到代理向 Microsoft Entra ID 的请求依赖于 SCIM。可以在教程中了解有关 SCIM 实现的详细信息：在 Microsoft Entra ID 中开发和计划 SCIM 终结点的预配。

Microsoft Entra 预配服务通常发出 get-user 调用，以便在三种情况下检查虚拟用户：在每个预配周期的开头，在执行按需预配之前，以及何时选择 测试连接 。此检查可确保目标终结点可用，并向 Microsoft Entra 预配服务返回符合 SCIM 的响应。

如何排查预配代理问题？

您可能会遇到以下错误情境。

代理未能启动

可能会收到一条错误消息，指出：

“服务”Microsoft Entra Connect 预配代理“无法启动。检查是否有足够的权限来启动系统服务。

此问题通常是由组策略引起的，该组策略阻止将权限应用于安装程序创建的本地 NT 服务登录帐户（NT SERVICE\AADConnectProvisioningAgent）。启动服务需要这些权限。

若要解决此问题，请执行以下操作:

使用管理员帐户登录到服务器。
通过导航到服务或转到开始运行Services.msc来开启服务。
在 “服务”下，双击 Microsoft Entra Connect 预配代理。
在 “登录 ”选项卡上， 将此帐户 更改为域管理员。然后重启服务。

此测试验证代理是否可以通过端口 443 与 Azure 通信。打开浏览器，然后从安装了代理的服务器转到上一个 URL。

代理超时或证书无效

尝试注册代理时，可能会收到以下错误消息。

显示代理程序超时的屏幕截图。

此问题通常是由于代理无法连接到混合标识服务而引起的，并要求配置 HTTP 代理。若要解决此问题，请配置出站代理。

配置代理支持使用出站代理。可以通过编辑代理配置文件 C:\Program Files\Azure AD Connect Provisioning Agent\AADConnectProvisioningAgent.exe.config对其进行配置。将以下行添加到该文件中，紧跟在结束 </configuration> 标记之前的文件末尾。将变量 [proxy-server] 和 [proxy-port] 替换为代理服务器名称和端口值。

    <system.net>
        <defaultProxy enabled="true" useDefaultCredentials="true">
            <proxy
                usesystemdefault="true"
                proxyaddress="http://[proxy-server]:[proxy-port]"
                bypassonlocal="true"
            />
        </defaultProxy>
    </system.net>

代理注册失败，出现安全错误

安装云预配代理时可能会收到错误消息。

此问题通常是由于本地 PowerShell 执行策略导致代理无法执行 PowerShell 注册脚本。

若要解决此问题，请更改服务器上的 PowerShell 执行策略。需要将计算机和用户策略设置为 “未定义 ”或 “RemoteSigned”。如果它们设置为 “不受限制”，你将看到此错误。有关详细信息，请参阅 PowerShell 执行策略。

日志文件

默认情况下，代理会发出最少的错误消息和堆栈跟踪信息。可以在文件夹 C：\ProgramData\Microsoft\Azure AD Connect 预配代理\Trace 中找到跟踪日志。

为了解决与代理相关的问题获取更多信息，请执行以下操作：

AADCloudSyncTools按照 PowerShell 模块中所述AADCloudSyncTools安装 PowerShell 模块，以便Microsoft Entra Connect 云同步。
使用 Export-AADCloudSyncToolsLogs PowerShell cmdlet 捕获信息。使用以下开关微调数据收集。使用：
- SkipVerboseTrace 只导出当前日志，而不会捕获详细日志（默认值为假）。
- TracingDurationMins 指定不同的捕获持续时间（默认值 = 3 分钟）。
- 用于指定其他输出路径的 OutputPath（默认值 = 用户的文档）。

通过使用 Microsoft Entra ID，可以监视云中的预配服务并在本地收集日志。预配服务会针对在同步过程中评估的每个用户发出日志。可以通过 Azure 门户 UI、API 和日志分析使用这些日志。 ECMA 主机还会在本地生成日志。它显示收到的每个预配请求以及发送到 Microsoft Entra ID 的响应。

代理安装失败

错误 System.ComponentModel.Win32Exception: The specified service already exists 指示以前的 ECMA 主机未成功卸载。卸载主机应用程序。转到程序文件并删除 ECMA 主机文件夹。可能需要存储配置文件进行备份。

以下错误指示未满足先决条件。确保已安装 .NET 4.7.1。

  Method Name : <>c__DisplayClass0_1 : 
  RegisterNotLoadedAssemblies Error during load assembly: System.Management.Automation.resources.dll
  --------- Outer Exception Data ---------
  Message: Could not load file or assembly 'file:///C:\Program Files\Microsoft ECMA2Host\Service\ECMA\System.Management.Automation.resources.dll' or one of its dependencies. The system cannot find the file specified.

使用 SQL 配置 ECMA 连接器主机时，我遇到了无效的 LDAP 样式 DN 错误。

默认情况下，泛型 SQL 连接器要求使用 LDAP 样式填充 DN（在第一个连接页中未选中“DN 为定位点”属性时）。在错误消息 Invalid LDAP style DN 或 Target Site: ValidByLdapStyle 中，你可能会看到 DN 字段包含用户主体名称 (UPN)，而不是连接器所期望的 LDAP 格式的 DN。

若要解决此错误消息，请确保在配置连接器时在对象类型页上选择 自动生成 。

有关详细信息，请参阅关于定位点属性和可分辨名称。

后续步骤

教程：ECMA 连接器主机通用 SQL 连接器

Last updated on 2026-03-27