USMT 日志文件

用户状态迁移工具 (USMT) 日志可用于监视迁移以及排查错误和迁移失败问题。 本文介绍用于启用 USMT 日志的可用命令行选项。 它还介绍了可用于配置的新 XML 元素:

  • 哪些类型的错误是致命的,应停止迁移。
  • 哪些类型是非致命的,应跳过,以便继续迁移。

日志命令行选项

下表描述了与日志相关的每个命令行选项,并提供了日志名称以及每个日志包含的信息类型的说明。

命令行选项 文件名 描述
/l[Path]FileName ScanState.exe.logLoadState.log 指定 ScanState 日志或 LoadState 日志的路径和文件名。
/progress[Path]FileName 指定进度日志的路径和文件名。 按完成百分比提供有关迁移状态的信息。
/v[VerbosityLevel] 不适用 请参阅 ScanState 语法中的监视选项
/listfiles[Path]FileName 指定 Listfiles 日志的路径和文件名。 提供已迁移的文件的列表。
将环境变量 MIG_ENABLE_DIAG 设置为 XML 文件的路径。 USMTDiag.xml 诊断日志包含详细的系统环境信息、用户环境信息,以及有关正在收集) migunit 及其内容的迁移单元 (信息。

注意

日志文件不能存储在 StorePath 中。 如果日志文件存储在 StorePath 中,则 USMT 运行时将覆盖日志文件。

ScanState 和 LoadState 日志

ScanStateLoadState 日志是在 ScanStateLoadState 工具运行时创建的文本文件。 这些日志可用于帮助监视迁移。 日志的内容取决于使用的命令行选项和指定的详细级别。 有关详细级别的详细信息,请参阅 ScanState 语法中的监视选项

进度日志

可以使用 选项创建 /progress 进度日志。 外部工具(如 Microsoft System Center Operations Manager)可以分析进度日志以更新监视系统。 每行中的前三个字段是固定的,如下所示:

  • 日期: 日期,格式为 dayshortNameOfTheMonthyear。 例如:2023 年 6 月 8 日。

  • 当地时间: 时间,格式为 hrsminutesseconds , (使用 24 小时制) 。 例如:13:49:13。

  • 迁移时间: 运行 USMT 的持续时间,格式为 hrs:minutes:seconds。 例如:00:00:20。

其余字段是键/值对,如下表所示。

注册表项
程序 ScanState.exeLoadState.exe
productVersion USMT 的完整产品版本号。
computerName 运行 USMT 的源计算机或目标计算机的名称。
commandLine 用于运行 USMT 的完整命令。
阶段 报告迁移中的新阶段正在启动。 此键可以是以下值之一:
  • 初始 化
  • 扫描
  • 收集
  • 储蓄
  • 估计
  • 应用
detectedUser
  • 对于 ScanState 工具,此密钥是在可以迁移的源计算机上检测到的用户 USMT。
  • 对于 LoadState 工具,此密钥是在可迁移的存储中检测到的用户 USMT。
includedInMigration 定义是否包含用于迁移的用户配置文件/组件。 有效值为 “是”“否”。
forUser 指定以下值之一:
  • 正在迁移的用户状态。
  • 此计算机,表示未与用户关联的文件和设置。
detectedComponent 指定 USMT 检测到的组件。
  • 对于 ScanState,此密钥是安装在源计算机上的组件或应用程序。
  • 对于 LoadState,此密钥是在存储中检测到的组件或应用程序。
totalSizeInMBToTransfer 要迁移的文件和设置的总大小 (MB) 。
totalPercentageCompleted 由 ScanStateLoadState 完成的迁移的总百分比。
collectingUser 指定要为其收集文件和设置的 ScanState 用户。
totalMinutesRemaining 迁移完成的估计时间(以分钟为单位)。
error 发生的非致命错误类型。 此键可以是以下值之一:
  • UnableToCopy:无法复制到存储,因为存储所在的磁盘已满。
  • UnableToOpen:无法打开文件进行迁移,因为另一个应用程序或服务在非共享模式下打开了该文件。
  • UnableToCopyCatalog:无法复制,因为存储已损坏。
  • UnableToAccessDevice:无法访问设备。
  • UnableToApply:无法将设置应用于目标计算机。
objectName 导致非严重错误的文件或设置的名称。
行动 USMT 针对非致命错误执行的操作。 这些值为:
  • 忽略:忽略了非致命错误,并且迁移仍在继续,因为在命令行上指定了 /c 选项。
  • 中止:停止迁移,因为未指定 /c 选项。
errorCode errorCode 或返回值。
numberOfIgnoredErrors USMT 忽略的非致命错误总数。
消息* 对应于 errorCode 的消息。

列出文件日志

列出文件日志 (Listfiles.txt) 提供了已迁移的文件的列表。 此列表可用于排查 XML 问题,也可以保留为已收集到迁移存储中的文件的记录。 “列表文件”日志仅适用于 ScanState.exe

诊断日志

可以通过将环境变量 MIG_ENABLE_DIAG 设置为 XML 文件的路径来获取诊断日志。

诊断日志包含:

  • 详细的系统环境信息。

  • 详细的用户环境信息。

  • 有关正在收集) 迁移单元的信息 (migunit 及其内容。

使用诊断日志

诊断日志实质上是迁移中包含的所有迁移单元 (migunit) 的报告。 migunit 是数据的集合。 在 XML 文件中,组件标识与 migunit 关联的 migunit。 迁移存储由迁移中的所有 migunit 组成。 诊断日志可用于验证迁移中包括了哪些 migunit,并且可用于在创作迁移 XML 文件时进行故障排除。

以下示例描述了可以使用诊断日志的常见方案。

为什么在为该文件创作“包含”规则时,此文件不迁移?

假设我们具有以下目录结构,并且我们希望数据目录与新文件夹中的新文本 Document.txt 文件一起包含在迁移中。 的 C:\data 目录包含:

12/21/2023  01:08 PM    <DIR>          .
12/21/2023  01:08 PM    <DIR>          ..
12/21/2023  01:08 PM    <DIR>          New Folder
12/21/2023  01:19 PM                13 test (1).txt
12/21/2023  01:19 PM                13 test.txt
               2 File(s)             26 bytes

C:\data\New Folder 目录包含:

12/21/2023  01:08 PM    <DIR>          .
12/21/2023  01:08 PM    <DIR>          ..
12/21/2023  01:08 PM                 0 New Text Document.txt
               1 File(s)              0 bytes

若要迁移这些文件,请编写以下迁移 XML:

<?xml version="1.0" encoding="UTF-8"?>
<migration urlid="http://www.microsoft.com/migration/1.0/TestSuite_BUGFIX">

<component context="System"  type="Application">
  <displayName>DATA1</displayName>
  <role role="Data">
    <rules>
      <include>
        <objectSet>
          <pattern type="File">c:\data\ [*]</pattern>
        </objectSet>
      </include>

    </rules>
  </role>
</component>
</migration>

但是,在测试迁移时,会注意到 新文本 Document.txt 文件未包含在迁移中。 若要排查此故障,可以使用环境变量 重复迁移,MIG_ENABLE_DIAG 设置以便生成诊断日志。 在诊断日志中搜索组件 DATA1 会显示以下 XML 部分:

<MigUnitList>
  <MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
    <Patterns Type="Include">
      <Pattern Type="File" Path="C:\data [*]"/>
    </Patterns>
  </MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
  <MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
    <Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data [test.txt]" SimObj="false" Success="true"/>
  </MigUnit>
</Perform>

此 XML 部分的分析显示处理迁移规则时创建的 migunit。 “ <执行”> 部分详细介绍了计划收集的实际文件和收集操作的结果。 新文本 Document.txt 文件不会出现在此部分中,这确认未正确创作迁移规则。

XML 元素库参考文章的分析表明<,需要按如下所示修改模式>标记:

<pattern type="File">c:\data\* [*]</pattern>

使用修改后的标记再次执行迁移时,诊断日志会显示以下信息:

<MigUnitList>
  <MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
    <Patterns Type="Include">
      <Pattern Type="File" Path="C:\data\* [*]"/>
    </Patterns>
  </MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
  <MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
    <Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data [test.txt]" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data\New Folder" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data\New Folder [New Text Document.txt]" SimObj="false" Success="true"/>
  </MigUnit>
</Perform>

此诊断日志确认修改后的 <模式> 值允许迁移文件。

创建排除规则时,为什么此文件会迁移?

在此方案中,存在以下目录结构, 并且数据 目录中的所有文件都应迁移,文本文件除外。 文件夹 C:\Data 包含:

Directory of C:\Data

12/21/2023  01:08 PM    <DIR>          .
12/21/2023  01:08 PM    <DIR>          ..
12/21/2023  01:08 PM    <DIR>          New Folder
12/21/2023  01:19 PM                13 test (1).txt
12/21/2023  01:19 PM                13 test.txt
               2 File(s)             26 bytes

包含 C:\Data\New Folder\

12/21/2023  01:08 PM    <DIR>          .
12/21/2023  01:08 PM    <DIR>          ..
12/21/2023  01:08 PM                 0 New Text Document.txt
               1 File(s)              0 bytes

以下迁移 XML 是创作的:

<?xml version="1.0" encoding="UTF-8"?>
<migration urlid="http://www.microsoft.com/migration/1.0/TestSuite_BUGFIX">

<component context="System"  type="Application">
  <displayName>DATA1</displayName>
  <role role="Data">
    <rules>
      <include>
        <objectSet>
          <pattern type="File">c:\data\* [*]</pattern>
        </objectSet>
      </include>
    </rules>
    <rules>
      <exclude>
        <objectSet>
          <pattern type="File">c:\* [*.txt]</pattern>
        </objectSet>
      </exclude>

    </rules>
  </role>
</component>

但是,在测试迁移时,会注意到所有文本文件仍包含在迁移中。 为了解决此问题,可以使用环境变量 执行迁移,MIG_ENABLE_DIAG 设置,以便生成诊断日志。 在诊断日志中搜索组件 DATA1 会显示以下 XML 部分:

<MigUnitList>
  <MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
    <Patterns Type="Include">
      <Pattern Type="File" Path="C:\data\* [*]"/>
    </Patterns>
    <Patterns Type="Exclude">
      <Pattern Type="File" Path="C:\* [*.txt]"/>
    </Patterns>
  </MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
  <MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
    <Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data [test.docx]" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data [test.txt]" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data\New Folder" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data\New Folder [New Text Document.txt]" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data\New Folder [test.docx]" SimObj="false" Success="true"/>
  </MigUnit>
</Perform>

查看诊断日志时,确认文件仍在迁移,并且与创作的迁移 XML 规则存在问题。 将更新创作到迁移 XML 脚本,如下所示:

<?xml version="1.0" encoding="UTF-8"?>
<migration urlid="http://www.microsoft.com/migration/1.0/TestSuite_BUGFIX">

<component context="System"  type="Application">
  <displayName>DATA1</displayName>
  <role role="Data">
    <rules>
      <include>
        <objectSet>
          <pattern type="File">c:\data\* [*]</pattern>
        </objectSet>
      </include>
    </rules>
    <rules>
      <exclude>
        <objectSet>
          <pattern type="File">c:\data\* [*.txt]</pattern>
        </objectSet>
      </exclude>

    </rules>
  </role>
</component>


</migration>

修订后的迁移 XML 脚本将文件排除在迁移中,如诊断日志中确认的那样:

<MigUnitList>
  <MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
    <Patterns Type="Include">
      <Pattern Type="File" Path="C:\data\* [*]"/>
    </Patterns>
    <Patterns Type="Exclude">
      <Pattern Type="File" Path="C:\data\* [*.txt]"/>
    </Patterns>
  </MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
  <MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
    <Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data [test.docx]" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data\New Folder" SimObj="false" Success="true"/>
    <Operation Name="Store" Type="File" Path="C:\data\New Folder [test.docx]" SimObj="false" Success="true"/>
  </MigUnit>
</Perform>