deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-15 18:33:43 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

USMT Refresh 20

Browse Source
This commit is contained in:
Frank Rojas
2024-01-03 09:45:28 -05:00
parent 3379ff01a9
commit 2e890bd0b1
8 changed files with 113 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
windows/deployment/usmt/offline-migration-reference.md
View File

@ -102,8 +102,8 @@ System environment variables are necessary in the scenarios outlined in the foll
|Variable|Value|Scenario|
|--- |--- |--- |
|**USMT_WORKING_DIR**|Full path to a working directory|Required when USMT binaries are located on read-only media, which doesn't support the creation of log files or temporary storage. To set the system environment variable, at a command prompt type the following command: <br><br> `Set USMT_WORKING_DIR=<path to working directory>`|
|**MIG_OFFLINE_PLATFORM_ARCH**|32 or 64|While operating offline, this environment variable defines the architecture of the offline system, if the system doesn't match the WinPE and `ScanState.exe` architecture. This environment variable enables the 32-bit ScanState application to gather data from a computer with 64-bit architecture, or the 64-bit ScanState application to gather data from a computer with 32-bit architecture. Specifying the architecture is required when auto-detection of the offline architecture doesn't function properly. For example, to set this system environment variable for a 32-bit architecture, at a command prompt type the following command: <br><br> `Set MIG_OFFLINE_PLATFORM_ARCH=32`|
|**USMT_WORKING_DIR**|Full path to a working directory|Required when USMT binaries are located on read-only media, which doesn't support the creation of log files or temporary storage. To set the system environment variable, at a command prompt type the following command:<br><br> `Set USMT_WORKING_DIR=<path to working directory>`|
|**MIG_OFFLINE_PLATFORM_ARCH**|32 or 64|While operating offline, this environment variable defines the architecture of the offline system, if the system doesn't match the WinPE and `ScanState.exe` architecture. This environment variable enables the 32-bit ScanState application to gather data from a computer with 64-bit architecture, or the 64-bit ScanState application to gather data from a computer with 32-bit architecture. Specifying the architecture is required when auto-detection of the offline architecture doesn't function properly. For example, to set this system environment variable for a 32-bit architecture, at a command prompt type the following command:<br><br> `Set MIG_OFFLINE_PLATFORM_ARCH=32`|
## Offline.xml elements

16
windows/deployment/usmt/usmt-conflicts-and-precedence.md
View File

@ -134,26 +134,26 @@ These examples explain how USMT deals with **\<include\>** and **\<exclude\>** r
| <ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li></ul> | Migrates all files and subfolders in C:\Dir1, except the **.txt** files in C:\Dir1\Dir2 and its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\ * [.txt]\</pattern\></li></ul> | Migrates all files and subfolders in C:\Dir1, except the **.txt** files in C:\Dir1 and its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li></ul> | Nothing is migrated. | The rules are equally specific, so the **\<exclude\>** rule takes precedence over the **\<include\>** rule. |
| <ul><li>Include rule: C:\Dir1* [.txt]</li><li>Exclude rule: C:\Dir1\Dir2* []</li></ul> | Migrates the **.txt** files in Dir1 and the **.txt** files from subfolders other than Dir2. <br>No files are migrated from Dir2 or its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: C:\Dir1* [.txt]</li><li>Exclude rule: C:\Dir1\Dir2* []</li></ul> | Migrates the **.txt** files in Dir1 and the **.txt** files from subfolders other than Dir2.<br>No files are migrated from Dir2 or its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: C:\Dir1\Dir2* []</li><li>Exclude rule: C:\Dir1* [.txt]</li></ul> | Migrates all files and subfolders of Dir2, except the **.txt** files from Dir1 and any subfolders of Dir1 (including Dir2). | Both rules are processed as intended. |
| If the following code exists in different components | Resulting behavior | Explanation |
|-----|----|----|
| Component 1:<ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li></ul> <br>Component 2:<ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li></ul> | Migrates all files and subfolders of C:\Dir1\ (including C:\Dir1\Dir2). | Rules that are in different components don't affect each other, except for the **\<unconditionalExclude\>** rule. Therefore, in this example, although some **.txt** files were excluded when Component 1 was processed, they were included when Component 2 was processed. |
| Component 1:<ul><li>Include rule: C:\Dir1\Dir2* []</li></ul> <br>Component 2:<ul><li>Exclude rule: C:\Dir1* [.txt]</li></ul> | Migrates all files and subfolders from Dir2 except the **.txt** files in C:\Dir1 and its subfolders. | Both rules are processed as intended. |
| Component 1:<ul><li>Exclude rule: C:\Dir1\Dir2* []</li></ul> <br>Component 2:<ul><li>Include rule: C:\Dir1* [.txt]</li></ul> | Migrates all **.txt** files in Dir1 and any subfolders. | Component 1 doesn't contain an **\<include\>** rule, so the **\<exclude\>** rule isn't processed. |
| Component 1:<ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li></ul><br>Component 2:<ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li></ul> | Migrates all files and subfolders of C:\Dir1\ (including C:\Dir1\Dir2). | Rules that are in different components don't affect each other, except for the **\<unconditionalExclude\>** rule. Therefore, in this example, although some **.txt** files were excluded when Component 1 was processed, they were included when Component 2 was processed. |
| Component 1:<ul><li>Include rule: C:\Dir1\Dir2* []</li></ul><br>Component 2:<ul><li>Exclude rule: C:\Dir1* [.txt]</li></ul> | Migrates all files and subfolders from Dir2 except the **.txt** files in C:\Dir1 and its subfolders. | Both rules are processed as intended. |
| Component 1:<ul><li>Exclude rule: C:\Dir1\Dir2* []</li></ul><br>Component 2:<ul><li>Include rule: C:\Dir1* [.txt]</li></ul> | Migrates all **.txt** files in Dir1 and any subfolders. | Component 1 doesn't contain an **\<include\>** rule, so the **\<exclude\>** rule isn't processed. |
### Including and excluding registry objects
| If the following code exists in the same component | Resulting behavior | Explanation |
|-----|-----|-----|
| <ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor* []</li><li>Exclude Rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Migrates all keys in HKLM\Software\Microsoft\Command Processor except DefaultColor. | Both rules are processed as intended. |
| <ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude Rule: <br>HKLM\Software\Microsoft\Command Processor* []</li></ul> | Migrates only DefaultColor in HKLM\Software\Microsoft\Command Processor. | DefaultColor is migrated because the **\<include\>** rule is more specific than the **\<exclude\>** rule. |
| <ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Doesn't migrate DefaultColor. | The rules are equally specific, so the **\<exclude\>** rule takes precedence over the \<include\> rule. |
| <ul><li>Include rule:<br>HKLM\Software\Microsoft\Command Processor* []</li><li>Exclude Rule:<br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Migrates all keys in HKLM\Software\Microsoft\Command Processor except DefaultColor. | Both rules are processed as intended. |
| <ul><li>Include rule:<br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude Rule:<br>HKLM\Software\Microsoft\Command Processor* []</li></ul> | Migrates only DefaultColor in HKLM\Software\Microsoft\Command Processor. | DefaultColor is migrated because the **\<include\>** rule is more specific than the **\<exclude\>** rule. |
| <ul><li>Include rule:<br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude rule:<br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Doesn't migrate DefaultColor. | The rules are equally specific, so the **\<exclude\>** rule takes precedence over the \<include\> rule. |
| If the following code exists in different components | Resulting behavior | Explanation |
|-----|-----|-----|
| Component 1:<ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude rule: <br>HKLM\Software\Microsoft\Command Processor* []</li></ul> <br>Component 2:<ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor* []</li><li>Exclude rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Migrates all the keys/values under HKLM\Software\Microsoft\Command Processor. | Rules that are in different components don't affect each other, except for the **\<unconditionalExclude\>** rule. In this example, the objects that were excluded when Component 1 was processed were included when Component 2 was processed. |
| Component 1:<ul><li>Include rule:<br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude rule:<br>HKLM\Software\Microsoft\Command Processor* []</li></ul><br>Component 2:<ul><li>Include rule:<br>HKLM\Software\Microsoft\Command Processor* []</li><li>Exclude rule:<br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Migrates all the keys/values under HKLM\Software\Microsoft\Command Processor. | Rules that are in different components don't affect each other, except for the **\<unconditionalExclude\>** rule. In this example, the objects that were excluded when Component 1 was processed were included when Component 2 was processed. |
## File collisions

2
windows/deployment/usmt/usmt-determine-what-to-migrate.md
View File

@ -41,7 +41,7 @@ Using an SOE can vastly simplify the migration and reduce overall deployment cha
|[Identify users](usmt-identify-users.md)|Use command-line options to specify which users to migrate and how they should be migrated.|
|[Identify applications settings](usmt-identify-application-settings.md)|Determine which applications need to be migrated and prepare a list of application settings to be migrated.|
|[Identify operating system settings](usmt-identify-operating-system-settings.md)|Use migration to create a new standard environment on each of the destination computers.|
|[Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md)|For the following items that need to be migrated: <br><ul><li>File types.</li><li>Files.</li><li>Folders.</li><li>Settings.</li></ul> determine where these items might be located. For example:<ul><li>Standard default OS locations.</li><li>Organization-specified locations.</li><li>Non-standard locations.</li></ul>|
|[Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md)|For the following items that need to be migrated:<br><ul><li>File types.</li><li>Files.</li><li>Folders.</li><li>Settings.</li></ul> determine where these items might be located. For example:<ul><li>Standard default OS locations.</li><li>Organization-specified locations.</li><li>Non-standard locations.</li></ul>|
## Related articles

4
windows/deployment/usmt/usmt-hard-link-migration-store.md
View File

@ -149,8 +149,8 @@ A new section in the `Config.xml` file allows optional configuration of some of
| **\<Policies\>** | This element contains elements that describe the policies that USMT follows while creating a migration store. |
| **\<HardLinkStoreControl\>** | This element contains elements that describe how to handle files during the creation of a hard link migration store. |
| **\<fileLocked\>** | This element contains elements that describe how to handle files that are locked for editing. |
| **\<createHardLink\>** | This element defines a standard MigXML pattern that describes file paths where hard links should be created, even if the file is locked for editing by another application. <br><br>Syntax: `<createHardLink>` [pattern] `</createHardLink>` |
| **\<errorHardLink\>** | This element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created, if the file is locked for editing by another application. <br><br>`<errorHardLink>` [pattern] `</errorHardLink>` |
| **\<createHardLink\>** | This element defines a standard MigXML pattern that describes file paths where hard links should be created, even if the file is locked for editing by another application.<br><br>Syntax: `<createHardLink>` [pattern] `</createHardLink>` |
| **\<errorHardLink\>** | This element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created, if the file is locked for editing by another application.<br><br>`<errorHardLink>` [pattern] `</errorHardLink>` |
> [!IMPORTANT]
>

106
windows/deployment/usmt/usmt-loadstate-syntax.md
View File

@ -1,6 +1,6 @@
---
title: LoadState Syntax
description: Learn about the syntax and usage of the command-line options available when you use the LoadState command.
description: Learn about the syntax and usage of the command-line options available when using the LoadState command.
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
@ -17,32 +17,28 @@ appliesto:
The `LoadState.exe` command is used with the User State Migration Tool (USMT) to restore a store previously captured by the `ScanState.exe` command onto a destination computer. This article discusses the `LoadState.exe` command syntax and the options available with it.
## Before you begin
## Before beginning
Before you run the `LoadState.exe` command, note the following items:
Before running the `LoadState.exe` command, note the following items:
- To ensure that all operating system settings migrate, Microsoft recommends that you run the `LoadState.exe` commands in administrator mode from an account with administrative credentials.
- To ensure that all operating system settings migrate, Microsoft recommends running `LoadState.exe` commands in administrator mode from an account with administrative credentials.
- For information about software requirements for running the `LoadState.exe` command, see [USMT requirements](usmt-requirements.md).
- You should sign out after you run the `LoadState.exe` command. Some settings, such as example, fonts, wallpaper, and screensaver settings, won't take effect until the next time the user logs in.
- Sign out after running the `LoadState.exe` command. Some settings, such as example, fonts, wallpaper, and screensaver settings, won't take effect until the next time the user logs in.
- Unless otherwise specified, you can use each option only once when running a tool on the command line.
- Unless otherwise specified, each option can only be used once when running a tool from the command line.
- **LoadState** doesn't require domain controller access to apply domain profiles. This functionality is available without any additional configuration. It isn't necessary for the source computer to have domain controller access when the user profile was gathered using **ScanState**. However, domain profiles are inaccessible until the destination computer is joined to the domain.
- The [Incompatible command-line options](#incompatible-command-line-options) table lists which options you can use together and which command-line options are incompatible.
- The [Incompatible command-line options](#incompatible-command-line-options) table lists which options can be used together and which command-line options are incompatible.
## Syntax
This section explains the syntax and usage of the command-line options available when you use the `LoadState.exe` command. The options can be specified in any order. If the option contains a parameter, you can specify either a colon or space separator.
This section explains the syntax and usage of the command-line options available when using the `LoadState.exe` command. The options can be specified in any order. If the option contains a parameter, either a colon or space separator can be specified.
The `LoadState.exe` command's syntax is:
<!--
`LoadState.exe StorePath [/i:[Path\]FileName] [/v:VerbosityLevel] [/nocompress] [/decrypt /key:KeyString|/keyfile:[Path\]FileName] [/l:[Path\]FileName] [/progress:[Path\]FileName] [/r:TimesToRetry] [/w:SecondsToWait] [/c] [/all] [/ui:[DomainName|ComputerName\]UserName] [/ue:[[DomainName|ComputerName\]UserName] [/uel:NumberOfDays|YYYY/MM/DD|0] [/md:OldDomain:NewDomain] [/mu:OldDomain\OldUserName:[NewDomain\]NewUserName] [/lac:[Password]] [/lae] [/config:[Path\]FileName] [/?|help]`
-->
> LoadState.exe *StorePath* \[/i:\[*Path*\\\]*FileName*\] \[/v:*VerbosityLevel*\] \[/nocompress\] \[/decrypt /key:*KeyString*|/keyfile:\[Path\\\]*FileName*\] \[/l:\[*Path*\\\]*FileName*\] \[/progress:\[*Path*\\\]*FileName*\] \[/r:*TimesToRetry*\] \[/w:*SecondsToWait*\] \[/c\] \[/all\] \[/ui:\[*DomainName*|*ComputerName*\\\]*UserName*\] \[/ue:\[\[*DomainName*|*ComputerName*\\\]*UserName*\] \[/uel:*NumberOfDays*|*YYYY/MM/DD*|0\] \[/md:*OldDomain*:*NewDomain*\] \[/mu:*OldDomain*\\*OldUserName*:\[*NewDomain*\\\]*NewUserName*\] \[/lac:\[*Password*\]\] \[/lae\] \[/config:\[*Path*\\\]*FileName*\] \[/?|help\]
For example, to decrypt the store and migrate the files and settings to a computer, type the following command:
@ -51,58 +47,58 @@ For example, to decrypt the store and migrate the files and settings to a comput
## Storage options
USMT provides the following options that you can use to specify how and where the migrated data is stored.
USMT provides the following options that can be used to specify how and where the migrated data is stored.
| Command-Line Option | Description |
|--- |--- |
| **StorePath** | Indicates the folder where the files and settings data are stored. You must specify *StorePath* when using the `LoadState.exe` command. You can't specify more than one *StorePath*. |
| **/decrypt /key**:*KeyString* <br>or <br>**/decrypt /key**:"*Key String*" <br>or <br>**/decrypt /keyfile**:[*Path*]*FileName* | Decrypts the store with the specified key. With this option, the encryption key needs to be specified in one of the following ways:<ul><li>`/key`:*KeyString* specifies the encryption key. If there's a space in *KeyString*, you must surround the argument with quotation marks (`"`).</li><li>`/keyfile`:*FilePathAndName* specifies a text (`.txt`) file that contains the encryption key</li></ul> <br>*KeyString* can't exceed 256 characters. <br>The `/key` and `/keyfile` options can't be used on the same command line. <br>The `/decrypt` and `/nocompress` options can't be used on the same command line. <br><div class="alert">**Important** <br> Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `LoadState.exe` command with these options also have access to the encryption key.</div> <br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /decrypt /key:mykey` |
| **StorePath** | Indicates the folder where the files and settings data are stored. *StorePath* must be specified when using the `LoadState.exe` command. More than one *StorePath* can't be specified. |
| **/decrypt /key**:*KeyString*<br>or<br>**/decrypt /key**:"*Key String*"<br>or<br>**/decrypt /keyfile**:[*Path*]*FileName* | Decrypts the store with the specified key. With this option, the encryption key needs to be specified in one of the following ways:<ul><li>`/key`:*KeyString* specifies the encryption key. If there's a space in *KeyString*, the argument must be surrounded with quotation marks (`"`).</li><li>`/keyfile`:*FilePathAndName* specifies a text (`.txt`) file that contains the encryption key</li></ul><br>*KeyString* can't exceed 256 characters.<br>The `/key` and `/keyfile` options can't be used on the same command line.<br>The `/decrypt` and `/nocompress` options can't be used on the same command line.<br><div class="alert">**Important**<br> Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `LoadState.exe` command with these options also have access to the encryption key.</div><br>For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /decrypt /key:mykey` |
| **/decrypt**:*"encryption strength"* | The `/decrypt` option accepts a command-line parameter to define the encryption strength specified for the migration store encryption. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
| **/hardlink** | Enables user-state data to be restored from a hard-link migration store. The `/nocompress` parameter must be specified with `/hardlink` option. |
| **/nocompress** | Specifies that the store isn't compressed. You should only use this option in testing environments. Microsoft recommends that you use a compressed store during the actual migration. This option can't be used with the `/decrypt` option. <br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /nocompress` |
| **/nocompress** | Specifies that the store isn't compressed. This option should only be used in testing environments. Microsoft recommends using a compressed store during the actual migration. This option can't be used with the `/decrypt` option.<br>For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /nocompress` |
## Migration rule options
USMT provides the following options to specify what files you want to migrate.
USMT provides the following options to specify what files to migrate.
| Command-Line Option | Description |
|--- |--- |
| **/i**:[*Path*]*FileName* | **(include)** <br>Specifies an **.xml** file that contains rules that define what state to migrate. You can specify this option multiple times to include all of the **.xml** files (`MigApp.xml`, `MigSys.xml`, `MigDocs.xml` and any custom **.xml** files that you create). *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory. <br><br>For more information about which files to specify, see the &quot;XML files&quot; section of the [Frequently Asked Questions](usmt-faq.yml) article. |
| **/config**:[*Path*]*FileName* | Specifies the `Config.xml` file that the `LoadState.exe` command should use. You can't specify this option more than once on the command line. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the *FileName* must be located in the current directory. <br><br>This example migrates the files and settings based on the rules in the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files: <br><br>`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:5 /l:LoadState.log` |
| **/auto**:*"path to script files"* | This option enables you to specify the location of the default **.xml** files and then launch the migration. If no path is specified, USMT uses the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i:MigDocs.xml` `/i:MigApp.xml /v:5`. |
| **/i**:[*Path*]*FileName* | **(include)**<br>Specifies an **.xml** file that contains rules that define what data to migrate. This option can be specified multiple times to include all of the **.xml** files (`MigApp.xml`, `MigSys.xml`, `MigDocs.xml` and any custom **.xml** files that are created). *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory.<br><br>For more information about which files to specify, see the &quot;XML files&quot; section of the [Frequently Asked Questions](usmt-faq.yml) article. |
| **/config**:[*Path*]*FileName* | Specifies the `Config.xml` file that the `LoadState.exe` command should use. This option can't be specified more than once on the command line. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the *FileName* must be located in the current directory.<br><br>This example migrates the files and settings based on the rules in the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:<br><br>`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:5 /l:LoadState.log` |
| **/auto**:*"path to script files"* | This option enables specifying the location of the default **.xml** files. If no path is specified, USMT uses the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i:MigDocs.xml` `/i:MigApp.xml /v:5`. |
## Monitoring options
USMT provides several command-line options that you can use to analyze problems that occur during migration.
USMT provides several command-line options that can be used to analyze problems that occur during migration.
| Command-Line Option | Description |
|--- |--- |
| **/l**:[*Path*]*FileName* | Specifies the location and name of the **LoadState** log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the log is created in the current directory. You can specify the `/v` option to adjust the verbosity of the log. <br><br>If you run the `LoadState.exe` command from a shared network resource, you must specify the `l` option, or USMT fails with the error:<br><br>***USMT was unable to create the log file(s)***<br><br> To fix this issue, make sure to specify the `/l` option when running `LoadState.exe` from a shared network resource. |
| **/v**:*`<VerbosityLevel>`* | **(Verbosity)** <br><br>Enables verbose output in the **LoadState** log file. The default value is 0. <br>You can set the *VerbosityLevel* to one of the following levels:<ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul><br>For example: <br>`LoadState.exe \server\share\migration\mystore /v:5 /i:MigDocs.xml /i:MigApp.xml` |
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* is created in the current directory. <br><br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:loadlog.log` |
| **/c** | When this option is specified, the `LoadState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit on the computer, the `LoadState.exe` command logs an error and continue with the migration. Without the `/c` option, the `LoadState.exe` command exits on the first error. You can use the new \<**ErrorControl**\> section in the `Config.xml` file to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This error control enables the `/c` command-line option to safely skip all input/output (I/O) errors in the environment. In addition, the `/genconfig` option now generates a sample \<**ErrorControl**\> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r**:*`<TimesToRetry>`* | **(Retry)** <br><br>Specifies the number of times to retry when an error occurs while migrating the user state from a server. The default is three times. This option is useful in environments where network connectivity isn't reliable. <br><br>When the user state is being restored, the `/r` option doesn't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. |
| **/w**:*`<SecondsBeforeRetry>`* | **(Wait)** <br><br>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/l**:[*Path*]*FileName* | Specifies the location and name of the **LoadState** log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the log is created in the current directory. The `/v` option can be specified to adjust the verbosity of the log.<br><br>If running the `LoadState.exe` command from a shared network resource, the `l` option must be specified, or USMT fails with the error:<br><br>***USMT was unable to create the log file(s)***<br><br> To fix this issue, make sure to specify the `/l` option when running `LoadState.exe` from a shared network resource. |
| **/v**:*`<VerbosityLevel>`* | **(Verbosity)**<br><br>Enables verbose output in the **LoadState** log file. The default value is 0.<br>The *VerbosityLevel* can be set to one of the following levels:<ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul><br>For example:<br>`LoadState.exe \server\share\migration\mystore /v:5 /i:MigDocs.xml /i:MigApp.xml` |
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br><br>For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:loadlog.log` |
| **/c** | When this option is specified, the `LoadState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit on the computer, the `LoadState.exe` command logs an error and continue with the migration. Without the `/c` option, the `LoadState.exe` command exits on the first error. The \<**ErrorControl**\> section can be used in the `Config.xml` file to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This error control enables the `/c` command-line option to safely skip all input/output (I/O) errors in the environment. In addition, the `/genconfig` option now generates a sample \<**ErrorControl**\> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r**:*`<TimesToRetry>`* | **(Retry)**<br><br>Specifies the number of times to retry when an error occurs while migrating the user state from a server. The default is three times. This option is useful in environments where network connectivity isn't reliable.<br><br>When the user state is being restored, the `/r` option doesn't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. |
| **/w**:*`<SecondsBeforeRetry>`* | **(Wait)**<br><br>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/?** or **/help** | Displays Help on the command line. |
## User options
By default, all users are migrated. The only way to specify which users to include and exclude is by using the following options. You can't exclude users in the migration **.xml** files or by using the `Config.xml` file. For more information, see [Identify Users](usmt-identify-users.md).
By default, all users are migrated. The only way to specify which users to include and exclude is by using the following options. Users can't be excluded in the migration **.xml** files or by using the `Config.xml` file. For more information, see [Identify Users](usmt-identify-users.md).
| Command-Line Option | Description |
|--- |--- |
| **/all** | Migrates all of the users on the computer. <br><br>USMT migrates all user accounts on the computer, unless you specifically exclude an account with the `/ue` or `/uel` options. For this reason, you don't need to specify this option on the command line. However, if you choose to use the `/all` option, you can't also use the `/ui`, `/ue` or `/uel` options. |
| **/ui**:*DomainName UserName* <br>or <br>**/ui**:*"DomainName User Name"* <br>or <br>**/ui**:*ComputerName LocalUserName* | **(User include)** <br><br>Migrates the specified user. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` option. You can specify multiple `/ui` options, but you can't use the `/ui` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When user name that contains spaces is specified, it needs to be surrounded with quotations marks (`"`). <br><br>For example, to include only **User2** from the Corporate domain, enter: <br><br>`/ue:* /ui:corporate\user2`<br><br><div class="alert">**Note** <br>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.</div> <br> For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/uel**:*`<NumberOfDays>`* <br>or <br>**/uel**:*`<YYYY/MM/DD>`* <br>or <br>**/uel**:0 | **(User exclude based on last logon)** <br><br>Migrates only the users that logged onto the source computer within the specified time period, based on the **Last Modified** date of the **Ntuser.dat** file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose user account was modified, within the last 30 days from the date when the `ScanState.exe` command is run. You can specify the number of days or you can specify a date. You can't use this option with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when you run this option. In addition, if a domain user signs into another computer, USMT doesn't consider that sign-in instance. <div class="alert">**Note** <br>The `/uel` option isn't valid in offline migrations.</div> <br>Examples:<ul><li>`/uel:0` migrates accounts that were logged on to the source computer when the `ScanState.exe` command was run.</li><li>`/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose accounts were modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who logged on or whose accounts modified since February 15, 2020.</li></ul> <br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /uel:0` |
| **/ue**:*DomainName\UserName* <br>or <br>**/ue** *"DomainName\User Name"* <br>or <br>**/ue**:*ComputerName\LocalUserName* | **(User exclude)** <br><br>Excludes the specified users from the migration. You can specify multiple `/ue` options but you can't use the `/ue` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surround with quotation marks (`"`). <br><br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /ue:contoso\user1` <br>For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/md**:*OldDomain*:*NewDomain* <br>or <br>**/md**:*LocalComputerName:NewDomain* | **(Move domain)** <br><br>Specifies a new domain for the user. Use this option to change the domain for users on a computer or to migrate a local user to a domain account. *OldDomain* might contain the asterisk () wildcard character. <br><br>This option can be specified more than once. If consolidating users across multiple domains to a single domain, multiple `/md` options might need to be specified. For example, to consolidate the users from the Corporate and FarNorth domains into the Fabrikam domain, specify the following settings: `/md:corporate:fabrikam` and `/md:farnorth:fabrikam`. <br><br>If there are conflicts between two `/md` commands, the first rule that you specify is applied. For example, if you specify the `/md:corporate:fabrikam` and `/md:corporate:farnorth` commands, then Corporate users would be mapped to the Fabrikam domain. <div class="alert"> **Note** <br>If you specify an *OldDomain* that didn't exist on the source computer, the `LoadState.exe` command appears to complete successfully, without an error or warning. However, in this case, users aren't moved to *NewDomain* but instead remain in their original domain. For example, if you misspell **contoso** and you instead specify **/md:contso:fabrikam**, the users remain in **contoso** on the destination computer.</div> <br> For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br>` /progress:Progress.log /l:LoadState.log /md:contoso:fabrikam` |
| **/mu**:*OldDomain OldUserName*:[*NewDomain*]*NewUserName* <br>or <br>**/mu**:*OldLocalUserName*:*NewDomain NewUserName* | **(Move user)** <br><br>Specifies a new user name for the specified user. If the store contains more than one user, you can specify multiple `/mu` options. You can't use wildcard characters with this option. <br><br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br>`/progress:Progress.log /l:LoadState.log /mu:contoso\user1:fabrikam\user1` |
| **/lac**:[*Password*] | **(Local account create)** <br><br>If a user account is:<ul><li>A local (non-domain) account</li><li>An account that doesn't exist on the destination computer</li></ul>this setting specifies to create the account on the destination computer. However, the account is disabled. To enable the account, you must also use the `/lae` option. <br><br>If the `/lac` option isn't specified, any local user accounts that don't already exist on the destination computer aren't migrated. <br><br>*Password* is the password for the newly created account. An empty password is used by default. <div class="alert"> **Caution** <br>Use the *Password* variable with caution. The *Password* variable is provided in plain text and anyone with access to the computer that is running the `LoadState.exe` command can obtain the password. <br>Also, if the computer has multiple users, all migrated users have the same password.</div> <br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br><br>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |
| `/lae` | **(Local account enable)** <br><br>Enables the account that was created with the `/lac` option. You must specify the `/lac` option with this option. <br><br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br>`/progress:Progress.log /l:LoadState.log /lac:password /lae` <br><br>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |
| **/all** | Migrates all of the users on the computer.<br><br>USMT migrates all user accounts on the computer, unless an account is specifically excluded with the `/ue` or `/uel` options. For this reason, this option doesn't need to be specified on the command line. However, if using the `/all` option, the `/ui`, `/ue` or `/uel` options can't also be used. |
| **/ui**:*DomainName UserName*<br>or<br>**/ui**:*"DomainName User Name"*<br>or<br>**/ui**:*ComputerName LocalUserName* | **(User include)**<br><br>Migrates the specified user. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` option. Multiple `/ui` options can be specified, but the `/ui` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When user name that contains spaces is specified, it needs to be surrounded with quotations marks (`"`).<br><br>For example, to include only **User2** from the Corporate domain, enter:<br><br>`/ue:* /ui:corporate\user2`<br><br><div class="alert">**Note**<br>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.</div><br> For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/uel**:*`<NumberOfDays>`*<br>or<br>**/uel**:*`<YYYY/MM/DD>`*<br>or<br>**/uel**:0 | **(User exclude based on last logon)**<br><br>Migrates only the users that logged onto the source computer within the specified time period, based on the **Last Modified** date of the **Ntuser.dat** file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose user account was modified, within the last 30 days from the date when the `ScanState.exe` command is run. The number of days can be specified or a date can be specified. This option can't be used with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when running this option. In addition, if a domain user signs into another computer, USMT doesn't consider that sign-in instance. <div class="alert">**Note**<br>The `/uel` option isn't valid in offline migrations.</div><br>Examples:<ul><li>`/uel:0` migrates accounts that were logged on to the source computer when the `ScanState.exe` command was run.</li><li>`/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose accounts were modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who logged on or whose accounts modified since February 15, 2020.</li></ul><br>For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /uel:0` |
| **/ue**:*DomainName\UserName*<br>or<br>**/ue** *"DomainName\User Name"*<br>or<br>**/ue**:*ComputerName\LocalUserName* | **(User exclude)**<br><br>Excludes the specified users from the migration. Multiple `/ue` options can be used but the `/ue` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surround with quotation marks (`"`).<br><br>For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /ue:contoso\user1`<br>For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/md**:*OldDomain*:*NewDomain*<br>or<br>**/md**:*LocalComputerName:NewDomain* | **(Move domain)**<br><br>Specifies a new domain for the user. Use this option to change the domain for users on a computer or to migrate a local user to a domain account. *OldDomain* might contain the asterisk () wildcard character.<br><br>This option can be specified more than once. If consolidating users across multiple domains to a single domain, multiple `/md` options might need to be specified. For example, to consolidate the users from the Corporate and FarNorth domains into the Fabrikam domain, specify the following settings: `/md:corporate:fabrikam` and `/md:farnorth:fabrikam`.<br><br>If there are conflicts between two `/md` commands, the first rule specified is applied. For example, if the `/md:corporate:fabrikam` and `/md:corporate:farnorth` commands are specified, then Corporate users would be mapped to the Fabrikam domain. <div class="alert"> **Note**<br>If a domain that didn't exist on the source computer is specified, the `LoadState.exe` command appears to complete successfully, without an error or warning. However, in this case, users aren't moved to *NewDomain* but instead remain in their original domain. For example, if **contoso** is misspelled and instead **/md:contso:fabrikam** is specified, the users remain in **contoso** on the destination computer.</div><br> For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`<br>`/progress:Progress.log /l:LoadState.log /md:contoso:fabrikam` |
| **/mu**:*OldDomain OldUserName*:[*NewDomain*]*NewUserName*<br>or<br>**/mu**:*OldLocalUserName*:*NewDomain NewUserName* | **(Move user)**<br><br>Specifies a new user name for the specified user. If the store contains more than one user, multiple `/mu` options can be specified. Wildcard characters can't be used with this option.<br><br>For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`<br>`/progress:Progress.log /l:LoadState.log /mu:contoso\user1:fabrikam\user1` |
| **/lac**:[*Password*] | **(Local account create)**<br><br>If a user account is:<ul><li>A local (non-domain) account</li><li>An account that doesn't exist on the destination computer</li></ul>this setting specifies to create the account on the destination computer. However, the account is disabled. To enable the account, the `/lae` option must also be used.<br><br>If the `/lac` option isn't specified, any local user accounts that don't already exist on the destination computer aren't migrated.<br><br>*Password* is the password for the newly created account. An empty password is used by default. <div class="alert"> **Caution**<br>Use the *Password* variable with caution. The *Password* variable is provided in plain text and anyone with access to the computer that is running the `LoadState.exe` command can obtain the password.<br>Also, if the computer has multiple users, all migrated users have the same password.</div><br>For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`<br><br>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |
| `/lae` | **(Local account enable)**<br><br>Enables the account that was created with the `/lac` option. The `/lac` option must be specified with this option.<br><br>For example:<br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`<br>`/progress:Progress.log /l:LoadState.log /lac:password /lae`<br><br>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |
### Examples for the /ui and /ue options
The following examples apply to both the **/ui** and **/ue** options. You can replace the **/ue** option with the **/ui** option to include, rather than exclude, the specified users.
The following examples apply to both the **/ui** and **/ue** options. The **/ue** option can be replaced with the **/ui** option to include, rather than exclude, the specified users.
| Behavior | Command |
|--- |--- |
@ -115,43 +111,43 @@ The following examples apply to both the **/ui** and **/ue** options. You can re
### Using the options together
You can use the `/uel`, `/ue` and `/ui` options together to migrate only the users that you want migrated.
The `/uel`, `/ue` and `/ui` options can be used together to migrate only the users that need to be migrated.
**The /ui option has precedence over the /ue and /uel options.** If a user is included using the `/ui` option and also excluded using either the `/ue` or `/uel` options, the user is included in the migration. For example, if `/ui:contoso\* /ue:contoso\user1` is specified, then User1 is migrated, because the `/ui` option takes precedence over the `/ue` option.
**The /uel option takes precedence over the /ue option.** If a user logged on within the specified time period set by the `/uel` option, that user's profile is migrated even if they're excluded by using the `/ue` option. For example, if you specify `/ue:contoso\user1 /uel:14`, then User1 is migrated if they logged on to the computer within the last 14 days.
**The /uel option takes precedence over the /ue option.** If a user logged on within the specified time period set by the `/uel` option, that user's profile is migrated even if they're excluded by using the `/ue` option. For example, if `/ue:contoso\user1 /uel:14` is specified, then User1 is migrated if they logged on to the computer within the last 14 days.
| Behavior | Command |
|--- |--- |
| Include only User2 from the Fabrikam domain and exclude all other users. | `/ue:* /ui:fabrikam\user2` |
| Include only the local user named User1 and exclude all other users. | `/ue:* /ui:user1` |
| Include only the domain users from Contoso, except Contoso\User1. | This behavior can't be completed using a single command. Instead, to migrate this set of users, specify the following options:<ul><li>Using the **ScanState** command-line tool, enter: <br>`/ue:* /ui:contoso`</li><li>Using the **LoadState** command-line tool, enter: <br>`/ue:contoso\user1`</li></ul> |
| Include only the domain users from Contoso, except Contoso\User1. | This behavior can't be completed using a single command. Instead, to migrate this set of users, specify the following options:<ul><li>Using the **ScanState** command-line tool, enter:<br>`/ue:* /ui:contoso`</li><li>Using the **LoadState** command-line tool, enter:<br>`/ue:contoso\user1`</li></ul> |
| Include only local (non-domain) users. | `/ue: /ui:%computername%*` |
## Incompatible command-line options
The following table indicates which command-line options aren't compatible with the `LoadState.exe` command. If the table entry for a particular combination is blank, the options are compatible, and you can use them together. The X symbol means that the options aren't compatible. For example, you can't use the `/nocompress` option with the `/encrypt` option.
The following table indicates which command-line options aren't compatible with the `LoadState.exe` command. If the table entry for a particular combination is blank, the options are compatible, and they can be used together. The ❌ symbol means that the options aren't compatible. For example, the `/nocompress` option can't be used with the `/encrypt` option.
| Command-Line Option | /keyfile | /nocompress | /genconfig | /all |
|--- |--- |--- |--- |--- |
| **/i** | | | | |
| **/v** | | | | |
| **/nocompress** | | N/A | X | |
| **/key** | X | | X | |
| **/decrypt** | Required* | X | X | |
| **/keyfile** | N/A | | X | |
| **/nocompress** | | N/A | ❌ | |
| **/key** | ❌ | | ❌ | |
| **/decrypt** | Required* | ❌ | ❌ | |
| **/keyfile** | N/A | | ❌ | |
| **/l** | | | | |
| **/progress** | | | X | |
| **/r** | | | X | |
| **/w** | | | X | |
| **/c** | | | X | |
| **/p** | | | X | N/A |
| **/all** | | | X | |
| **/ui** | | | X | X |
| **/ue** | | | X | X |
| **/uel** | | | X | X |
| **/progress** | | | ❌ | |
| **/r** | | | ❌ | |
| **/w** | | | ❌ | |
| **/c** | | | ❌ | |
| **/p** | | | ❌ | N/A |
| **/all** | | | ❌ | |
| **/ui** | | | ❌ | ❌ |
| **/ue** | | | ❌ | ❌ |
| **/uel** | | | ❌ | ❌ |
| **/genconfig** | | | N/A | |
| **/config** | | | X | |
| **/config** | | | ❌ | |
| *StorePath* | | | | |
| **/md** | | | | |
| **/mu** | | | | |

26
windows/deployment/usmt/usmt-scanstate-syntax.md
View File

@ -61,11 +61,11 @@ To create an encrypted store using the `Config.xml` file and the default migrati
| **/apps** | Scans the image for apps and includes them and their associated registry settings. |
| **/ppkg** [*\<FileName\>*] | Exports to a specific file location. |
| **/o** | Required to overwrite any existing data in the migration store or `Config.xml` file. If not specified, the `ScanState.exe` command fails if the migration store already contains data. This option can't be used more than once on a command line. |
| **/vsc** | This option enables the volume shadow-copy service to migrate files that are locked or in use. This command-line option eliminates most file-locking errors that are typically encountered by the **\<ErrorControl\>** section. <br><br>This option is only used with the **ScanState** executable file and can't be combined with the `/hardlink` option. |
| **/vsc** | This option enables the volume shadow-copy service to migrate files that are locked or in use. This command-line option eliminates most file-locking errors that are typically encountered by the **\<ErrorControl\>** section.<br><br>This option is only used with the **ScanState** executable file and can't be combined with the `/hardlink` option. |
| **/hardlink** | Enables the creation of a hard-link migration store at the specified location. The `/nocompress` option must be specified with the `/hardlink` option. |
| **/encrypt** [{**/key:** *\<KeyString\>* &#124; **/keyfile**:*\<file\>*]} | Encrypts the store with the specified key. Encryption is disabled by default. With this option, the encryption key needs to be specified in one of the following ways: <ul><li>`/key`: *KeyString* specifies the encryption key. If there's a space in *KeyString*, *KeyString* needs to be surrounded with quotation marks (`"`).</li><li>`/keyfile`: *FilePathAndName* specifies a text (`.txt`) file that contains the encryption key.</li></ul> <br>*KeyString* is recommended to be at least eight characters long, but it can't exceed 256 characters. The `/key` and `/keyfile` options can't be used on the same command line. The `/encrypt` and `/nocompress` options can't be used on the same command line. <div class="alert">**Important**<br>Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `ScanState.exe` command with these options also have access to the encryption key.</div> <br>The following example shows the `ScanState.exe` command and the `/key` option: <br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /encrypt /key:mykey` |
| **/encrypt** [{**/key:** *\<KeyString\>* &#124; **/keyfile**:*\<file\>*]} | Encrypts the store with the specified key. Encryption is disabled by default. With this option, the encryption key needs to be specified in one of the following ways: <ul><li>`/key`: *KeyString* specifies the encryption key. If there's a space in *KeyString*, *KeyString* needs to be surrounded with quotation marks (`"`).</li><li>`/keyfile`: *FilePathAndName* specifies a text (`.txt`) file that contains the encryption key.</li></ul><br>*KeyString* is recommended to be at least eight characters long, but it can't exceed 256 characters. The `/key` and `/keyfile` options can't be used on the same command line. The `/encrypt` and `/nocompress` options can't be used on the same command line. <div class="alert">**Important**<br>Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `ScanState.exe` command with these options also have access to the encryption key.</div><br>The following example shows the `ScanState.exe` command and the `/key` option:<br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /encrypt /key:mykey` |
| **/encrypt**:*\<EncryptionStrength\>* | The `/encrypt` option accepts a command-line parameter to define the encryption strength to be used for encryption of the migration store. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
| **/nocompress** | Disables compression of data and saves the files to a hidden folder named &quot;File&quot; at *StorePath*\USMT. Compression is enabled by default. Combining the `/nocompress` option with the `/hardlink` option generates a hard-link migration store. The uncompressed store can be used to view what USMT stored, troubleshoot a problem, or run an antivirus utility against the files. This option should only be used in testing environments. Microsoft recommends using a compressed store during production migrations, unless combining the `/nocompress` option with the `/hardlink` option. <br><br>The `/nocompress` and `/encrypt` options can't be used together in one statement on the command line. However, if an uncompressed store is migrated, the `LoadState.exe` command migrates each file directly from the store to the correct location on the destination computer without a temporary location. <br><br>For example:<br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /nocompress` |
| **/nocompress** | Disables compression of data and saves the files to a hidden folder named &quot;File&quot; at *StorePath*\USMT. Compression is enabled by default. Combining the `/nocompress` option with the `/hardlink` option generates a hard-link migration store. The uncompressed store can be used to view what USMT stored, troubleshoot a problem, or run an antivirus utility against the files. This option should only be used in testing environments. Microsoft recommends using a compressed store during production migrations, unless combining the `/nocompress` option with the `/hardlink` option.<br><br>The `/nocompress` and `/encrypt` options can't be used together in one statement on the command line. However, if an uncompressed store is migrated, the `LoadState.exe` command migrates each file directly from the store to the correct location on the destination computer without a temporary location.<br><br>For example:<br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /nocompress` |
## Run the ScanState command on an offline Windows system
@ -106,10 +106,10 @@ USMT provides the following options to specify what files to migrate.
| Command-Line Option | Description |
|-----|-----|
| **/i:**[*Path*]*FileName* | **(include)** <br><br>Specifies an **.xml** file that contains rules that define what user, application, or system state to migrate. This option can be specified multiple times to include all of the **.xml** files (`MigApp.xml`, `MigDocs.xml`, and any custom **.xml** files that are created). *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory. For more information about which files to specify, see the &quot;XML Files&quot; section of the [Frequently asked questions](usmt-faq.yml) article. |
| **/genconfig:**[*Path*]*FileName* | (Generate **Config.xml**) <br><br>Generates the optional `Config.xml` file, but doesn't create a migration store. To ensure that this file contains everything that needs to be migrated, create this file on a source computer that contains all of the:<ul><li>components</li><li>applications</li><li>settings</li><li></ul>present on the destination computers. In addition, the other migration **.xml** files should be specified, using the **/i** option, when this option is specified.<br><br>After this file is created, it can be used with the `ScanState.exe` command using the **/config** option.<br><br>The only options that can be specified with this option are the `/i`, `/v`, and `/l` options. *StorePath* can't be specified, because the `/genconfig` option doesn't create a store. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br><br>Examples: <ul><li>The following example creates a `Config.xml` file in the current directory:<br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:13`</li></ul> |
| **/i:**[*Path*]*FileName* | **(include)**<br><br>Specifies an **.xml** file that contains rules that define what user, application, or system state to migrate. This option can be specified multiple times to include all of the **.xml** files (`MigApp.xml`, `MigDocs.xml`, and any custom **.xml** files that are created). *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory. For more information about which files to specify, see the &quot;XML Files&quot; section of the [Frequently asked questions](usmt-faq.yml) article. |
| **/genconfig:**[*Path*]*FileName* | (Generate **Config.xml**)<br><br>Generates the optional `Config.xml` file, but doesn't create a migration store. To ensure that this file contains everything that needs to be migrated, create this file on a source computer that contains all of the:<ul><li>components</li><li>applications</li><li>settings</li><li></ul>present on the destination computers. In addition, the other migration **.xml** files should be specified, using the **/i** option, when this option is specified.<br><br>After this file is created, it can be used with the `ScanState.exe` command using the **/config** option.<br><br>The only options that can be specified with this option are the `/i`, `/v`, and `/l` options. *StorePath* can't be specified, because the `/genconfig` option doesn't create a store. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br><br>Examples: <ul><li>The following example creates a `Config.xml` file in the current directory:<br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:13`</li></ul> |
| **/config:**[*Path*]*FileName* | Specifies the `Config.xml` file that the `ScanState.exe` command should use to create the store. This option can't be used more than once on the command line. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory.<br><br>The following example creates a store using the `Config.xml` file, `MigDocs.xml`, and `MigApp.xml` files:<br>`ScanState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log`<br><br>The following example migrates the files and settings to the destination computer using the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:<br>`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:LoadState.log` |
| **/auto:** *path to script files* | This option enables specifying the location of the default **.xml** files and then begin the migration. If no path is specified, USMT references the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i: MigDocs.xml /i:MigApp.xml /v:5`. |
| **/auto:** *path to script files* | This option enables specifying the location of the default **.xml** files. If no path is specified, USMT references the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i: MigDocs.xml /i:MigApp.xml /v:5`. |
| **/genmigxml:** *path to a file* | This option specifies that the `ScanState.exe` command should use the document finder to create and export an **.xml** file that defines how to migrate all of the files on the computer on which the `ScanState.exe` command is running. |
| **/localonly** | Migrates only files that are stored on the local computer, regardless of the rules in the **.xml** files that are specified on the command line. This option should be used to exclude the data from removable drives on the source computer and when there are network drives mapped on the source computer. Examples of removable drives include USB flash drives (UFDs) and some external hard drives. If the `/localonly` option isn't specified, then the `ScanState.exe` command copies files from these removable or network drives into the store.<br><br>`/localonly` excludes anything that isn't considered a fixed drive by the OS. In some cases, large external hard drives are considered fixed drives. These drives can be explicitly excluded from migration by using a custom **.xml** file. For more information about how to exclude all files on a specific drive, see [Exclude files and settings](usmt-exclude-files-and-settings.md).<br><br>The `/localonly` command-line option includes or excludes data in the migration as identified in the following storage locations:<ul><li>**Removable drives such as a USB flash drive** - Excluded</li><li>**Network drives** - Excluded</li><li>**Fixed drives** - Included</li></ul>|
@ -124,9 +124,9 @@ USMT provides several options that can be used to analyze problems that occur du
| Command-Line Option | Description |
|-----|-----|
| **/listfiles**:\<FileName\> | The `/listfiles` command-line option can be used with the `ScanState.exe` command to generate a text file that lists all of the files included in the migration. |
| **/l:**[*Path*]*FileName* | Specifies the location and name of the **ScanState** log. <br><br>The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the log is created in the current directory. The `/v` option can be used to adjust the amount of output. <br><br>If the `ScanState.exe` command is run from a shared network resource, the `/l` option must be specified, or USMT fails with the following error:<br><br>***USMT was unable to create the log file(s)***<br><br>To fix this issue, make sure to specify the `/l` option when running `ScanState.exe` from a shared network resource. |
| **/v:***\<VerbosityLevel\>* | **(Verbosity)**<br><br>Enables verbose output in the **ScanState** log file. The default value is 0. <br><br>The *VerbosityLevel* can be set to one of the following levels: <ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> <br>For example: <br>`ScanState.exe \server\share\migration\mystore /v:13 /i:MigDocs.xml /i:MigApp.xml`|
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br><br>For example: <br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:scanlog.log` |
| **/l:**[*Path*]*FileName* | Specifies the location and name of the **ScanState** log.<br><br>The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the log is created in the current directory. The `/v` option can be used to adjust the amount of output.<br><br>If the `ScanState.exe` command is run from a shared network resource, the `/l` option must be specified, or USMT fails with the following error:<br><br>***USMT was unable to create the log file(s)***<br><br>To fix this issue, make sure to specify the `/l` option when running `ScanState.exe` from a shared network resource. |
| **/v:***\<VerbosityLevel\>* | **(Verbosity)**<br><br>Enables verbose output in the **ScanState** log file. The default value is 0.<br><br>The *VerbosityLevel* can be set to one of the following levels: <ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul><br>For example:<br>`ScanState.exe \server\share\migration\mystore /v:13 /i:MigDocs.xml /i:MigApp.xml`|
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br><br>For example:<br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:scanlog.log` |
| **/c** | When this option is specified, the `ScanState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit in the store, the `ScanState.exe` command logs an error and continue with the migration. In addition, if a file is open or in use by an application, USMT might not be able to migrate the file and logs an error. Without the `/c` option, the `ScanState.exe` command exits on the first error.<br><br>The \<**ErrorControl**\> section in the `Config.xml` file can be used to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This advantage in the `Config.xml` file enables the `/c` command-line option to safely skip all input/output (I/O) errors in the environment. In addition, the /`genconfig` option now generates a sample \<**ErrorControl**\> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r:***\<TimesToRetry\>* | **(Retry)**<br><br>Specifies the number of times to retry when an error occurs while saving the user state to a server. The default is three times. This option is useful in environments where network connectivity isn't reliable.<br><br>When the user state is stored, the `/r` option can't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. |
| **/w:***\<SecondsBeforeRetry\>* | **(Wait)**<br><br>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
@ -139,9 +139,9 @@ By default, all users are migrated. The only way to specify which users to inclu
| Command-Line Option | Description |
|-----|-----|
| **/all** | Migrates all of the users on the computer. <br><br>USMT migrates all user accounts on the computer, unless an account is specifically excluded with either the `/ue` or `/uel` options. For this reason, this option doesn't need to be specified on the command line. However, if the `/all` option is specified, the `/ui`, `/ue` or `/uel` options can't also be specified. |
| **/ui**:*\<DomainName\>*&#92;*\<UserName\>*<br>or<br>**/ui**:*\<ComputerName\>*&#92;*\<LocalUserName\>* | **(User include)** <br><br>Migrates the specified users. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` or `/uel` options. Multiple `/ui` options can be specified, but the `/ui` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`). <div class="alert">**Note**<br>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.</div><br>For example:<br><ul><li>To include only **User2** from the Fabrikam domain, enter:<br><br>`/ue:*\* /ui:fabrikam\user2`<br><br></li><li>To migrate all users from the Fabrikam domain, and only the user accounts from other domains that are active or otherwise modified in the last 30 days, enter:<br><br>`/uel:30 /ui:fabrikam\*`<br><br>In this example, a user account from the Contoso domain that was last modified two months ago isn't migrated.</li></ul><br>For more examples, see the descriptions of the `/ue` and `/ui` options in this table. |
| **/uel**:*\<NumberOfDays\>*<br>or<br>**/uel**:*\<YYYY/MM/DD\>*<br>or<br>**/uel:0** | **(User exclude based on last logon)**<br><br>Migrates the users that logged on to the source computer within the specified time period, based on the **Last Modified** date of the Ntuser.dat file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose account was modified, within the last 30 days from the date when the `ScanState.exe` command is run.<br><br>The number of days or the date can be specified. This option can't be used with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when running this option. In addition, if a domain user signs in to another computer, USMT doesn't consider that sign-in instance. <div class="alert">**Note**<br>The `/uel` option isn't valid in offline migrations.</div><ul><li>`/uel:0` migrates any users who are currently logged on.</li><li>`/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose account were modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who logged on or been modified February 15, 2020 or afterwards.</li></ul> <br>For example: <br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \\server\share\migration\mystore /uel:0` |
| **/all** | Migrates all of the users on the computer.<br><br>USMT migrates all user accounts on the computer, unless an account is specifically excluded with either the `/ue` or `/uel` options. For this reason, this option doesn't need to be specified on the command line. However, if the `/all` option is specified, the `/ui`, `/ue` or `/uel` options can't also be specified. |
| **/ui**:*\<DomainName\>*&#92;*\<UserName\>*<br>or<br>**/ui**:*\<ComputerName\>*&#92;*\<LocalUserName\>* | **(User include)**<br><br>Migrates the specified users. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` or `/uel` options. Multiple `/ui` options can be specified, but the `/ui` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`). <div class="alert">**Note**<br>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.</div><br>For example:<br><ul><li>To include only **User2** from the Fabrikam domain, enter:<br><br>`/ue:*\* /ui:fabrikam\user2`<br><br></li><li>To migrate all users from the Fabrikam domain, and only the user accounts from other domains that are active or otherwise modified in the last 30 days, enter:<br><br>`/uel:30 /ui:fabrikam\*`<br><br>In this example, a user account from the Contoso domain that was last modified two months ago isn't migrated.</li></ul><br>For more examples, see the descriptions of the `/ue` and `/ui` options in this table. |
| **/uel**:*\<NumberOfDays\>*<br>or<br>**/uel**:*\<YYYY/MM/DD\>*<br>or<br>**/uel:0** | **(User exclude based on last logon)**<br><br>Migrates the users that logged on to the source computer within the specified time period, based on the **Last Modified** date of the Ntuser.dat file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose account was modified, within the last 30 days from the date when the `ScanState.exe` command is run.<br><br>The number of days or the date can be specified. This option can't be used with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when running this option. In addition, if a domain user signs in to another computer, USMT doesn't consider that sign-in instance. <div class="alert">**Note**<br>The `/uel` option isn't valid in offline migrations.</div><ul><li>`/uel:0` migrates any users who are currently logged on.</li><li>`/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose account were modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who logged on or been modified February 15, 2020 or afterwards.</li></ul><br>For example:<br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \\server\share\migration\mystore /uel:0` |
| **/ue**:*\<DomainName\>*&#92;*\<UserName\>*<br>-or-<br><br>**/ue**:*\<ComputerName\>*&#92;*\<LocalUserName\>* | **(User exclude)**<br><br>Excludes the specified users from the migration. Multiple `/ue` options can be specified. This option can't be used with the `/all` option. *\<DomainName\>* and *\<UserName\>* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`).<br><br>For example:<br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \\server\share\migration\mystore /ue:contoso\user1` |
## How to use /ui and /ue
@ -192,7 +192,7 @@ For more information, see [Migrate EFS Files and Certificates](usmt-migrate-efs-
| **/efs:abort** | Causes the `ScanState.exe` command to fail with an error code, if an Encrypting File System (EFS) file is found on the source computer. Enabled by default. |
| **/efs:skip** | Causes the `ScanState.exe` command to ignore EFS files. |
| **/efs:decryptcopy** | Causes the `ScanState.exe` command to decrypt the file, if possible, before saving it to the migration store, and to fail if the file can't be decrypted. If the `ScanState.exe` command succeeds, the file is unencrypted in the migration store, and once the `LoadState.exe` command is run, the file is copied to the destination computer. |
| **/efs:copyraw** | Causes the `ScanState.exe` command to copy the files in the encrypted format. The files are inaccessible on the destination computer until the EFS certificates are migrated. EFS certificates are automatically migrated; however, by default USMT fails if an encrypted file is found, unless the `/efs` option is specified. Therefore the `/efs:copyraw` option should be specified with the `ScanState.exe` command to migrate the encrypted file. When the `LoadState.exe` command is run, the encrypted file and the EFS certificate are automatically migrated.<br><br>For example: <br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /efs:copyraw` <div class="alert">**Important** <br>All files must be encrypted if the parent folder is encrypted. If the encryption attribute on a file inside an encrypted folder is removed, the file is encrypted during the migration using the credentials of the account used to run the **LoadState** tool. For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md).</div>|
| **/efs:copyraw** | Causes the `ScanState.exe` command to copy the files in the encrypted format. The files are inaccessible on the destination computer until the EFS certificates are migrated. EFS certificates are automatically migrated; however, by default USMT fails if an encrypted file is found, unless the `/efs` option is specified. Therefore the `/efs:copyraw` option should be specified with the `ScanState.exe` command to migrate the encrypted file. When the `LoadState.exe` command is run, the encrypted file and the EFS certificate are automatically migrated.<br><br>For example:<br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /efs:copyraw` <div class="alert">**Important**<br>All files must be encrypted if the parent folder is encrypted. If the encryption attribute on a file inside an encrypted folder is removed, the file is encrypted during the migration using the credentials of the account used to run the **LoadState** tool. For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md).</div>|
## Incompatible command-line options

10
windows/deployment/usmt/usmt-utilities.md
View File

@ -36,10 +36,10 @@ The syntax for `UsmtUtils.exe` is:
|Command-line Option|Description|
|--- |--- |
|**/ec**|Returns a list of supported cryptographic algorithms (AlgIDs) on the current system. This option can be used on a destination computer to determine which algorithm to use with the `/encrypt` command before running the **ScanState** tool on the source computer.|
|**/rd** *\<storeDir\>* |Removes the directory path specified by the *\<storeDir\>* argument on the computer. This command can be used to delete hard-link migration stores that can't otherwise be deleted at a command prompt due to a sharing lock. If the migration store spans multiple volumes on a given drive, the migration store is deleted from all of these volumes. <br><br>For example:<br>`UsmtUtils.exe /rd D:\MyHardLinkStore`|
|**/rd** *\<storeDir\>* |Removes the directory path specified by the *\<storeDir\>* argument on the computer. This command can be used to delete hard-link migration stores that can't otherwise be deleted at a command prompt due to a sharing lock. If the migration store spans multiple volumes on a given drive, the migration store is deleted from all of these volumes.<br><br>For example:<br>`UsmtUtils.exe /rd D:\MyHardLinkStore`|
|**/y**|Overrides the prompt to accept deletions when used with the `/rd` option. When the `/y` option is used with the `/rd` option, a prompt isn't displayed to accept the deletions before USMT deletes the directories.|
|**/verify**|Returns information on whether the compressed migration store is intact or whether it contains corrupted files or a corrupted catalog. <br><br>See [Verify options](#verify-options) for syntax and options to use with `/verify`.|
|**/extract**|Recovers files from a compressed USMT migration store. <br><br>See [Extract options](#extract-options) for syntax and options to use with `/extract`.|
|**/verify**|Returns information on whether the compressed migration store is intact or whether it contains corrupted files or a corrupted catalog.<br><br>See [Verify options](#verify-options) for syntax and options to use with `/verify`.|
|**/extract**|Recovers files from a compressed USMT migration store.<br><br>See [Extract options](#extract-options) for syntax and options to use with `/extract`.|
## Verify options
@ -52,7 +52,7 @@ The syntax for `/verify` is:
| Command-line Option | Description |
|-----|--------|
| *\<reportType\>* | Specifies whether to report on all files, corrupted files only, or the status of the catalog. <ul><li>**Summary**. Returns both the number of files that are intact and the number of files that are corrupted in the migration store. If no algorithm is specified, the summary report is displayed as a default.</li><li>**all**. Returns a tab-delimited list of all of the files in the compressed migration store and the status for each file. Each line contains the file name followed by a tab spacing, and either **CORRUPTED** or **OK** depending on the status of the file. The last entry reports the corruption status of the **CATALOG** of the store. A catalog file contains metadata for all files in a migration store. The **LoadState** tool requires a valid catalog file in order to open the migration store. Returns &quot;OK&quot; if the catalog file is intact and **LoadState** can open the migration store and &quot;CORRUPTED&quot; if the migration store is corrupted.</li><li>**failureonly**. Returns a tab-delimited list of only the files that are corrupted in the compressed migration store.</li><li>**Catalog**. Returns only the status of the catalog file.</li></ul> |
| **/l:** <br>*\<logfilePath\>* | Specifies the location and name of the log file. |
| **/l:**<br>*\<logfilePath\>* | Specifies the location and name of the log file. |
| **/v:** *\<VerbosityLevel\>* | **(Verbosity)**<br><br>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br><br>The *VerbosityLevel* can be set to one of the following levels:<br><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt** *\<AlgID\>* **/**:*\<KeyString\>*<br>or<br>**/decrypt** *\<AlgID\>* **/**:*\<"Key String"\>*<br>or<br>**/decrypt:** *\<AlgID\>* **/keyfile**:*\<FileName\>* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, specify a `/key` or `/keyfile` option as follows:<br><ul><li>*\<AlgID\>* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.<br>*\<AlgID\>* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li> `/key:` *\<KeyString\>* specifies the encryption key. If there's a space in *\<KeyString\>*, the argument must be surrounded with quotation marks.</li><li> `/keyfile`: *\<FileName\>* specifies the location and name of a text (.txt) file that contains the encryption key.</li></ul><br>For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
@ -76,7 +76,7 @@ The syntax for `/extract` is:
| Command-line Option | Description |
|-------|-----|
| *\<filePath\>* | Path to the USMT migration store. <br><br>For example:<br>`D:\MyMigrationStore\USMT\store.mig` |
| *\<filePath\>* | Path to the USMT migration store.<br><br>For example:<br>`D:\MyMigrationStore\USMT\store.mig` |
| *\<destinationPath\>* | Path to the folder where the tool puts the individual files. |
| **/i**:*\<includePattern\>* | Specifies a pattern for files to include in the extraction. More than one pattern can be specified. Separate patterns with a comma or a semicolon. The `/i`: *\<includePattern\>* and `/e`: *\<excludePattern\>* options can be used in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |
| **/e**:*\<excludePattern\>* | Specifies a pattern for files to omit from the extraction. More than one pattern can be specified. Separate patterns with a comma or a semicolon. The `/i`: *\<includePattern\>* and `/e`: *\<excludePattern\>* options can be used in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |

62
windows/deployment/usmt/usmt-xml-elements-library.md
View File

@ -29,7 +29,7 @@ The following table describes the XML elements and helper functions can be used
| Elements A-K | Elements L-Z | Helper functions |
|-----|----|-----|
| [\<addObjects\>](#addobjects) <br>[\<attributes\>](#attributes) <br>[\<bytes\>](#bytes) <br>[\<commandLine\>](#commandline) <br>[\<component\>](#component) <br>[\<condition\>](#condition) <br>[\<conditions\>](#conditions) <br>[\<content\>](#content) <br>[\<contentModify\>](#contentmodify) <br>[\<description\>](#description) <br>[\<destinationCleanup\>](#destinationcleanup) <br>[\<detect\>](#detect) <br>[\<detects\>](#detects) <br>[\<detection\>](#detection) <br>[\<displayName\>](#displayname) <br>[\<environment\>](#environment) <br>[\<exclude\>](#exclude) <br>[\<excludeAttributes\>](#excludeattributes) <br>[\<extensions\>](#extensions) <br>[\<extension\>](#extension) <br>[\<externalProcess\>](#externalprocess) <br>[\<icon\>](#icon) <br>[\<include\>](#include) <br>[\<includeAttribute\>](#includeattributes) | [\<library\>](#library) <br>[\<location\>](#location) <br>[\<locationModify\>](#locationmodify) <br>[\<_locDefinition\>](#_locdefinition) <br>[\<manufacturer\>](#manufacturer) <br>[\<merge\>](#merge) <br>[\<migration\>](#migration) <br>[\<namedElements\>](#namedelements) <br>[\<object\>](#object) <br>[\<objectSet\>](#objectset) <br>[\<path\>](#path) <br>[\<paths\>](#paths) <br>[\<pattern\>](#pattern) <br>[\<processing\>](#processing) <br>[\<plugin\>](#plugin) <br>[\<role\>](#role) <br>[\<rules\>](#rules) <br>[\<script\>](#script) <br>[\<text\>](#text) <br>[\<unconditionalExclude\>](#unconditionalexclude) <br>[\<variable\>](#variable) <br>[\<version\>](#version) <br>[\<windowsObjects\>](#windowsobjects) | [\<condition\> functions](#condition-functions) <br>[\<content\> functions](#content-functions) <br>[\<contentModify\> functions](#contentmodify-functions) <br>[\<include\> and \<exclude\> filter functions](#include-and-exclude-filter-functions) <br>[\<locationModify\> functions](#locationmodify-functions) <br>[\<merge\> functions](#merge-functions) <br>[\<script\> functions](#script-functions) <br>[Internal USMT functions](#internal-usmt-functions) |
| [\<addObjects\>](#addobjects)<br>[\<attributes\>](#attributes)<br>[\<bytes\>](#bytes)<br>[\<commandLine\>](#commandline)<br>[\<component\>](#component)<br>[\<condition\>](#condition)<br>[\<conditions\>](#conditions)<br>[\<content\>](#content)<br>[\<contentModify\>](#contentmodify)<br>[\<description\>](#description)<br>[\<destinationCleanup\>](#destinationcleanup)<br>[\<detect\>](#detect)<br>[\<detects\>](#detects)<br>[\<detection\>](#detection)<br>[\<displayName\>](#displayname)<br>[\<environment\>](#environment)<br>[\<exclude\>](#exclude)<br>[\<excludeAttributes\>](#excludeattributes)<br>[\<extensions\>](#extensions)<br>[\<extension\>](#extension)<br>[\<externalProcess\>](#externalprocess)<br>[\<icon\>](#icon)<br>[\<include\>](#include)<br>[\<includeAttribute\>](#includeattributes) | [\<library\>](#library)<br>[\<location\>](#location)<br>[\<locationModify\>](#locationmodify)<br>[\<_locDefinition\>](#_locdefinition)<br>[\<manufacturer\>](#manufacturer)<br>[\<merge\>](#merge)<br>[\<migration\>](#migration)<br>[\<namedElements\>](#namedelements)<br>[\<object\>](#object)<br>[\<objectSet\>](#objectset)<br>[\<path\>](#path)<br>[\<paths\>](#paths)<br>[\<pattern\>](#pattern)<br>[\<processing\>](#processing)<br>[\<plugin\>](#plugin)<br>[\<role\>](#role)<br>[\<rules\>](#rules)<br>[\<script\>](#script)<br>[\<text\>](#text)<br>[\<unconditionalExclude\>](#unconditionalexclude)<br>[\<variable\>](#variable)<br>[\<version\>](#version)<br>[\<windowsObjects\>](#windowsobjects) | [\<condition\> functions](#condition-functions)<br>[\<content\> functions](#content-functions)<br>[\<contentModify\> functions](#contentmodify-functions)<br>[\<include\> and \<exclude\> filter functions](#include-and-exclude-filter-functions)<br>[\<locationModify\> functions](#locationmodify-functions)<br>[\<merge\> functions](#merge-functions)<br>[\<script\> functions](#script-functions)<br>[Internal USMT functions](#internal-usmt-functions) |
## \<addObjects\>
@ -85,7 +85,7 @@ Syntax:
| Setting | Required? | Value |
|------|-----|----|
| *Content* | Yes | The content depends on the type of object specified. <br><ul><li>For files, the content can be a string containing any of the following attributes separated by commas:<ul><li>Archive</li><li>Read-only</li><li>System</li><li>Hidden</li></ul></li><li>For registry keys, the content can be one of the following types:<ul><li>None</li><li>String</li><li>ExpandString</li><li>Binary</li><li>Dword</li><li>REG_SZ</li></ul></li></ul>|
| *Content* | Yes | The content depends on the type of object specified.<br><ul><li>For files, the content can be a string containing any of the following attributes separated by commas:<ul><li>Archive</li><li>Read-only</li><li>System</li><li>Hidden</li></ul></li><li>For registry keys, the content can be one of the following types:<ul><li>None</li><li>String</li><li>ExpandString</li><li>Binary</li><li>Dword</li><li>REG_SZ</li></ul></li></ul>|
The following example is from the `MigApp.xml` file:
@ -176,9 +176,9 @@ hidden="Yes|No">
|Setting|Required?|Value|
|--- |--- |--- |
| type | Yes | The following items can be used to group settings, and define the type of the component.<ul><li>**System:** Operating system settings. All Windows components are defined by this type. <br>When **type="System"** and **defaultSupported="FALSE"**, the settings don't migrate unless there's an equivalent component in the **.xml** files that is specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file must be specified because the `LoadState.exe` tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name. Otherwise, the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer.</li><li>**Application:** Settings for an application.</li><li>**Device:** Settings for a device.</li><li>**Documents:** Specifies files.</li></ul> |
| context | No <br>Default = UserAndSystem | Defines the scope of this parameter; that is, whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the **\<component\>** element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it has a context of **User**. If a **\<rules\>** element has a context of **System**, it would act as though the **\<rules\>** element isn't there. <ul><li>**User**: Evaluates the component for each user.</li><li>**System**: Evaluates the component only once for the system.</li><li>**UserAndSystem**: Evaluates the component for the entire operating system and each user.</li></ul> |
| defaultSupported | No <br>(default = TRUE) | Can be any of **TRUE**, **FALSE**, **YES**, or **NO**. If this parameter is **FALSE** (or **NO**), the component isn't migrated unless there's an equivalent component on the destination computer. <br>When **type="System"** and **defaultSupported="FALSE"**, the settings aren't migrated unless there's an equivalent component in the **.xml** files that are specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file has to be specified in both command lines because the **LoadState** tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name or the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer. |
| type | Yes | The following items can be used to group settings, and define the type of the component.<ul><li>**System:** Operating system settings. All Windows components are defined by this type.<br>When **type="System"** and **defaultSupported="FALSE"**, the settings don't migrate unless there's an equivalent component in the **.xml** files that is specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file must be specified because the `LoadState.exe` tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name. Otherwise, the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer.</li><li>**Application:** Settings for an application.</li><li>**Device:** Settings for a device.</li><li>**Documents:** Specifies files.</li></ul> |
| context | No<br>Default = UserAndSystem | Defines the scope of this parameter; that is, whether to process this component in the context of the specific user, across the entire operating system, or both.<br>The largest possible scope is set by the **\<component\>** element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it has a context of **User**. If a **\<rules\>** element has a context of **System**, it would act as though the **\<rules\>** element isn't there. <ul><li>**User**: Evaluates the component for each user.</li><li>**System**: Evaluates the component only once for the system.</li><li>**UserAndSystem**: Evaluates the component for the entire operating system and each user.</li></ul> |
| defaultSupported | No<br>(default = TRUE) | Can be any of **TRUE**, **FALSE**, **YES**, or **NO**. If this parameter is **FALSE** (or **NO**), the component isn't migrated unless there's an equivalent component on the destination computer.<br>When **type="System"** and **defaultSupported="FALSE"**, the settings aren't migrated unless there's an equivalent component in the **.xml** files that are specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file has to be specified in both command lines because the **LoadState** tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name or the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer. |
| hidden | | This parameter is for internal USMT use only. |
For an example, see any of the default migration **.xml** files.
@ -205,7 +205,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|negation|No <br>Default = No|**"Yes"** reverses the True/False value of the condition.|
|negation|No<br>Default = No|**"Yes"** reverses the True/False value of the condition.|
|*ScriptName*|Yes|A script that is defined within this migration section.|
For example, in the following code sample, the **\<condition\>** elements, **A** and **B**, are joined together by the **AND** operator because they are in separate **\<conditions\>** sections:
@ -272,7 +272,7 @@ The **\<condition\>** functions return a Boolean value. These elements can be us
|Setting|Required?|Value|
|--- |--- |--- |
|*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"**, the result is **FALSE**.|
|*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`. <br><br>The **IsOSLaterThan** function returns **TRUE** if the current operating system is later than or equal to *OSVersion*.|
|*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`.<br><br>The **IsOSLaterThan** function returns **TRUE** if the current operating system is later than or equal to *OSVersion*.|
For example:
@ -289,7 +289,7 @@ The **\<condition\>** functions return a Boolean value. These elements can be us
|Setting|Required?|Value|
|--- |--- |--- |
|*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"** the result is **FALSE**.|
|*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`. <br><br>The **IsOSEarlierThan** function returns **TRUE** if the current operating system is earlier than *OSVersion*.|
|*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`.<br><br>The **IsOSEarlierThan** function returns **TRUE** if the current operating system is earlier than *OSVersion*.|
### Object content functions
@ -484,7 +484,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.<br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
### \<content\> functions
@ -571,7 +571,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2").` <br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2").`<br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
### \<contentModify\> functions
@ -664,7 +664,7 @@ The following functions change the content of objects as they're migrated. These
|Setting|Required?|Value|
|--- |--- |--- |
| *Delimiters* | Yes | A single character that is used to separate the content of the object that is being processed. The content is considered as a list of elements that is separated by the *Delimiters*. <br>For example, `"."` separates the string based on a period. |
| *Delimiters* | Yes | A single character that is used to separate the content of the object that is being processed. The content is considered as a list of elements that is separated by the *Delimiters*.<br>For example, `"."` separates the string based on a period. |
| *Instruction* | Yes | Can be one of the following values: <ul><li>**Add**: Adds *String* to the resulting MULTI-SZ if it isn't already there.</li><li>**Remove**: Removes *String* from the resulting MULTI-SZ.</li></ul> |
| *String* | Yes | The string to be added or removed. |
@ -718,7 +718,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.<br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
For example:
@ -756,8 +756,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| name | Yes, when **\<detect\>** is a child to **\<namedElements\>** <br>No, when **\<detect\>** is a child to \<detects\> | When *ID* is specified, any child elements aren't processed. Instead, any other **\<detect\>** elements with the same name that are declared within the **\<namedElements\>** element are processed. |
| context | No <br>(default = UserAndSystem) | Defines the scope of this parameter, which is whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the component element. For example, if a **\<component\>** element has a context of **User**, and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though the **\<rules\>** element weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
| name | Yes, when **\<detect\>** is a child to **\<namedElements\>**<br>No, when **\<detect\>** is a child to \<detects\> | When *ID* is specified, any child elements aren't processed. Instead, any other **\<detect\>** elements with the same name that are declared within the **\<namedElements\>** element are processed. |
| context | No<br>(default = UserAndSystem) | Defines the scope of this parameter, which is whether to process this component in the context of the specific user, across the entire operating system, or both.<br>The largest possible scope is set by the component element. For example, if a **\<component\>** element has a context of **User**, and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though the **\<rules\>** element weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
For examples, see the examples for [\<detection\>](#detection).
@ -782,8 +782,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| name | Yes, when \<detects\> is a child to **\<namedElements\>** <br>No, when \<detects\> is a child to **\<role\>** or **\<rules\>** | When *ID* is specified, no child **\<detect\>** elements are processed. Instead, any other **\<detects\>** elements with the same name that are declared within the **\<namedElements\>** element are processed. |
| context | No <br>(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the **\<component element\>**. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though the **\<rules\>** element weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> <br>The context parameter is ignored for **\<detects\>** elements that are inside **\<rules\>** elements. |
| name | Yes, when \<detects\> is a child to **\<namedElements\>**<br>No, when \<detects\> is a child to **\<role\>** or **\<rules\>** | When *ID* is specified, no child **\<detect\>** elements are processed. Instead, any other **\<detects\>** elements with the same name that are declared within the **\<namedElements\>** element are processed. |
| context | No<br>(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.<br>The largest possible scope is set by the **\<component element\>**. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though the **\<rules\>** element weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul><br>The context parameter is ignored for **\<detects\>** elements that are inside **\<rules\>** elements. |
The following example is from the `MigApp.xml` file.
@ -895,8 +895,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| name | Yes, when **\<environment\>** is a child of **\<namedElements\>** <br>No, when **\<environment\>** is a child of **\<role\>** or **\<component\>** | When declared as a child of the **\<role\>** or **\<component\>** elements, if *ID* is declared, USMT ignores the content of the **\<environment\>** element and the content of the **\<environment\>** element with the same name declared in the **\<namedElements\>** element is processed. |
| context | No <br>(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the **\<component\>** element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though **\<rules\>** weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
| name | Yes, when **\<environment\>** is a child of **\<namedElements\>**<br>No, when **\<environment\>** is a child of **\<role\>** or **\<component\>** | When declared as a child of the **\<role\>** or **\<component\>** elements, if *ID* is declared, USMT ignores the content of the **\<environment\>** element and the content of the **\<environment\>** element with the same name declared in the **\<namedElements\>** element is processed. |
| context | No<br>(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.<br>The largest possible scope is set by the **\<component\>** element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though **\<rules\>** weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
## Examples
@ -999,7 +999,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|filter|No <br>(default = No)|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|filter|No<br>(default = No)|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.<br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
For example, from the `MigUser.xml` file:
@ -1190,7 +1190,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| filter | No. <br>If this parameter isn't specified, then all patterns that are inside the child **\<objectSet\>** element are processed. | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. |
| filter | No.<br>If this parameter isn't specified, then all patterns that are inside the child **\<objectSet\>** element are processed. | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.<br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. |
The following example is from the `MigUser.xml` file:
@ -1359,7 +1359,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.<br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
The following example is from the `MigApp.xml` file:
@ -1478,7 +1478,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br><br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.<br><br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
The following example is from the `MigUser.xml` file:
@ -1525,7 +1525,7 @@ These functions control how collisions are resolved.
|Setting|Required?|Value|
|--- |--- |--- |
| *FilePattern* | Yes | <ul><li>**\<F\>** is replaced by the original file name.</li><li>**\<N\>** is replaced by an incrementing counter until there's no collision with the objects on the destination computer.</li><li>**\<E\>** is replaced by the original file name extension.</li></ul> <br>For example, `<F> (<N>).<E>` changes the source file `MyDocument.doc` into `MyDocument (1).doc` on the destination computer. |
| *FilePattern* | Yes | <ul><li>**\<F\>** is replaced by the original file name.</li><li>**\<N\>** is replaced by an incrementing counter until there's no collision with the objects on the destination computer.</li><li>**\<E\>** is replaced by the original file name extension.</li></ul><br>For example, `<F> (<N>).<E>` changes the source file `MyDocument.doc` into `MyDocument (1).doc` on the destination computer. |
- **NewestVersion**
@ -1600,7 +1600,7 @@ This filter helper function can be used to filter the migration of files based o
|--- |--- |
|Property|filesize, dateCreated, dateModified, dateAccessed|
|Operator|range, neq, lte, lt, eq, gte, gt|
|valueToCompare|The value that is being compared. For example: <br>Date: "2023/05/15-2020/05/17", "2023/05/15" <br>Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"|
|valueToCompare|The value that is being compared. For example:<br>Date: "2023/05/15-2020/05/17", "2023/05/15"<br>Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"|
```xml
<component context="System" type="Application">
@ -1753,8 +1753,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| type | Yes | *typeID* can be Registry, File, or Ini. If *typeId* is Ini, then a space between *Path* and *object* isn't allowed. For example, the following format is correct when type="Ini": <br>**\<pattern type="Ini"\>%WinAmp5InstPath%\Winamp.ini&#124;WinAmp[keeponscreen]\</pattern\>** |
| *Path* [*object*] | Yes | A valid registry or file path pattern, followed by at least one space, followed by brackets [] that contain the object to be migrated. <ul><li>*Path* can contain the asterisk (`*`) wildcard character or can be an [Recognized environment variables](usmt-recognized-environment-variables.md). The question mark can't be used as a wildcard character. `HKCU` and `HKLM` can be used to refer to `HKEY_CURRENT_USER` and `HKEY_LOCAL_MACHINE` respectively.</li><li>*Object* can contain the asterisk (`*`) wildcard character. However, the question mark can't be used as a wildcard character. For example: <br> **`C:\Folder\ [*]`** enumerates all files in `C:\Folder` but no subfolders of `C:\Folder`. <br> **`C:\Folder* [*]`** enumerates all files and subfolders of `C:\Folder`. <br> **`C:\Folder\ [*.mp3]`** enumerates all `.mp3` files in `C:\Folder`. <br> **`C:\Folder\ [Sample.doc]`** enumerates only the `Sample.doc` file located in C:\Folder. <div class="alert">**Note**<br>If migrating a file that has a square bracket character ([ or ]) in the file name, a carrot (^) character must be inserted directly before the bracket for it to be valid. For example, if there's a file named "file].txt", `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` must be specified instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
| type | Yes | *typeID* can be Registry, File, or Ini. If *typeId* is Ini, then a space between *Path* and *object* isn't allowed. For example, the following format is correct when type="Ini":<br>**\<pattern type="Ini"\>%WinAmp5InstPath%\Winamp.ini&#124;WinAmp[keeponscreen]\</pattern\>** |
| *Path* [*object*] | Yes | A valid registry or file path pattern, followed by at least one space, followed by brackets [] that contain the object to be migrated. <ul><li>*Path* can contain the asterisk (`*`) wildcard character or can be an [Recognized environment variables](usmt-recognized-environment-variables.md). The question mark can't be used as a wildcard character. `HKCU` and `HKLM` can be used to refer to `HKEY_CURRENT_USER` and `HKEY_LOCAL_MACHINE` respectively.</li><li>*Object* can contain the asterisk (`*`) wildcard character. However, the question mark can't be used as a wildcard character. For example:<br> **`C:\Folder\ [*]`** enumerates all files in `C:\Folder` but no subfolders of `C:\Folder`.<br> **`C:\Folder* [*]`** enumerates all files and subfolders of `C:\Folder`.<br> **`C:\Folder\ [*.mp3]`** enumerates all `.mp3` files in `C:\Folder`.<br> **`C:\Folder\ [Sample.doc]`** enumerates only the `Sample.doc` file located in C:\Folder. <div class="alert">**Note**<br>If migrating a file that has a square bracket character ([ or ]) in the file name, a carrot (^) character must be inserted directly before the bracket for it to be valid. For example, if there's a file named "file].txt", `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` must be specified instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
For example:
@ -1834,7 +1834,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| role | Yes | Defines the role for the component. Role can be one of: <ul><li>**Container**</li><li>**Binaries**</li><li>**Settings**</li><li>**Data**</li></ul> One of the following items can be specified: <ol><li>Up to three **\<role\>** elements within a **\<component\>** - one "Binaries" role element, one "Settings" role element and one "Data" role element. These parameters don't change the migration behavior - their only purpose is to help categorize the settings that are migrating. These **\<role\>** elements can be nested, but each nested element must be of the same role parameter.</li><li>One "Container" **\<role\>** element within a **\<component\>** element. In this case, any child **\<rules\>** elements can't be specified, only other **\<component\>** elements. And each child **\<component\>** element must have the same type as that of parent **\<component\>** element. For example:</li></ol> <pre class="syntax"><code>\<component context="UserAndSystem" type="Application"\> <br> \<displayName _locID="migapp.msoffice2016"\>Microsoft Office 2016\</displayName\> <br> \<environment name="GlobalEnv" /\> <br> \<role role="Container"\><br> \<detection name="AnyOffice2016Version" /\> <br> \<detection name="Word2016" /\> <br> \<!-- <br> Office 2016 Common Settings <br> --\> <br> \<component context="UserAndSystem" type="Application"\></code></pre> |
| role | Yes | Defines the role for the component. Role can be one of: <ul><li>**Container**</li><li>**Binaries**</li><li>**Settings**</li><li>**Data**</li></ul> One of the following items can be specified: <ol><li>Up to three **\<role\>** elements within a **\<component\>** - one "Binaries" role element, one "Settings" role element and one "Data" role element. These parameters don't change the migration behavior - their only purpose is to help categorize the settings that are migrating. These **\<role\>** elements can be nested, but each nested element must be of the same role parameter.</li><li>One "Container" **\<role\>** element within a **\<component\>** element. In this case, any child **\<rules\>** elements can't be specified, only other **\<component\>** elements. And each child **\<component\>** element must have the same type as that of parent **\<component\>** element. For example:</li></ol> <pre class="syntax"><code>\<component context="UserAndSystem" type="Application"\><br> \<displayName _locID="migapp.msoffice2016"\>Microsoft Office 2016\</displayName\><br> \<environment name="GlobalEnv" /\><br> \<role role="Container"\><br> \<detection name="AnyOffice2016Version" /\><br> \<detection name="Word2016" /\><br> \<!--<br> Office 2016 Common Settings<br> --\><br> \<component context="UserAndSystem" type="Application"\></code></pre> |
The following example is from the `MigUser.xml` file. For more examples, see the `MigApp.xml` file:
@ -1888,8 +1888,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| name | Yes, when **\<rules\>** is a child to **\<namedElements\>** <br>No, when **\<rules\>** is a child to any other element | When *ID* is specified, any child elements aren't processed. Instead, any other **\<rules\>** elements with the same name that are declared within **\<namedElements\>** are processed. |
| context | No <br>(default = UserAndSystem) | Defines the scope of this parameter - whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the component element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it has a context of **User**. If **\<rules\>** had a context of **System**, it would act as though **\<rules\>** wasn't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
| name | Yes, when **\<rules\>** is a child to **\<namedElements\>**<br>No, when **\<rules\>** is a child to any other element | When *ID* is specified, any child elements aren't processed. Instead, any other **\<rules\>** elements with the same name that are declared within **\<namedElements\>** are processed. |
| context | No<br>(default = UserAndSystem) | Defines the scope of this parameter - whether to process this component in the context of the specific user, across the entire operating system, or both.<br>The largest possible scope is set by the component element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it has a context of **User**. If **\<rules\>** had a context of **System**, it would act as though **\<rules\>** wasn't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
The following example is from the `MigUser.xml` file:
@ -1961,7 +1961,7 @@ The return value that is required by **\<script\>** depends on the parent elemen
|Setting|Required?|Value|
|--- |--- |--- |
| *ScriptWithArguments* | Yes | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. <br>The return value that is required by **\<script\>** depends on the parent element. <ul><li>When used within **\<variable\>**, the return value must be a string.</li><li>When used within **\<objectSet\>**, the return value must be a two-dimensional array of strings.</li><li>When used within **\<location\>**, the return value must be a valid location that aligns with the type attribute of **\<location\>**. For example, if \<location type="File"\>, the child script element, if specified, must be a valid file location. <div class="alert">**Note**<br>If migrating a file that has a bracket character ([ or ]) in the file name, insert the carrot (^) character directly before the bracket for it to be valid. For example, if there's a file named "file].txt", specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
| *ScriptWithArguments* | Yes | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.<br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.<br>The return value that is required by **\<script\>** depends on the parent element. <ul><li>When used within **\<variable\>**, the return value must be a string.</li><li>When used within **\<objectSet\>**, the return value must be a two-dimensional array of strings.</li><li>When used within **\<location\>**, the return value must be a valid location that aligns with the type attribute of **\<location\>**. For example, if \<location type="File"\>, the child script element, if specified, must be a valid file location. <div class="alert">**Note**<br>If migrating a file that has a bracket character ([ or ]) in the file name, insert the carrot (^) character directly before the bracket for it to be valid. For example, if there's a file named "file].txt", specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
Examples:
@ -1994,7 +1994,7 @@ These functions return either a string or a pattern.
|Setting|Required?|Value|
|--- |--- |--- |
| *ObjectType* | Yes | The type of object. Can be Registry or Ini (for an **.ini** file). |
| *EncodedLocationPattern* | Yes | <ul><li>If type of object is Registry, EncodedLocationPattern must be a valid registry path. For example, `HKLM\SOFTWARE\MyKey[]`.</li><li>If the type of object is Ini, then EncodedLocationPattern must be in the following format: <br>**IniFilePath&#124;SectionName[SettingName]**</li></ul> |
| *EncodedLocationPattern* | Yes | <ul><li>If type of object is Registry, EncodedLocationPattern must be a valid registry path. For example, `HKLM\SOFTWARE\MyKey[]`.</li><li>If the type of object is Ini, then EncodedLocationPattern must be in the following format:<br>**IniFilePath&#124;SectionName[SettingName]**</li></ul> |
| *ExpandContent* | No (default=TRUE) | Can be **TRUE** or **FALSE**. If **FALSE**, then the given location isn't expanded before returned. |
For example: