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

Merge branch 'main' into delete-windows-contents-ADO-8098898

Browse Source
This commit is contained in:
Gary Moore
2024-01-19 20:39:26 -08:00
parent d2afe80f35 beea365858
commit 4e2838d770
1893 changed files with 23180 additions and 32426 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
windows/deployment/TOC.yml
View File

@ -328,13 +328,15 @@
- name: UCServiceUpdateStatus
href: update/wufb-reports-schema-ucserviceupdatestatus.md
- name: UCUpdateAlert
href: update/wufb-reports-schema-ucupdatealert.md
href: update/wufb-reports-schema-ucupdatealert.md
- name: Enumerated types
href: update/wufb-reports-schema-enumerated-types.md
- name: Troubleshooting
items:
- name: Resolve upgrade errors
items:
- name: Resolve Windows client upgrade errors
href: upgrade/resolve-windows-10-upgrade-errors.md
- name: Resolve Windows upgrade errors
href: upgrade/resolve-windows-upgrade-errors.md
- name: Quick fixes
href: /troubleshoot/windows-client/deployment/windows-10-upgrade-quick-fixes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json
- name: SetupDiag

4
windows/deployment/deploy-enterprise-licenses.md
View File

@ -14,7 +14,7 @@ ms.collection:
appliesto:
- ✅ <b>Windows 10</b>
- ✅ <b>Windows 11</b>
ms.date: 11/23/2022
ms.date: 11/14/2023
---
# Deploy Windows Enterprise licenses
@ -306,6 +306,6 @@ If a device isn't able to connect to Windows Update, it can lose activation stat
## Virtual Desktop Access (VDA)
Subscriptions to Windows Enterprise are also available for virtualized clients. Enterprise E3 and E5 are available for Virtual Desktop Access (VDA) in Azure or in another [qualified multitenant hoster](https://download.microsoft.com/download/3/D/4/3D445779-2870-4E3D-AFCB-D35D2E1BC095/QMTH%20Authorized%20Partner%20List.pdf) (PDF download).
Subscriptions to Windows Enterprise are also available for virtualized clients. Enterprise E3 and E5 are available for Virtual Desktop Access (VDA) in Azure or in another qualified multitenant hoster.
Virtual machines (VMs) must be configured to enable Windows Enterprise subscriptions for VDA. Active Directory-joined and Microsoft Entra joined clients are supported. For more information, see [Enable VDA for Enterprise subscription activation](vda-subscription-activation.md).

147
windows/deployment/deploy-whats-new.md
View File

@ -11,19 +11,17 @@ ms.topic: conceptual
ms.collection:
- highpri
- tier2
ms.date: 11/23/2022
ms.date: 01/18/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# What's new in Windows client deployment
*Applies to:*
- Windows 10
- Windows 11
This article provides an overview of new solutions and online content related to deploying Windows client in your organization.
- For an all-up overview of new features in Windows 10, see [What's new in Windows 10](/windows/whats-new/index).
- For an all-up overview of new features in Windows, see [What's new in Windows](/windows/whats-new/).
## [Preview] Windows Autopilot diagnostics page
@ -33,41 +31,39 @@ When you deploy Windows 11 with Autopilot, you can enable users to view addition
Check out the following new articles about Windows 11:
- [Overview of Windows 11](/windows/whats-new/windows-11)
- [Plan for Windows 11](/windows/whats-new/windows-11-plan)
- [Prepare for Windows 11](/windows/whats-new/windows-11-prepare)
The [Windows ADK for Windows 11](/windows-hardware/get-started/adk-install) is available.<br>
- [Overview of Windows 11](/windows/whats-new/windows-11).
- [Plan for Windows 11](/windows/whats-new/windows-11-plan).
- [Prepare for Windows 11](/windows/whats-new/windows-11-prepare).
- [Windows ADK for Windows 11](/windows-hardware/get-started/adk-install) is available.
## Deployment tools
[SetupDiag](#setupdiag) is included with Windows 10, version 2004 and later, and Windows 11.<br>
New capabilities are available for [Delivery Optimization](#delivery-optimization) and [Windows Update for Business](#windows-update-for-business).<br>
VPN support is added to [Windows Autopilot](#windows-autopilot)<br>
An in-place upgrade wizard is available in [Configuration Manager](#microsoft-configuration-manager).<br>
The Windows 10 deployment and update [landing page](index.yml) has been redesigned, with more content added and more content coming soon.<br>
- [SetupDiag](#setupdiag) is included with all currently supported versions of Windows.
- New capabilities are available for [Delivery Optimization](#delivery-optimization) and [Windows Update for Business](#windows-update-for-business).
- VPN support is added to [Windows Autopilot](#windows-autopilot).
- An in-place upgrade wizard is available in [Configuration Manager](#microsoft-configuration-manager).
## The Modern Desktop Deployment Center
The [Modern Desktop Deployment Center](/microsoft-365/enterprise/desktop-deployment-center-home) has launched with tons of content to help you with large-scale deployment of Windows 10 and Microsoft 365 Apps for enterprise.
The [Modern Desktop Deployment Center](/microsoft-365/enterprise/desktop-deployment-center-home) has content to help you with large-scale deployment of supported version of Windows and Microsoft 365 Apps for enterprise.
## Microsoft 365
Microsoft 365 is a new offering from Microsoft that combines
Microsoft 365 is a new offering from Microsoft that combines:
- Windows 10
- Office 365
- A currently supported version of Windows.
- Office 365.
- Enterprise Mobility and Security (EMS).
See [Deploy Windows 10 with Microsoft 365](deploy-m365.md) for an overview, which now includes a link to download a nifty [Microsoft 365 Enterprise poster](deploy-m365.md#microsoft-365-enterprise-poster).
See [Deploy Windows 10 with Microsoft 365](deploy-m365.md) for an overview, which now includes a link to download a [Microsoft 365 Enterprise poster](deploy-m365.md#microsoft-365-enterprise-poster).
## Windows 10 servicing and support
## Windows servicing and support
### Delivery Optimization
Windows PowerShell cmdlets for Delivery Optimization have been improved:
Windows PowerShell cmdlets for Delivery Optimization is improved:
- **Get-DeliveryOptimizationStatus** has added the **-PeerInfo** option for a real-time peek behind the scenes on peer-to-peer activity (for example the peer IP Address, bytes received / sent).
- **Get-DeliveryOptimizationStatus** has the **-PeerInfo** option for a real-time peek behind the scenes on peer-to-peer activity (for example the peer IP Address, bytes received / sent).
- **Get-DeliveryOptimizationLogAnalysis** is a new cmdlet that provides a summary of the activity in your DO log (# of downloads, downloads from peers, overall peer efficiency). Use the **-ListConnections** option to for in-depth look at peer-to-peer connections.
- **Enable-DeliveryOptimizationVerboseLogs** is a new cmdlet that enables a greater level of logging detail to help in troubleshooting.
@ -79,31 +75,38 @@ Other improvements in [Delivery Optimization](./do/waas-delivery-optimization.md
The following Delivery Optimization policies are removed in the Windows 10, version 2004 release:
- Percentage of Maximum Download Bandwidth (DOPercentageMaxDownloadBandwidth)
- Reason: Replaced with separate policies for foreground and background
- Max Upload Bandwidth (DOMaxUploadBandwidth)
- Percentage of Maximum Download Bandwidth (DOPercentageMaxDownloadBandwidth).
- Reason: Replaced with separate policies for foreground and background.
- Max Upload Bandwidth (DOMaxUploadBandwidth).
- Reason: impacts uploads to internet peers only, which isn't used in enterprises.
- Absolute max throttle (DOMaxDownloadBandwidth)
- Reason: separated to foreground and background
- Absolute max throttle (DOMaxDownloadBandwidth).
- Reason: separated to foreground and background.
### Windows Update for Business
[Windows Update for Business](./update/waas-manage-updates-wufb.md) enhancements in this release include:
- Intune console updates: target version is now available allowing you to specify which version of Windows 10 you want devices to move to. Additionally, this capability enables you to keep devices on their current version until they reach end of service. Check it out in Intune, also available as a Group Policy and Configuration Service Provider (CSP) policy.
- Validation improvements: To ensure devices and end users stay productive and protected, Microsoft uses safeguard holds to block devices from updating when there are known issues that would impact that device. Also, to better enable IT administrators to validate on the latest release, we've created a new policy that enables admins to opt devices out of the built-in safeguard holds.
- **Intune console updates**: target version is now available allowing you to specify which supported version of Windows you want devices to move to. Additionally, this capability enables you to keep devices on their current version until they reach end of service. Check it out in Intune, also available as a Group Policy and Configuration Service Provider (CSP) policy.
- **Validation improvements**: To ensure devices and end users stay productive and protected, Microsoft blocks devices from updating when there are known issues affect that device. Also, to better enable IT administrators to validate on the latest release, a new policy is available that enables admins to opt devices out of the built-in safeguard holds.
- [**Automatic Restart Sign-on (ARSO)**](/windows-server/identity/ad-ds/manage/component-updates/winlogon-automatic-restart-sign-on--arso-): Windows automatically signs in as the user and locks their device in order to complete the update. Automatic sign-on ensures that when the user returns and unlocks the device, the update is completed.
- [**Windows Update for Business**](https://techcommunity.microsoft.com/t5/Windows-IT-Pro-Blog/Windows-Update-for-Business-and-the-retirement-of-SAC-T/ba-p/339523): There's now a single, common start date for phased deployments (no more SAC-T designation). In addition, there's a new notification and reboot scheduling experience for end users, the ability to enforce update installation and reboot deadlines, and the ability to provide end user control over reboots for a specific time period.
- [**Automatic Restart Sign-on (ARSO)**](/windows-server/identity/ad-ds/manage/component-updates/winlogon-automatic-restart-sign-on--arso-): Windows will automatically sign in as the user and lock their device in order to complete the update, ensuring that when the user returns and unlocks the device, the update will be completed.
- [**Windows Update for Business**](https://techcommunity.microsoft.com/t5/Windows-IT-Pro-Blog/Windows-Update-for-Business-and-the-retirement-of-SAC-T/ba-p/339523): There will now be a single, common start date for phased deployments (no more SAC-T designation). In addition, there will be a new notification and reboot scheduling experience for end users, the ability to enforce update installation and reboot deadlines, and the ability to provide end user control over reboots for a specific time period.
- **Update rollback improvements**: You can now automatically recover from startup failures by removing updates if the startup failure was introduced after the installation of recent driver or quality updates. When a device is unable to start up properly after the recent installation of Quality of driver updates, Windows will now automatically uninstall the updates to get the device back up and running normally.
- **Pause updates**: We've extended the ability to pause updates for both feature and monthly updates. This extension ability is for all editions of Windows 10, including Home. You can pause both feature and monthly updates for up to 35 days (seven days at a time, up to five times). Once the 35-day pause period is reached, you'll need to update your device before pausing again.
- **Improved update notifications**: When there's an update requiring you to restart your device, you'll see a colored dot on the Power button in the Start menu and on the Windows icon in your taskbar.
- **Pause updates**: The ability to pause updates for both feature and monthly updates is extended. This extension ability is for all currently supported editions of Windows, including Home. You can pause both feature and monthly updates for up to 35 days (seven days at a time, up to five times). Once the 35-day pause period is reached, the device needs to update before pausing again.
- **Improved update notifications**: When there's an update requiring you to restart your device, a colored dot appears on the Power button in the Start menu and on the Windows icon in the taskbar.
- **Intelligent active hours**: To further enhance active hours, users now can let Windows Update intelligently adjust active hours based on their device-specific usage patterns. You must enable the intelligent active hours feature for the system to predict device-specific usage patterns.
- **Improved update orchestration to improve system responsiveness**: This feature will improve system performance by intelligently coordinating Windows updates and Microsoft Store updates, so they occur when users are away from their devices to minimize disruptions.
Microsoft previously announced that we're [extending support](https://www.microsoft.com/microsoft-365/blog/2018/09/06/helping-customers-shift-to-a-modern-desktop) for Windows 10 Enterprise and Windows 10 Education editions to 30 months from the version release date. These editions include all past versions and future versions that are targeted for release in September (versions ending in 09, ex: 1809). Future releases that are targeted for release in March (versions ending in 03, ex: 1903) will continue to be supported for 18 months from their release date. All releases of Windows 10 Home, Windows 10 Pro, and Microsoft 365 Apps for enterprise will continue to be supported for 18 months (there's no change for these editions). These support policies are summarized in the table below.
- **Improved update orchestration to improve system responsiveness**: This feature improves system performance by intelligently coordinating Windows updates and Microsoft Store updates, so they occur when users are away from their devices to minimize disruptions.
![Support lifecycle.](images/support-cycle.png)
Microsoft previously announced that we're [extending support](https://www.microsoft.com/microsoft-365/blog/2018/09/06/helping-customers-shift-to-a-modern-desktop) for Windows 10 Enterprise and Windows 10 Education editions to 30 months from the version release date. These editions include all past versions and future versions that are targeted for release in September (versions ending in 09, ex: 1809). Future releases that are targeted for release in March (versions ending in 03, ex: 1903) will continue to be supported for 18 months from their release date. All releases of Windows 10 Home, Windows 10 Pro, and Microsoft 365 Apps for enterprise will continue to be supported for 18 months (there's no change for these editions). These support policies are summarized in the following table:
:::image type="content" alt-text="Support lifecycle." source="images/support-cycle.png":::
## Windows 10 Enterprise upgrade
@ -111,7 +114,7 @@ Windows 10 version 1703 includes a Windows 10 Enterprise E3 and E5 benefit to Mi
Windows 10 Enterprise E3 launched in the Cloud Solution Provider (CSP) channel on September 1, 2016. Previously, only organizations with a Microsoft Volume Licensing Agreement could deploy Windows 10 Enterprise to their users. With Windows 10 Enterprise E3 in CSP, small and medium-sized organizations can more easily take advantage of Windows 10 Enterprise features.
For more information, see [Windows 10 Enterprise E3 in CSP](windows-10-enterprise-e3-overview.md)
For more information, see [Windows 10 Enterprise E3 in CSP](windows-10-enterprise-e3-overview.md).
## Deployment solutions and tools
@ -119,17 +122,17 @@ For more information, see [Windows 10 Enterprise E3 in CSP](windows-10-enterpris
[Windows Autopilot](/windows/deployment/windows-autopilot/windows-autopilot) streamlines and automates the process of setting up and configuring new devices, with minimal interaction required from the end user. You can also use Windows Autopilot to reset, repurpose, and recover devices.
With the release of Windows 10, version 2004 you can configure [Windows Autopilot user-driven](/windows/deployment/windows-autopilot/user-driven) Hybrid Azure Active Directory join with VPN support. This support is also backported to Windows 10, version 1909 and 1903.
With the release of Windows 10, version 2004 you can configure [Windows Autopilot user-driven](/windows/deployment/windows-autopilot/user-driven) Microsoft Entra hybrid join with VPN support.
If you configure the language settings in the Autopilot profile and the device is connected to Ethernet, all scenarios will now skip the language, locale, and keyboard pages. In previous versions, these language settings were only supported with self-deploying profiles.
If you configure the language settings in the Autopilot profile and the device is connected to Ethernet, all scenarios now skip the language, locale, and keyboard pages. In previous versions, these language settings were only supported with self-deploying profiles.
The following Windows Autopilot features are available in Windows 10, version 1903 and later:
- [Windows Autopilot for white glove deployment](/windows/deployment/windows-autopilot/white-glove) is new in Windows 10, version 1903. "White glove" deployment enables partners or IT staff to pre-provision devices so they're fully configured and business ready for your users.
- [Windows Autopilot for pre-provisioned deployment](/autopilot/pre-provision) is new in Windows 10, version 1903. Pre-provisioned deployment enables partners or IT staff to pre-provision devices so they're fully configured and business ready for your users.
- The Intune [enrollment status page](/intune/windows-enrollment-status) (ESP) now tracks Intune Management Extensions​.
- [Cortana voiceover](/windows-hardware/customize/desktop/cortana-voice-support) and speech recognition during OOBE is disabled by default for all Windows 10 Pro Education, and Enterprise SKUs.
- Windows Autopilot is self-updating during OOBE. From Windows 10 onward, version 1903 Autopilot functional and critical updates will begin downloading automatically during OOBE.
- Windows Autopilot will set the [diagnostics data](/windows/privacy/windows-diagnostic-data) level to Full on Windows 10 version 1903 and later during OOBE.
- Windows Autopilot is self-updating during OOBE. From Windows 10 onward, version 1903 Autopilot functional and critical updates begin downloading automatically during OOBE.
- Windows Autopilot sets the [diagnostics data](/windows/privacy/windows-diagnostic-data) level to Full on Windows 10 version 1903 and later during OOBE.
### Microsoft Configuration Manager
@ -137,34 +140,30 @@ An in-place upgrade wizard is available in Configuration Manager. For more infor
### Windows 10 Subscription Activation
Windows 10 Education support has been added to Windows 10 Subscription Activation.
Windows 10 Education support is added to Windows 10 Subscription Activation.
With Windows 10, version 1903, you can step up from Windows 10 Pro Education to the enterprise-grade edition for educational institutions - Windows 10 Education. For more information, see [Windows 10 Subscription Activation](./windows-10-subscription-activation.md).
### SetupDiag
[SetupDiag](upgrade/setupdiag.md) is a command-line tool that can help diagnose why a Windows 10 update failed. SetupDiag works by searching Windows Setup log files. When log files are being searched, SetupDiag uses a set of rules to match known issues.
[SetupDiag](upgrade/setupdiag.md) is a command-line tool that can help diagnose why an update of Windows failed. SetupDiag works by searching Windows Setup log files. When log files are being searched, SetupDiag uses a set of rules to match known issues.
In Windows 10, version 2004, SetupDiag is now automatically installed.
During the upgrade process, Windows Setup will extract all its sources files to the **%SystemDrive%\$Windows.~bt\Sources** directory. With Windows 10, version 2004 and later, Windows Setup now also installs SetupDiag.exe to this directory. If there's an issue with the upgrade, SetupDiag is automatically run to determine the cause of the failure. If the upgrade process proceeds normally, this directory is moved under %SystemDrive%\Windows.Old for cleanup.
During the upgrade process, Windows Setup extracts all its sources files to the `%SystemDrive%\$Windows.~bt\Sources` directory. **SetupDiag.exe** is also installed to this directory. If there's an issue with the upgrade, SetupDiag automatically runs to determine the cause of the failure. If the upgrade process proceeds normally, this directory is moved under `%SystemDrive%\Windows.Old` for cleanup.
### Upgrade Readiness
The Upgrade Readiness tool moved from public preview to general availability on March 2, 2017.
Upgrade Readiness helps you ensure that applications and drivers are ready for an upgrade of Windows. The solution provides up-to-date application and driver inventory, information about known issues, troubleshooting guidance, and per-device readiness and tracking details.
Upgrade Readiness helps you ensure that applications and drivers are ready for a Windows 10 upgrade. The solution provides up-to-date application and driver inventory, information about known issues, troubleshooting guidance, and per-device readiness and tracking details.
The development of Upgrade Readiness has been heavily influenced by input from the community; the development of new features is ongoing. To begin using Upgrade Readiness, add it to an existing Operation Management Suite (OMS) workspace or sign up for a new OMS workspace with the Upgrade Readiness solution enabled.
Input from the community heavily influenced the development of Upgrade Readiness and the development of new features is ongoing. To begin using Upgrade Readiness, add it to an existing Operation Management Suite (OMS) workspace or sign up for a new OMS workspace with the Upgrade Readiness solution enabled.
For more information about Upgrade Readiness, see the following articles:
- [Windows Analytics blog](https://aka.ms/blog/WindowsAnalytics/)
- [Manage Windows upgrades with Upgrade Readiness](/mem/configmgr/desktop-analytics/overview)
- [Windows Analytics blog](https://aka.ms/blog/WindowsAnalytics/).
- [Manage Windows upgrades with Upgrade Readiness](/mem/configmgr/desktop-analytics/overview).
### Update Compliance
Update Compliance helps you to keep Windows 10 devices in your organization secure and up-to-date.
Update Compliance helps you to keep supported Windows devices in your organization secure and up-to-date.
Update Compliance is a solution built using OMS Logs and Analytics that provides information about installation status of monthly quality and feature updates. Details are provided about the deployment progress of existing updates and the status of future updates. Information is also provided about devices that might need attention to resolve issues.
@ -172,31 +171,35 @@ For more information about Update Compliance, see [Monitor Windows Updates with
### Device Health
Device Health is the newest Windows Analytics solution that complements the existing Upgrade Readiness and Update Compliance solutions by helping to identify devices crashes and the cause. Device drivers that are causing crashes are identified along with alternative drivers that might reduce the number of crashes. Windows Information Protection misconfigurations are also identified. For more information, see [Monitor the health of devices with Device Health](/mem/configmgr/desktop-analytics/overview)
Device Health is the newest Windows Analytics solution that complements the existing Upgrade Readiness and Update Compliance solutions by helping to identify devices crashes and the cause. Device drivers that are causing crashes are identified along with alternative drivers that might reduce the number of crashes. Windows Information Protection misconfigurations are also identified. For more information, see [Monitor the health of devices with Device Health](/mem/configmgr/desktop-analytics/overview).
### MBR2GPT
MBR2GPT.EXE converts a disk from Master Boot Record (MBR) to GUID Partition Table (GPT) partition style without modifying or deleting data on the disk. Previously, it was necessary to image, then wipe and reload a disk to change from MBR format to GPT.
There are many benefits to converting the partition style of a disk to GPT, including the use of larger disk partitions, added data reliability, and faster boot and shutdown speeds. The GPT format also enables you to use the Unified Extensible Firmware Interface (UEFI) which replaces the Basic Input/Output System (BIOS) firmware interface. Security features of Windows 10 that require UEFI mode include: Secure Boot, Early Launch Anti-malware (ELAM) driver, Windows Trusted Boot, Measured Boot, Device Guard, Credential Guard, and BitLocker Network Unlock.
There are many benefits to converting the partition style of a disk to GPT, including the use of larger disk partitions, added data reliability, and faster boot and shutdown speeds. The GPT format also enables you to use the Unified Extensible Firmware Interface (UEFI) which replaces the Basic Input/Output System (BIOS) firmware interface. Security features of supported versions of Windows that require UEFI mode include: Secure Boot, Early Launch Anti-malware (ELAM) driver, Windows Trusted Boot, Measured Boot, Device Guard, Credential Guard, and BitLocker Network Unlock.
For more information, see [MBR2GPT.EXE](mbr-to-gpt.md).
### Microsoft Deployment Toolkit (MDT)
MDT version 8456 supports Windows 10, version 2004 and earlier operating systems, including Windows Server 2019. There's currently an issue that causes MDT to incorrectly detect that UEFI is present in Windows 10, version 2004. This issue is currently under investigation.
MDT version 8456 supports Windows 10, version 2004 and earlier operating systems, including Windows Server 2019.
For the latest information about MDT, see the [MDT release notes](/mem/configmgr/mdt/release-notes).
> [!IMPORTANT]
>
> MDT doesn't support versions of Windows after Windows 10 and Windows Server 2019.
### Windows Assessment and Deployment Kit (ADK)
The Windows Assessment and Deployment Kit (Windows ADK) contains tools that can be used by IT Pros to deploy Windows.
IT Pros can use the tools in the Windows Assessment and Deployment Kit (Windows ADK) to deploy Windows.
Download the Windows ADK and Windows PE add-on for Windows 11 [here](/windows-hardware/get-started/adk-install).
For information about what's new in the ADK, see [What's new in the Windows ADK](/windows-hardware/get-started/what-s-new-in-kits-and-tools).
Also see [Windows ADK for Windows 10 scenarios for IT Pros](windows-adk-scenarios-for-it-pros.md).
Also see [Windows ADK for Windows scenarios for IT Pros](windows-adk-scenarios-for-it-pros.md).
## Testing and validation guidance
@ -206,19 +209,19 @@ The Windows 10 PoC guide enables you to test Windows 10 deployment in a virtual
For more information, see the following guides:
- [Step by step guide: Configure a test lab to deploy Windows 10](windows-10-poc.md)
- [Deploy Windows 10 in a test lab using Microsoft Deployment Toolkit](windows-10-poc-mdt.md)
- [Deploy Windows 10 in a test lab using Microsoft Configuration Manager](windows-10-poc-sc-config-mgr.md)
- [Step by step guide: Configure a test lab to deploy Windows 10](windows-10-poc.md).
- [Deploy Windows 10 in a test lab using Microsoft Deployment Toolkit](windows-10-poc-mdt.md).
- [Deploy Windows 10 in a test lab using Microsoft Configuration Manager](windows-10-poc-sc-config-mgr.md).
## Troubleshooting guidance
[Resolve Windows 10 upgrade errors](upgrade/resolve-windows-10-upgrade-errors.md) was published in October of 2016 and will continue to be updated with new fixes. The article provides a detailed explanation of the Windows 10 upgrade process and instructions on how to locate, interpret, and resolve specific errors that can be encountered during the upgrade process.
[Resolve Windows upgrade errors](upgrade/resolve-windows-upgrade-errors.md) was published in October of 2016 and continues to be updated with new fixes. The article provides a detailed explanation of the Windows upgrade process and instructions on how to locate, interpret, and resolve specific errors that can be encountered during the upgrade process.
## Related articles
[Overview of Windows as a service](update/waas-overview.md)<br>
[Windows 10 deployment considerations](planning/windows-10-deployment-considerations.md)<br>
[Windows 10 release information](/windows/windows-10/release-information)<br>
[Windows 10 Specifications & Systems Requirements](https://www.microsoft.com/windows/windows-10-specifications)<br>
[Windows 10 upgrade paths](upgrade/windows-10-upgrade-paths.md)<br>
[Windows 10 deployment tools](windows-deployment-scenarios-and-tools.md)<br>
- [Overview of Windows as a service](update/waas-overview.md).
- [Windows 10 deployment considerations](planning/windows-10-deployment-considerations.md).
- [Windows 10 release information](/windows/windows-10/release-information).
- [Windows 10 Specifications & Systems Requirements](https://www.microsoft.com/windows/windows-10-specifications).
- [Windows 10 upgrade paths](upgrade/windows-10-upgrade-paths.md).
- [Windows 10 deployment tools](windows-deployment-scenarios-and-tools.md).

2
windows/deployment/do/TOC.yml
View File

@ -21,7 +21,7 @@
items:
- name: Delivery Optimization reference
href: waas-delivery-optimization-reference.md
- name: Delivery Optimization client-service communication
- name: Delivery Optimization workflow, privacy, security, and endpoints
href: delivery-optimization-workflow.md
- name: Using a proxy with Delivery Optimization
href: delivery-optimization-proxy.md

24
windows/deployment/do/delivery-optimization-workflow.md
View File

@ -1,6 +1,6 @@
---
title: Delivery Optimization client-service communication
description: Details of how Delivery Optimization communicates with the server when content is requested to download.
title: Delivery Optimization workflow, privacy, security, and endpoints
description: Details of how Delivery Optimization communicates with the server when content is requested to download including privacy, security, and endpoints.
ms.prod: windows-client
ms.technology: itpro-updates
ms.topic: conceptual
@ -14,23 +14,31 @@ appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
- ✅ <a href=https://learn.microsoft.com/windows/deployment/do/waas-delivery-optimization target=_blank>Delivery Optimization</a>
ms.date: 12/31/2017
ms.date: 01/18/2024
---
# Delivery Optimization client-service communication explained
# Delivery Optimization workflow, privacy, security, and endpoints
Delivery Optimization is a cloud-managed solution that uses peer-to-peer (P2P) and local caching to deliver software updates and apps to Windows clients across your network. This article describes details of how Delivery Optimization communicates with the server when content is requested to download.
## Download request workflow
Delivery Optimization is a cloud-managed solution that uses peer-to-peer (P2P) and local caching to deliver software updates and apps to Windows clients across your network. This article describes details of how Delivery Optimization communicates with the server when content is requested to download and contains information about privacy, security, and endpoints.
This workflow allows Delivery Optimization to securely and efficiently deliver requested content to the calling device. Delivery Optimization uses content metadata to verify the content and to determine all available locations to pull content from.
## How we help keep your data safe
Delivery Optimization can't be used to download or send personal content. Delivery Optimization doesn't access personal files or folders, and it doesn't change any files on the device.
Delivery Optimization downloads the same updates and apps that you would get through [Windows Update](../update/windows-update-security.md), Microsoft Store apps, and other Microsoft updates using the same security measures. To make sure you're getting authentic updates, Delivery Optimization gets information securely from Microsoft to check the authenticity of each part of an update or app that it downloads from other PCs. The authenticity of the downloads is checked again before installing it. <!--8658744-->
## Download request workflow
This workflow allows Delivery Optimization to securely and efficiently deliver requested content to the calling device and explains client-service communication. Delivery Optimization uses content metadata to verify the content and to determine all available locations to pull content from.
1. When a download starts, the Delivery Optimization client attempts to get its content metadata. This content metadata is a hash file containing the SHA-256 block-level hashes of each piece in the file (typically one piece = 1 MB).
2. The authenticity of the content metadata file itself is verified prior to any content being downloaded using a hash that is obtained via an SSL channel from the Delivery Optimization service. The same channel is used to ensure the content is curated and authorized to use peer-to-peer.
3. When Delivery Optimization pulls a certain piece of the hash from another peer, it verifies the hash against the known hash in the content metadata file.
4. If a peer provides an invalid piece, that piece is discarded. When a peer sends multiple bad pieces, it's banned and will no longer be used as a source by the Delivery Optimization client performing the download.
5. If Delivery Optimization is unable to obtain the content metadata file, or if the verification of the hash file itself fails, the download will fall back to "simple mode”. Simple mode will only pull content from the HTTP source and peer-to-peer won't be allowed.
5. If Delivery Optimization is unable to obtain the content metadata file, or if the verification of the hash file itself fails, the download will fall back to simple mode. Simple mode will only pull content from the HTTP source and peer-to-peer won't be allowed.
6. Once downloading is complete, Delivery Optimization uses all retrieved pieces of the content to put the file together. At that point, the Delivery Optimization caller (for example, Windows Update) checks the entire file to verify the signature prior to installing it.
## Delivery Optimization service endpoint and data information
|Endpoint hostname | Port|Name|Description|Data sent from the computer to the endpoint

BIN
windows/deployment/do/images/assigning-ip-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.6 KiB

BIN
windows/deployment/do/images/external-switch-1.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
windows/deployment/do/images/installation-complete-7.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 59 KiB

BIN
windows/deployment/do/images/installation-info-4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
windows/deployment/do/images/memory-storage-5.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
windows/deployment/do/images/portal-installation-instructions-6.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
windows/deployment/do/images/use-custom-dns-3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.6 KiB

2
windows/deployment/do/index.yml
View File

@ -15,7 +15,7 @@ metadata:
author: aczechowski
ms.author: aaroncz
manager: aaroncz
ms.date: 03/07/2022 #Required; mm/dd/yyyy format.
ms.date: 12/22/2023 #Required; mm/dd/yyyy format.
localization_priority: medium
# linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new

8
windows/deployment/do/mcc-enterprise-appendix.md
View File

@ -15,7 +15,7 @@ appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
- ✅ <a href=https://learn.microsoft.com/windows/deployment/do/waas-microsoft-connected-cache target=_blank>Microsoft Connected Cache for Enterprise and Education</a>
ms.date: 02/06/2023
ms.date: 11/07/2023
---
# Appendix
@ -37,10 +37,10 @@ Most customers choose to install their cache node on a Windows Server with a nes
### Installing on VMware
We've seen that Microsoft Connected Cache for Enterprise and Education can be successfully installed on VMware. To do so, there are a couple of additional configurations to be made:
Microsoft Connected Cache for Enterprise and Education can be successfully installed on VMware. To do so, there are a couple of additional configurations to be made. Ensure the VM is turned off before making the following configuration changes:
1. Ensure that you're using ESX. In the VM settings, turn on the option **Expose hardware assisted virtualization to the guest OS**.
1. Using the Hyper-V Manager, create an external switch. For the external switch to have internet connection, ensure **"Allow promiscuous mode"**, **"Allow forged transmits"**, and **"Allow MAC changes"** are all switched to **Yes**.
1. Using the Hyper-V Manager, create an external switch. For the external switch to have internet connection, ensure **"Allow promiscuous mode"** is switched to **Yes**.
### Installing on Hyper-V
@ -136,4 +136,4 @@ To verify that the Delivery Optimization client can download content using MCC,
- [Install Azure IoT Edge for Linux on Windows](/azure/iot-edge/how-to-provision-single-device-linux-on-windows-symmetric#install-iot-edge)
- [PowerShell functions for Azure IoT Edge for Linux on Windows](/azure/iot-edge/reference-iot-edge-for-linux-on-windows-functions)
- EFLOW FAQ and Support: [Support · Azure/iotedge-eflow Wiki (github.com)](https://github.com/Azure/iotedge-eflow/wiki/Support#how-can-i-apply-updates-to-eflow)
- [Now ready for Production: Linux IoT Edge Modules on Windows - YouTube](https://www.youtube.com/watch?v=pgqVCg6cxVU&ab_channel=MicrosoftIoTDevelopers)
- [Now ready for Production: Linux IoT Edge Modules on Windows - YouTube](https://www.youtube.com/watch?v=pgqVCg6cxVU&ab_channel=MicrosoftIoTDevelopers)

129
windows/deployment/do/mcc-enterprise-deploy.md
View File

@ -13,7 +13,7 @@ appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
- ✅ <a href=https://learn.microsoft.com/windows/deployment/do/waas-microsoft-connected-cache target=_blank>Microsoft Connected Cache for Enterprise and Education</a>
ms.date: 03/10/2023
ms.date: 11/09/2023
---
# Deploy your cache node
@ -29,7 +29,7 @@ To deploy MCC to your server:
1. [Create an MCC Node](#create-an-mcc-node-in-azure)
1. [Edit Cache Node Information](#edit-cache-node-information)
1. [Install MCC on a physical server or VM](#install-mcc-on-windows)
1. [Verify proper functioning MCC server](#verify-proper-functioning-mcc-server)
1. [Verify MCC functionality](#verify-mcc-server-functionality)
1. [Review common Issues](#common-issues) if needed.
For questions regarding these instructions contact [msconnectedcache@microsoft.com](mailto:msconnectedcache@microsoft.com)
@ -194,12 +194,15 @@ Installing MCC on your Windows device is a simple process. A PowerShell script p
> </br>
> </br> [D] Do not run **[R] Run once** [S] Suspend [?] Help (default is "D"):
1. Choose whether you would like to create a new virtual switch or select an existing one. Name your switch and select the Net Adapter to use for the switch. A computer restart will be required if you're creating a new switch.
1. Choose whether you would like to create a new external virtual switch or select an existing external virtual switch.
If creating a new external virtual switch, name your switch and be sure to choose a Local Area Connection (USB adapters work as well however, we do not recommend using Wi-Fi). A computer restart will be required if you're creating a new switch.
> [!NOTE]
> Restarting your computer after creating a switch is recommended. You'll notice network delays during installation if the computer has not been restarted.
If you restarted your computer after creating a switch, start from Step 2 above and skip step 5.
If you restarted your computer after creating a switch, start from step 2 above and skip to step 5.
If you opt to use an existing external switch, select the switch from the presented options. Local Area Connection (or USB) is preferable to Wi-Fi.
:::image type="content" source="./images/ent-mcc-script-new-switch.png" alt-text="Screenshot of the installer script running in PowerShell when a new switch is created." lightbox="./images/ent-mcc-script-new-switch.png":::
@ -207,34 +210,46 @@ Installing MCC on your Windows device is a simple process. A PowerShell script p
:::image type="content" source="./images/ent-mcc-script-existing-switch.png" alt-text="Screenshot of the installer script running in PowerShell when using an existing switch." lightbox="./images/ent-mcc-script-existing-switch.png":::
1. Decide whether you would like to use dynamic or static address for the Eflow VM
1. Decide whether you would like to use dynamic or static address for the Eflow VM. If you choose to use a static IP, do not use the IP address of the server. It is a VM, and it will have its own IP.
:::image type="content" source="./images/ent-mcc-script-dynamic-address.png" alt-text="Screenshot of the installer script running in PowerShell asking if you'd like to use a dynamic address." lightbox="./images/ent-mcc-script-dynamic-address.png":::
> [!NOTE]
> Choosing a dynamic IP address might assign a different IP address when the MCC restarts. A static IP address is recommended so you don't have to change this value in your management solution when MCC restarts.
1. Choose where you would like to download, install, and store the virtual hard disk for EFLOW. You'll also be asked how much memory, storage, and how many cores you would like to allocate for the VM. For this example, we chose the default values for all prompts.
1. Follow the Azure Device Login link and sign into the Azure portal.
:::image type="content" source="./images/ent-mcc-script-device-code.png" alt-text="Screenshot of the installer script running in PowerShell displaying the code and URL to use for the Azure portal." lightbox="./images/ent-mcc-script-device-code.png":::
1. If this is your first MCC deployment, select **n** so that a new IoT Hub can be created. If you have already configured MCC before, choose **y** so that your MCCs are grouped in the same IoT Hub.
The IP address you assign to the EFLOW VM should be within the same subnet as the host server (based on the subnet mask) and not used by any other machine on the network.
For example, for host configuration where the server IP Address is 192.168.1.202 and the subnet mask is 255.255.255.0, the static IP can be anything 192.168.1.* except 192.168.1.202.
<!-- Insert Image 1 & 2. Remove ent-mcc-script-dynamic-address.png image (it is replaced by image 2) -->
:::image type="content" source="./images/external-switch-1.jpg" alt-text="Screenshot of a sample output of ipconfig command showing example of subnet mask." lightbox="./images/external-switch-1.jpg":::
:::image type="content" source="./images/assigning-ip-2.png" alt-text="Screenshot of multiple installer questions about ipv4 address for Eflow." lightbox="./images/assigning-ip-2.png":::
If you would like to use your own DNS server instead of Google DNS 8.8.8.8, select **n** and set your own DNS server IP.
:::image type="content" source="./images/use-custom-dns-3.png" alt-text="Screenshot of multiple installer questions about setting an alternate DNS server." lightbox="./images/use-custom-dns-3.png":::
If you use a dynamic IP address, the DHCP server will automatically configure the IP address and DNS settings.
1. Choose where you would like to download, install, and store the virtual hard disk for EFLOW. You'll also be asked how much memory, storage, and how many cores you would like to allocate for the VM. For this example, we chose the default values for download path, install path, and virtual hard disk path.
<!-- Insert Image 4 -->
:::image type="content" source="./images/installation-info-4.png" alt-text="Screenshot of multiple installer questions about memory and storage for EFLOW." lightbox="./images/installation-info-4.png":::
For more information, see [Sizing Recommendations](mcc-enterprise-prerequisites.md#sizing-recommendations) for memory, virtual storage, and CPU cores. For this example we chose the recommend values for a Branch Office/Small Enterprise deployment.
<!-- Insert Image 5 -->
:::image type="content" source="./images/memory-storage-5.png" alt-text="Screenshot of multiple installer questions about memory and storage." lightbox="./images/memory-storage-5.png":::
<!-- Remove: If this is your first MCC deployment, select **n** so that a new IoT Hub can be created. If you have already configured MCC before, choose **y** so that your MCCs are grouped in the same IoT Hub.
1. You'll be shown a list of existing IoT Hubs in your Azure subscription. Enter the number corresponding to the IoT Hub to select it. **You'll likely have only 1 IoT Hub in your subscription, in which case you want to enter "1"**
:::image type="content" source="./images/ent-mcc-script-select-hub.png" alt-text="Screenshot of the installer script running in PowerShell prompting you to select which IoT Hub to use." lightbox="./images/ent-mcc-script-select-hub.png":::
-->
1. When the installation is complete, you should see the following output (the values below will be your own)
:::image type="content" source="./images/ent-mcc-script-complete.png" alt-text="Screenshot of the installer script displaying the completion summary in PowerShell." lightbox="./images/ent-mcc-script-complete.png":::
<!-- Insert Image 7 -->
:::image type="content" source="./images/installation-complete-7.png" alt-text="Screenshot of expected output when installation is complete." lightbox="./images/installation-complete-7.png":::
1. Your MCC deployment is now complete.
If you don't see any errors, continue to the next section to validate your MCC deployment. Your VM will not appear in Hyper-V Manager as it is an EFLOW VM.
- After validating your MCC is properly functional, review your management solution documentation, such as [Intune](/mem/intune/configuration/delivery-optimization-windows), to set the cache host policy to the IP address of your MCC.
- If you had errors during your deployment, see the [Common Issues](#common-issues) section in this article.
1. If you don't see any errors, continue to the next section to validate your MCC deployment. Your VM will not appear in Hyper-V Manager as it is an EFLOW VM.
1. After validating your MCC is properly functional, review your management solution documentation, such as [Intune](/mem/intune/configuration/delivery-optimization-windows), to set the cache host policy to the IP address of your MCC.
1. If you had errors during your deployment, see the [Common Issues](#common-issues) section in this article.
## Verify proper functioning MCC server
## Verify MCC server functionality
#### Verify client side
@ -251,14 +266,20 @@ Connect to the EFLOW VM and check if MCC is properly running:
:::image type="content" source="./images/ent-mcc-connect-eflowvm.png" alt-text="Screenshot of running connect-EflowVm, sudo -s, and iotedge list from PowerShell." lightbox="./images/ent-mcc-connect-eflowvm.png":::
You should see MCC, edgeAgent, and edgeHub running. If you see edgeAgent or edgeHub but not MCC, try this command in a few minutes. The MCC container can take a few minutes to deploy.
You should see MCC, edgeAgent, and edgeHub running. If you see edgeAgent or edgeHub but not MCC, try this command in a few minutes. The MCC container can take a few minutes to deploy. If iotedge list times out, you can run docker ps -a to list the running containers.
If the 3 containers are still not running, run the following commands to check if DNS resolution is working correctly:
```bash
ping www.microsoft.com
resolvectl query microsoft.com
```
See the [common issues](#common-issues) section for more information.
#### Verify server side
For a validation of properly functioning MCC, execute the following command in the EFLOW VM or any device in the network. Replace <CacheServerIP\> with the IP address of the cache server.
To validate that MCC is properly functioning, execute the following command in the EFLOW VM or any device in the network. Replace <CacheServerIP\> with the IP address of the cache server.
```powershell
wget [http://<CacheServerIP>/mscomtest/wuidt.gif?cacheHostOrigin=au.download.windowsupdate.com]
wget http://<CacheServerIP>/mscomtest/wuidt.gif?cacheHostOrigin=au.download.windowsupdate.com
```
A successful test result will display a status code of 200 along with additional information.
@ -319,3 +340,69 @@ This command will provide the current status of the starting, stopping of a cont
> [!NOTE]
> You should consult the IoT Edge troubleshooting guide ([Common issues and resolutions for Azure IoT Edge](/azure/iot-edge/troubleshoot)) for any issues you may encounter configuring IoT Edge, but we've listed a few issues that we encountered during our internal validation.
>
### DNS needs to be configured
Run the following IoT Edge install state check:
```bash
sudo iotedge check --verbose
```
If you see issues with ports 5671, 443, and 8883, your IoT Edge device needs to update the DNS for Docker.
To configure the device to work with your DNS, use the following steps:
1. Use `ifconfig` to find the appropriate NIC adapter name.
```bash
ifconfig
```
1. Run `nmcli device show <network adapter name>` to show the DNS name for the ethernet adapter. For example, to show DNS information for **eno1**:
```bash
nmcli device show eno1
```
:::image type="content" source="images/mcc-isp-nmcli.png" alt-text="Screenshot of a sample output of nmcli command to show network adapter information." lightbox="./images/mcc-isp-nmcli.png":::
1. Open or create the Docker configuration file used to configure the DNS server.
```bash
sudo nano /etc/docker/daemon.json
```
1. Paste the following string into the **daemon.json** file, and include the appropriate DNS server address. For example, in the previous screenshot, `IP4.DNS[1]` is `10.50.10.50`.
```bash
{ "dns": ["x.x.x.x"]}
```
1. Save the changes to daemon.json. If you need to change permissions on this file, use the following command:
```bash
sudo chmod 555 /etc/docker/daemon.json
```
1. Restart Docker to pick up the new DNS setting. Then restart IoT Edge.
```bash
sudo systemctl restart docker
sudo systemctl daemon-reload
sudo restart IoTEdge
```
### Resolve DNS issues
Follow these steps if you see a DNS error when trying to resolve hostnames during the provisioning or download of container:
Run ``` Get-EflowVmEndpoint ``` to get interface name
Once you get the name
```bash
Set-EflowVmDNSServers -vendpointName "interface name from above" -dnsServers @("DNS_IP_ADDRESS")
Stop-EflowVm
Start-EflowVm
```

7
windows/deployment/do/mcc-enterprise-prerequisites.md
View File

@ -13,7 +13,7 @@ appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
- - ✅ <a href=https://learn.microsoft.com/windows/deployment/do/waas-microsoft-connected-cache target=_blank>Microsoft Connected Cache for Enterprise and Education</a>
ms.date: 05/01/2023
ms.date: 11/07/2023
---
# Requirements of Microsoft Connected Cache for Enterprise and Education (early preview)
@ -34,8 +34,9 @@ ms.date: 05/01/2023
> Azure VMs are not currently supported. If you'd like to install your cache node on VMWare, see the [Appendix](mcc-enterprise-appendix.md) for a few additional configurations.
**EFLOW requires Hyper-V support**
- On Windows client, enable the Hyper-V feature
- On Windows Server, install the Hyper-V role and create a default network switch
- On Windows client, enable the Hyper-V feature.
- On Windows Server, install the Hyper-V role and create a default network switch.
- For additional requirements, see [EFLOW requirements](/azure/iot-edge/iot-edge-for-linux-on-windows#prerequisites).
Disk recommendations:
- Using an SSD is recommended as cache read speed of SSD is superior to HDD

9
windows/deployment/do/mcc-enterprise-update-uninstall.md
View File

@ -1,6 +1,6 @@
---
title: Update or uninstall MCC for Enterprise and Education
description: Details on how to update or uninstall Microsoft Connected Cache (MCC) for Enterprise and Education for your environment.
title: Uninstall MCC for Enterprise and Education
description: Details on how to uninstall Microsoft Connected Cache (MCC) for Enterprise and Education for your environment.
ms.prod: windows-client
ms.technology: itpro-updates
ms.topic: how-to
@ -18,6 +18,7 @@ appliesto:
ms.date: 10/12/2022
---
<!-- Customers will no longer update the private preview and instead install public preview
# Update or uninstall Microsoft Connected Cache for Enterprise and Education
Throughout the preview phase, we'll send you security and feature updates for MCC. Follow these steps to perform the update.
@ -35,8 +36,8 @@ For example:
```powershell
# .\updatemcc.ps1 version="msconnectedcacheprod.azurecr.io/mcc/linux/iot/mcc-ubuntu-iot-amd64:1.2.1.659" tenantid="799a999aa-99a1-99aa-99aa-9a9aa099db99" customerid="99a999aa-99a1-99aa-99aa-9aaa9aaa0saa" cachenodeid=" aa99aaaa-999a-9aas-99aa99daaa99 " customerkey="a99d999a-aaaa-aa99-0999aaaa99a"
```
## Uninstall MCC
-->
# Uninstall MCC
Please contact the MCC Team before uninstalling to let us know if you're facing issues.

8
windows/deployment/do/waas-delivery-optimization-reference.md
View File

@ -161,7 +161,7 @@ Starting in Windows 10, version 1803, set this policy to restrict peer selection
- 4 = DNS Suffix
- 5 = Starting with Windows 10, version 1903, you can use the Microsoft Entra tenant ID as a means to define groups. To do this set the value for DOGroupIdSource to its new maximum value of 5.
When set, the Group ID is assigned automatically from the selected source. If you set this policy, the GroupID policy is ignored. The default behavior, when the GroupID or GroupIDSource policies aren't set, is to determine the Group ID using AD Site (1), Authenticated domain SID (2) or Microsoft Entra tenant ID (5), in that order. If GroupIDSource is set to either DHCP Option ID (3) or DNS Suffix (4) and those methods fail, the default behavior is used instead. The option set in this policy only applies to Group (2) download mode. If Group (2) isn't set as Download mode, this policy will be ignored. If you set the value to anything other than 0-5, the policy is ignored.
When set, the Group ID will be assigned automatically from the selected source. This policy is ignored if the GroupID policy is also set. The default behavior, when the GroupID or GroupIDSource policies aren't set, is to determine the Group ID using AD Site (1), Authenticated domain SID (2) or Microsoft Entra tenant ID (5), in that order. If GroupIDSource is set to either DHCP Option ID (3) or DNS Suffix (4) and those methods fail, the default behavior is used instead. The option set in this policy only applies to Group (2) download mode. If Group (2) isn't set as Download mode, this policy will be ignored. If you set the value to anything other than 0-5, the policy is ignored.
### Minimum RAM (inclusive) allowed to use Peer Caching
@ -204,7 +204,7 @@ This setting specifies the minimum content file size in MB enabled to use Peer C
### Maximum Download Bandwidth
MDM Setting: **DOMaxUploadBandwidth**
MDM Setting: **DOMaxDownloadBandwidth**
Deprecated in Windows 10, version 2004.
This setting specifies the maximum download bandwidth that can be used across all concurrent Delivery Optimization downloads in kilobytes per second (KB/s). **A default value of "0"** means that Delivery Optimization dynamically adjusts and optimize the maximum bandwidth used.
@ -259,7 +259,7 @@ Starting in Windows 10, version 1803, set this policy to restrict peer selection
If Group mode is set, Delivery Optimization connects to locally discovered peers that are also part of the same Group (have the same Group ID).
The Local Peer Discovery (DNS-SD) option can only be set via MDM delivered policies on Windows 11 builds. This feature can be enabled in supported Windows 10 builds by setting the `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\DeliveryOptimization\DORestrictPeerSelectionBy` value to **2**.
In Windows 11, the Local Peer Discovery (DNS-SD) option can be set via MDM or Group Policy. However, in Windows 10, this feature can be enabled by setting the `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\DeliveryOptimization\DORestrictPeerSelectionBy` value to **2**.
### Delay background download from HTTP (in secs)
@ -335,7 +335,7 @@ The device can download from peers while on battery regardless of this policy.
MDM Setting: **DOCacheHost**
Set this policy to designate one or more Microsoft Connected Cache servers to be used by Delivery Optimization. You can set one or more FQDNs or IP Addresses that are comma-separated, for example: myhost.somerandomhost.com,myhost2.somerandomhost.com,10.10.1.7. **By default, this policy has no value.** Delivery Optimization client will connect to the listed Microsoft Connected Cache servers in the order as they are listed. When multiple FQDNs or IP Addresses are listed, the Microsoft Connected Cache server priority order is determined based on the order as they are listed. If the first server fails, it will move the the next one. When the last server fails, it will fallback to the CDN.
Set this policy to designate one or more Microsoft Connected Cache servers to be used by Delivery Optimization. You can set one or more FQDNs or IP Addresses that are comma-separated, for example: myhost.somerandomhost.com,myhost2.somerandomhost.com,10.10.1.7. **By default, this policy has no value.** Delivery Optimization client will connect to the listed Microsoft Connected Cache servers in the order as they are listed. When multiple FQDNs or IP Addresses are listed, the Microsoft Connected Cache server priority order is determined based on the order as they are listed. If the first server fails, it will move the next one. When the last server fails, it will fallback to the CDN.
>[!IMPORTANT]
> Any value will signify that the policy is set. For example, an empty string ("") isn't considered empty.

5
windows/deployment/do/waas-delivery-optimization.md
View File

@ -50,7 +50,8 @@ The following table lists the minimum Windows 10 version that supports Delivery
| Windows Client | Minimum Windows version | HTTP Downloader | Peer to Peer | Microsoft Connected Cache (MCC)
|------------------|---------------|----------------|----------|----------------|
| Windows Update ([feature updates quality updates, language packs, drivers](../update/get-started-updates-channels-tools.md#types-of-updates)) | Windows 10 1511, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Windows 10 Store apps | Windows 10 1511, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Windows 10/11 UWP Store apps | Windows 10 1511, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Windows 11 Win32 Store apps | Windows 11 | :heavy_check_mark: | | |
| Windows 10 Store for Business apps | Windows 10 1511, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Windows Defender definition updates | Windows 10 1511, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Intune Win32 apps| Windows 10 1709, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
@ -58,7 +59,7 @@ The following table lists the minimum Windows 10 version that supports Delivery
| Edge Browser Updates | Windows 10 1809, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Configuration Manager Express updates| Windows 10 1709 + Configuration Manager version 1711, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Dynamic updates| Windows 10 1903, Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| MDM Agent | Windows 11 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| MDM Agent | Windows 11 | :heavy_check_mark: | | |
| Xbox Game Pass (PC) | Windows 10 1809, Windows 11 | :heavy_check_mark: | | :heavy_check_mark: |
| Windows Package Manager| Windows 10 1809, Windows 11 | :heavy_check_mark: | | |
| MSIX Installer| Windows 10 2004, Windows 11 | :heavy_check_mark: | | |

5
windows/deployment/docfx.json
View File

@ -40,9 +40,8 @@
],
"breadcrumb_path": "/windows/resources/breadcrumb/toc.json",
"uhfHeaderId": "MSDocsHeader-Windows",
"feedback_system": "GitHub",
"feedback_github_repo": "MicrosoftDocs/windows-itpro-docs",
"feedback_product_url": "https://support.microsoft.com/windows/send-feedback-to-microsoft-with-the-feedback-hub-app-f59187f8-8739-22d6-ba93-f66612949332",
"feedback_system": "Standard",
"feedback_product_url": "https://support.microsoft.com/windows/send-feedback-to-microsoft-with-the-feedback-hub-app-f59187f8-8739-22d6-ba93-f66612949332",
"_op_documentIdPathDepotMapping": {
"./": {
"depot_name": "MSDN.win-development",

BIN
windows/deployment/images/insider.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

16
windows/deployment/includes/insider-note.md Normal file
View File

@ -0,0 +1,16 @@
---
author: paolomatarazzo
ms.author: paoloma
ms.topic: include
ms.date: 01/11/2024
---
:::row:::
:::column span="1":::
:::image type="content" source="../images/insider.png" alt-text="Logo of Windows Insider." border="false":::
:::column-end:::
:::column span="3":::
> [!IMPORTANT]
>This article describes features or settings that are under development and only applicable to [Windows Insider Preview builds](/windows-insider/). The content is subject to change and may have dependencies on other features or services in preview.
:::column-end:::
:::row-end:::

244
windows/deployment/index.yml
View File

@ -1,104 +1,180 @@
### YamlMime:Landing
### YamlMime:Hub
title: Windows client deployment resources and documentation # < 60 chars
summary: Learn about deploying and keeping Windows client devices up to date. # < 160 chars
title: Deploy and update Windows # < 60 chars; shows at top of hub page
summary: Learn about deploying and updating Windows client devices in your organization. # < 160 chars
metadata:
title: Windows client deployment resources and documentation # Required; page title displayed in search results. Include the brand. < 60 chars.
description: Learn about deploying Windows and keeping it up to date in your organization. # Required; article description that is displayed in search results. < 160 chars.
ms.topic: landing-page
ms.technology: itpro-deploy
title: Windows client deployment documentation # Required; browser tab title displayed in search results. Include the brand. < 60 chars.
description: Learn about deploying and updating Windows client devices in your organization. # Required; article description that is displayed in search results. < 160 chars.
ms.topic: hub-page
ms.prod: windows-client
ms.technology: itpro-deploy
ms.collection:
- highpri
- tier1
author: frankroj
ms.author: frankroj
author: aczechowski
ms.author: aaroncz
manager: aaroncz
ms.date: 10/31/2022
ms.date: 01/18/2024
localization_priority: medium
# linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new
landingContent:
# Cards and links should be based on top customer tasks or top subjects
# Start card title with a verb
# Card (optional)
- title: Plan
linkLists:
- linkListType: overview
links:
- text: Create a deployment plan
url: update/create-deployment-plan.md
- text: Define readiness criteria
url: update/plan-define-readiness.md
- text: Evaluate infrastructure and tools
url: update/eval-infra-tools.md
- text: Define your servicing strategy
url: update/plan-define-strategy.md
# common graphics: https://review.learn.microsoft.com/content-production-service/internal/image-gallery?branch=main
# Card (optional)
- title: Prepare
linkLists:
- linkListType: how-to-guide
productDirectory:
title: Get started
items:
- title: Plan
imageSrc: /media/common/i_overview.svg
links:
- text: Plan for Windows 11
url: /windows/whats-new/windows-11-plan?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json
- text: Create a deployment plan
url: update/create-deployment-plan.md
- text: Define readiness criteria
url: update/plan-define-readiness.md
- text: Define your servicing strategy
url: update/plan-define-strategy.md
- text: Determine application readiness
url: update/plan-determine-app-readiness.md
- text: Plan for volume activation
url: volume-activation/plan-for-volume-activation-client.md
- title: Prepare
imageSrc: /media/common/i_tasks.svg
links:
- text: Prepare for Windows 11
url: /windows/whats-new/windows-11-prepare?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json
- text: Prepare to deploy Windows updates
url: update/prepare-deploy-windows.md
- text: Prepare updates using Windows Update for Business
url: update/waas-manage-updates-wufb.md
- text: Evaluate and update infrastructure
url: update/update-policies.md
- text: Set up Delivery Optimization for Windows client updates
url: do/waas-delivery-optimization-setup.md?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json
- text: Prepare for imaging with Configuration Manager
url: deploy-windows-cm/prepare-for-zero-touch-installation-of-windows-10-with-configuration-manager.md
- title: Deploy
imageSrc: /media/common/i_deploy.svg
links:
- text: Deploy Windows with Autopilot
url: /mem/autopilot/tutorial/autopilot-scenarios
- text: Assign devices to servicing channels
url: update/waas-servicing-channels-windows-10-updates.md
- text: Deploy updates with Intune
url: update/deploy-updates-intune.md
- text: Deploy Windows updates with Configuration Manager
url: update/deploy-updates-configmgr.md
- text: Upgrade Windows using Configuration Manager
url: deploy-windows-cm/upgrade-to-windows-10-with-configuration-manager.md
- text: Check release health
url: update/check-release-health.md
additionalContent:
sections:
- title: Solutions
items:
- title: Windows Autopilot
links:
- text: Prepare to deploy Windows updates
url: update/prepare-deploy-windows.md
- text: Prepare updates using Windows Update for Business
- text: Overview
url: /mem/autopilot/windows-autopilot
- text: Scenarios
url: /mem/autopilot/tutorial/autopilot-scenarios
- text: Device registration
url: /mem/autopilot/registration-overview
- text: Learn more about Windows Autopilot >
url: /mem/autopilot
- title: Windows Autopatch
links:
- text: What is Windows Autopatch?
url: windows-autopatch/overview/windows-autopatch-overview.md
- text: Frequently asked questions (FAQ)
url: windows-autopatch/overview/windows-autopatch-faq.yml
- text: Prerequisites
url: windows-autopatch/prepare/windows-autopatch-prerequisites.md
- text: Learn more about Windows Autopatch >
url: windows-autopatch/index.yml
- title: Windows Update for Business
links:
- text: What is Windows Update for Business?
url: update/waas-manage-updates-wufb.md
- text: Prepare for Zero Touch Installation of Windows 10 with Configuration Manager
url: deploy-windows-cm/prepare-for-zero-touch-installation-of-windows-10-with-configuration-manager.md
- text: Set up Delivery Optimization for Windows client updates
- text: Windows Update for Business deployment service
url: update/deployment-service-overview.md
- text: Manage Windows Update settings
url: update/waas-wu-settings.md
- text: Windows Update for Business reports overview
url: update/wufb-reports-overview.md
- title: Optimize and cache content
links:
- text: What is Delivery Optimization?
url: do/waas-delivery-optimization.md
- text: What is Microsoft Connected Cache?
url: do/waas-microsoft-connected-cache.md
- text: Frequently asked questions
url: do/waas-delivery-optimization-faq.yml
- text: Learn more about Delivery Optimization >
url: do/index.yml
# Card (optional)
- title: Deploy
linkLists:
- linkListType: deploy
- title: In-place upgrade and imaging
links:
- text: Deploy Windows 10 with Autopilot
url: /mem/autopilot
- text: Assign devices to servicing channels
url: update/waas-servicing-channels-windows-10-updates.md
# Card
- title: Overview
linkLists:
- linkListType: overview
links:
- text: What's new in Windows deployment
url: deploy-whats-new.md
- text: Windows 11 overview
url: /windows/whats-new/windows-11
- text: Windows client deployment scenarios
url: windows-10-deployment-scenarios.md
- text: Basics of Windows updates, channels, and tools
url: update/get-started-updates-channels-tools.md
- text: Overview of Windows Autopilot
url: /mem/autopilot/windows-autopilot
- text: Upgrade Windows using Configuration Manager
url: deploy-windows-cm/upgrade-to-windows-10-with-configuration-manager.md
- text: Deploy a Windows image using Configuration Manager
url: deploy-windows-cm/refresh-a-windows-7-client-with-windows-10-using-configuration-manager.md
- text: Convert a disk from MBR to GPT
url: mbr-to-gpt.md
- text: Resolve Windows upgrade errors
url: upgrade/resolve-windows-upgrade-errors.md
# Card
- title: Support remote work
linkLists:
- linkListType: concept
- title: Licensing and activation
links:
- text: Deploy Windows 10 for a remote world
url: https://techcommunity.microsoft.com/t5/windows-it-pro-blog/deploying-a-new-version-of-windows-10-in-a-remote-world/ba-p/1419846
- text: Empower remote workers with Microsoft 365
url: /microsoft-365/solutions/empower-people-to-work-remotely
- text: Top 12 tasks for security teams to support working from home
url: /microsoft-365/security/top-security-tasks-for-remote-work
- text: Support your remote workforce
url: /microsoftteams/faq-support-remote-workforce
- text: Plan for volume activation
url: volume-activation/plan-for-volume-activation-client.md
- text: Subscription activation
url: windows-10-subscription-activation.md
- text: Volume activation management tool (VAMT)
url: volume-activation/introduction-vamt.md
- text: Activate using key management service (KMS)
url: volume-activation/activate-using-key-management-service-vamt.md
- text: Windows commercial licensing overview
url: /windows/whats-new/windows-licensing
# Card (optional)
- title: Microsoft Learn training
linkLists:
- linkListType: learn
- title: More resources
items:
- title: Release and lifecycle
links:
- text: Plan to deploy updates for Windows 10 and Microsoft 365 Apps
url: /training/modules/windows-plan
- text: Prepare to deploy updates for Windows 10 and Microsoft 365 Apps
url: /training/modules/windows-prepare/
- text: Deploy updates for Windows 10 and Microsoft 365 Apps
url: /training/modules/windows-deploy
- text: Windows release health dashboard
url: /windows/release-health
- text: Windows client features lifecycle
url: /windows/whats-new/feature-lifecycle
- text: Lifecycle FAQ - Windows
url: /lifecycle/faq/windows
- title: Windows hardware
links:
- text: Download and install the Windows ADK
url: /windows-hardware/get-started/adk-install
- text: Deployment tools
url: /windows-hardware/manufacture/desktop/boot-and-install-windows
# - text:
# url:
# - text:
# url:
- title: Community
links:
- text: Windows IT pro blog
url: https://techcommunity.microsoft.com/t5/windows-it-pro-blog/bg-p/Windows10Blog
- text: Windows office hours
url: https://aka.ms/windows/officehours
# - text:
# url:
# - text:
# url:

227
windows/deployment/mbr-to-gpt.md
View File

@ -4,7 +4,7 @@ description: Use MBR2GPT.EXE to convert a disk from the Master Boot Record (MBR)
ms.prod: windows-client
author: frankroj
ms.author: frankroj
ms.date: 11/23/2022
ms.date: 11/16/2023
manager: aaroncz
ms.localizationpriority: high
ms.topic: how-to
@ -12,19 +12,18 @@ ms.collection:
- highpri
- tier2
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# MBR2GPT.EXE
*Applies to:*
**MBR2GPT.EXE** converts a disk from the Master Boot Record (MBR) to the GUID Partition Table (GPT) partition style without modifying or deleting data on the disk. The tool runs from a Windows Preinstallation Environment (Windows PE) command prompt, but can also be run from the full Windows operating system (OS) by using the **`/allowFullOS`** option.
- Windows 10
**MBR2GPT.EXE** is located in the **`Windows\System32`** directory on a computer running Windows.
**MBR2GPT.EXE** converts a disk from the Master Boot Record (MBR) to the GUID Partition Table (GPT) partition style without modifying or deleting data on the disk. The tool runs from a Windows Preinstallation Environment (Windows PE) command prompt, but can also be run from the full Windows 10 operating system (OS) by using the **`/allowFullOS`** option.
MBR2GPT.EXE is located in the **`Windows\System32`** directory on a computer running Windows 10 version 1703 or later.
The tool is available in both the full OS environment and Windows PE. To use this tool in a deployment task sequence with Configuration Manager or Microsoft Deployment Toolkit (MDT), you must first update the Windows PE image (winpe.wim, boot.wim) with the [Windows ADK](https://developer.microsoft.com/windows/hardware/windows-assessment-deployment-kit) 1703, or a later version.
The tool is available in both the full OS environment and Windows PE.
See the following video for a detailed description and demonstration of MBR2GPT.
@ -33,13 +32,13 @@ See the following video for a detailed description and demonstration of MBR2GPT.
You can use MBR2GPT to:
- Convert any attached MBR-formatted system disk to the GPT partition format. You can't use the tool to convert non-system disks from MBR to GPT.
- Convert an MBR disk with BitLocker-encrypted volumes as long as protection has been suspended. To resume BitLocker after conversion, you'll need to delete the existing protectors and recreate them.
- Convert operating system disks that have earlier versions of Windows 10 installed, such as versions 1507, 1511, and 1607. However, you must run the tool while booted into Windows 10 version 1703 or later, and perform an offline conversion.
- Convert an operating system disk from MBR to GPT using Configuration Manager or MDT if your task sequence uses Windows PE version 1703 or later.
- Convert an MBR disk with BitLocker-encrypted volumes as long as protection is suspended. To resume BitLocker after conversion, you'll need to delete the existing protectors and recreate them.
- Convert an operating system disk from MBR to GPT using Microsoft Configuration Manager or Microsoft Deployment Toolkit (MDT).
Offline conversion of system disks with earlier versions of Windows installed, such as Windows 7, 8, or 8.1 aren't officially supported. The recommended method to convert these disks is to upgrade the operating system to Windows 10 first, then perform the MBR to GPT conversion.
Offline conversion of system disks with earlier versions of Windows installed, such as Windows 7, 8, or 8.1 aren't officially supported. The recommended method to convert these disks is to upgrade the operating system to a currently supported version of Windows, then perform the MBR to GPT conversion.
> [!IMPORTANT]
>
> After the disk has been converted to GPT partition style, the firmware must be reconfigured to boot in UEFI mode.
>
> Make sure that your device supports UEFI before attempting to convert the disk.
@ -57,9 +56,9 @@ Before any change to the disk is made, MBR2GPT validates the layout and geometry
- The disk doesn't have any extended/logical partition
- The BCD store on the system partition contains a default OS entry pointing to an OS partition
- The volume IDs can be retrieved for each volume that has a drive letter assigned
- All partitions on the disk are of MBR types recognized by Windows or has a mapping specified using the /map command-line option
- All partitions on the disk are of MBR types recognized by Windows or has a mapping specified using the `/map` command-line option
If any of these checks fails, the conversion won't proceed, and an error will be returned.
If any of these checks fails, the conversion doesn't proceed, and an error is returned.
## Syntax
@ -72,9 +71,9 @@ If any of these checks fails, the conversion won't proceed, and an error will be
|**/validate**| Instructs `MBR2GPT.exe` to perform only the disk validation steps and report whether the disk is eligible for conversion. |
|**/convert**| Instructs `MBR2GPT.exe` to perform the disk validation and to proceed with the conversion if all validation tests pass. |
|**/disk:*\<diskNumber\>***| Specifies the disk number of the disk to be converted to GPT. If not specified, the system disk is used. The mechanism used is the same as used by the diskpart.exe tool **SELECT DISK SYSTEM** command.|
|**/logs:*\<logDirectory\>***| Specifies the directory where `MBR2GPT.exe` logs should be written. If not specified, **%windir%** is used. If specified, the directory must already exist, it will not be automatically created or overwritten.|
|**/logs:*\<logDirectory\>***| Specifies the directory where `MBR2GPT.exe` logs should be written. If not specified, **%windir%** is used. If specified, the directory must already exist, it isn't automatically created or overwritten.|
|**/map:*\<source\>*=*\<destination\>***| Specifies other partition type mappings between MBR and GPT. The MBR partition number is specified in decimal notation, not hexadecimal. The GPT GUID can contain brackets, for example: **/map:42={af9b60a0-1431-4f62-bc68-3311714a69ad}**. Multiple /map options can be specified if multiple mappings are required. |
|**/allowFullOS**| By default, `MBR2GPT.exe` is blocked unless it's run from Windows PE. This option overrides this block and enables disk conversion while running in the full Windows environment. <br>**Note**: Since the existing MBR system partition is in use while running the full Windows environment, it can't be reused. In this case, a new ESP is created by shrinking the OS partition.|
|**/allowFullOS**| By default, `MBR2GPT.exe` can only run from Windows PE and is blocked from running in full Windows. This option overrides this block and enables disk conversion while running in the full Windows environment. <br>**Note**: Since the existing MBR system partition is in use while running the full Windows environment, it can't be reused. In this case, a new EFI system partition is created by shrinking the OS partition.|
## Examples
@ -83,7 +82,7 @@ If any of these checks fails, the conversion won't proceed, and an error will be
In the following example, disk 0 is validated for conversion. Errors and warnings are logged to the default location of **`%windir%`**.
```cmd
X:\>mbr2gpt.exe /validate /disk:0
X:\> mbr2gpt.exe /validate /disk:0
MBR2GPT: Attempting to validate disk 0
MBR2GPT: Retrieving layout of disk
MBR2GPT: Validating layout, disk sector size is: 512
@ -94,19 +93,24 @@ MBR2GPT: Validation completed successfully
In the following example:
1. Using DiskPart, the current disk partition layout is displayed prior to conversion - three partitions are present on the MBR disk (disk 0): a system reserved partition, a Windows partition, and a recovery partition. A DVD-ROM is also present as volume 0.
1. The current disk partition layout is displayed prior to conversion using DiskPart - three partitions are present on the MBR disk (disk 0):
2. The OS volume is selected, partitions are listed, and partition details are displayed for the OS partition. The [MBR partition type](/windows/win32/fileio/disk-partition-types) is **07** corresponding to the installable file system (IFS) type.
- A system reserved partition.
- A Windows partition.
- A recovery partition.
- A DVD-ROM is also present as volume 0.
3. The MBR2GPT tool is used to convert disk 0.
1. The OS volume is selected, partitions are listed, and partition details are displayed for the OS partition. The [MBR partition type](/windows/win32/fileio/disk-partition-types) is **07** corresponding to the installable file system (IFS) type.
4. The DiskPart tool displays that disk 0 is now using the GPT format.
1. The MBR2GPT tool is used to convert disk 0.
5. The new disk layout is displayed - four partitions are present on the GPT disk: three are identical to the previous partitions and one is the new EFI system partition (volume 3).
1. The DiskPart tool displays that disk 0 is now using the GPT format.
6. The OS volume is selected again, and detail displays that it has been converted to the [GPT partition type](/windows/win32/api/winioctl/ns-winioctl-partition_information_gpt) of **ebd0a0a2-b9e5-4433-87c0-68b6b72699c7** corresponding to the **PARTITION_BASIC_DATA_GUID** type.
1. The new disk layout is displayed - four partitions are present on the GPT disk: three are identical to the previous partitions and one is the new EFI system partition (volume 3).
As noted in the output from the MBR2GPT tool, you must make changes to the computer firmware so that the new EFI system partition will boot properly.
1. The OS volume is selected again. The detail displays that the OS volume is converted to the [GPT partition type](/windows/win32/api/winioctl/ns-winioctl-partition_information_gpt) of **ebd0a0a2-b9e5-4433-87c0-68b6b72699c7** corresponding to the **PARTITION_BASIC_DATA_GUID** type.
As noted in the output from the MBR2GPT tool, you must make changes to the computer firmware so that the new EFI system partition boots properly.
<br>
<details>
@ -240,42 +244,44 @@ Offset in Bytes: 524288000
The following steps illustrate high-level phases of the MBR-to-GPT conversion process:
1. Disk validation is performed.
2. The disk is repartitioned to create an EFI system partition (ESP) if one doesn't already exist.
3. UEFI boot files are installed to the ESP.
2. The disk is repartitioned to create an EFI system partition if one doesn't already exist.
3. UEFI boot files are installed to the EFI system partition.
4. GPT metadata and layout information are applied.
5. The boot configuration data (BCD) store is updated.
6. Drive letter assignments are restored.
### Creating an EFI system partition
For Windows to remain bootable after the conversion, an EFI system partition (ESP) must be in place. MBR2GPT creates the ESP using the following rules:
For Windows to remain bootable after the conversion, an EFI system partition must be in place. MBR2GPT creates the EFI system partition using the following rules:
1. The existing MBR system partition is reused if it meets these requirements:
1. It isn't also the OS or Windows Recovery Environment partition.
1. It is at least 100 MB (or 260 MB for 4K sector size disks) in size.
1. It's less than or equal to 1 GB in size. This size is a safety precaution to ensure it isn't a data partition.
1. The conversion isn't being performed from the full OS. In this case, the existing MBR system partition is in use and can't be repurposed.
2. If the existing MBR system partition can't be reused, a new ESP is created by shrinking the OS partition. This new partition has a size of 100 MB (or 260 MB for 4K sector size disks) and is formatted FAT32.
- It isn't also the OS or Windows Recovery Environment partition.
- It is at least 100 MB (or 260 MB for 4K sector size disks) in size.
- It's less than or equal to 1 GB in size. This size is a safety precaution to ensure it isn't a data partition.
- The conversion isn't being performed from the full OS. In this case, the existing MBR system partition is in use and can't be repurposed.
If the existing MBR system partition isn't reused for the ESP, it's no longer used by the boot process after the conversion. Other partitions aren't modified.
2. If the existing MBR system partition can't be reused, a new EFI system partition is created by shrinking the OS partition. This new partition has a size of 100 MB (or 260 MB for 4K sector size disks) and is formatted FAT32.
>[!IMPORTANT]
>If the existing MBR system partition is not reused for the ESP, it might be assigned a drive letter. If you do not wish to use this small partition, you must manually hide the drive letter.
If the existing MBR system partition isn't reused for the EFI system partition, it's no longer used by the boot process after the conversion. Other partitions aren't modified.
> [!IMPORTANT]
>
> If the existing MBR system partition is not reused for the EFI system partition, it might be assigned a drive letter. If you do not wish to use this small partition, you must manually hide the drive letter.
### Partition type mapping and partition attributes
Since GPT partitions use a different set of type IDs than MBR partitions, each partition on the converted disk must be assigned a new type ID. The partition type mapping follows these rules:
1. The ESP is always set to partition type PARTITION_SYSTEM_GUID (c12a7328-f81f-11d2-ba4b-00a0c93ec93b).
2. If an MBR partition is of a type that matches one of the entries specified in the /map switch, the specified GPT partition type ID is used.
3. If the MBR partition is of type 0x27, the partition is converted to a GPT partition of type PARTITION_MSFT_RECOVERY_GUID (de94bba4-06d1-4d40-a16a-bfd50179d6ac).
4. All other MBR partitions recognized by Windows are converted to GPT partitions of type PARTITION_BASIC_DATA_GUID (ebd0a0a2-b9e5-4433-87c0-68b6b72699c7).
1. The EFI system partition is always set to partition type **PARTITION_SYSTEM_GUID** (**c12a7328-f81f-11d2-ba4b-00a0c93ec93b**).
2. If an MBR partition is of a type that matches one of the entries specified in the `/map` switch, the specified GPT partition type ID is used.
3. If the MBR partition is of type **0x27**, the partition is converted to a GPT partition of type **PARTITION_MSFT_RECOVERY_GUID** (**de94bba4-06d1-4d40-a16a-bfd50179d6ac**).
4. All other MBR partitions recognized by Windows are converted to GPT partitions of type **PARTITION_BASIC_DATA_GUID** (**ebd0a0a2-b9e5-4433-87c0-68b6b72699c7**).
In addition to applying the correct partition types, partitions of type PARTITION_MSFT_RECOVERY_GUID also have the following GPT attributes set:
- GPT_ATTRIBUTE_PLATFORM_REQUIRED (0x0000000000000001)
- GPT_BASIC_DATA_ATTRIBUTE_NO_DRIVE_LETTER (0x8000000000000000)
- **GPT_ATTRIBUTE_PLATFORM_REQUIRED** (**0x0000000000000001**)
- **GPT_BASIC_DATA_ATTRIBUTE_NO_DRIVE_LETTER** (**0x8000000000000000**)
For more information about partition types, see:
@ -284,20 +290,21 @@ For more information about partition types, see:
### Persisting drive letter assignments
The conversion tool will attempt to remap all drive letter assignment information contained in the registry that corresponds to the volumes of the converted disk. If a drive letter assignment can't be restored, an error will be displayed at the console and in the log, so that you can manually perform the correct assignment of the drive letter.
The conversion tool attempts to remap all drive letter assignment information contained in the registry that corresponds to the volumes of the converted disk. If a drive letter assignment can't be restored, an error is displayed at the console and in the log, so that you can manually perform the correct assignment of the drive letter.
> [!IMPORTANT]
>
> This code runs after the layout conversion has taken place, so the operation cannot be undone at this stage.
The conversion tool will obtain volume unique ID data before and after the layout conversion, organizing this information into a lookup table. It will then iterate through all the entries in **HKLM\SYSTEM\MountedDevices**, and for each entry do the following:
The conversion tool will obtain volume unique ID data before and after the layout conversion, organizing this information into a lookup table. It then iterates through all the entries in **HKLM\SYSTEM\MountedDevices**, and for each entry it does the following:
1. Check if the unique ID corresponds to any of the unique IDs for any of the volumes that are part of the converted disk.
1. Checks if the unique ID corresponds to any of the unique IDs for any of the volumes that are part of the converted disk.
2. If found, set the value to be the new unique ID, obtained after the layout conversion.
3. If the new unique ID can't be set and the value name starts with \DosDevices, issue a console and log warning about the need for manual intervention in properly restoring the drive letter assignment.
3. If the new unique ID can't be set and the value name starts with **\DosDevices**, issue a console and log warning about the need for manual intervention in properly restoring the drive letter assignment.
## Troubleshooting
The tool will display status information in its output. Both validation and conversion are clear if any errors are encountered. For example, if one or more partitions don't translate properly, this is displayed and the conversion not performed. To view more detail about any errors that are encountered, see the associated [log files](#logs).
The tool displays status information in its output. Both validation and conversion are clear if any errors are encountered. For example, if one or more partitions don't translate properly, this information is displayed and the conversion not performed. To view more detail about any errors that are encountered, see the associated [log files](#logs).
### Logs
@ -308,16 +315,21 @@ Four log files are created by the MBR2GPT tool:
- setupact.log
- setuperr.log
These files contain errors and warnings encountered during disk validation and conversion. Information in these files can be helpful in diagnosing problems with the tool. The setupact.log and setuperr.log files will have the most detailed information about disk layouts, processes, and other information pertaining to disk validation and conversion.
These files contain errors and warnings encountered during disk validation and conversion. Information in these files can be helpful in diagnosing problems with the tool. The `setupact.log` and `setuperr.log` files have the most detailed information about disk layouts, processes, and other information pertaining to disk validation and conversion.
> [!NOTE]
> The setupact*.log files are different than the Windows Setup files that are found in the %Windir%\Panther directory.
>
> The **setupact*.log** files are different than the Windows Setup files that are found in the `%Windir%\Panther` directory.
The default location for all these log files in Windows PE is **%windir%**.
### Interactive help
To view a list of options available when using the tool, enter **`mbr2gpt.exe /?`**
To view a list of options available when using the tool, enter the following command in an elevated command prompt:
```cmd
mbr2gpt.exe /?
```
The following text is displayed:
@ -378,7 +390,21 @@ MBR2GPT has the following associated return codes:
### Determining the partition type
You can type the following command at a Windows PowerShell prompt to display the disk number and partition type. Example output is also shown:
The partition type can be determined in one of three ways:
- Using Windows PowerShell
- Using the Disk Management tool
- Using the DiskPart tool
#### Windows PowerShell
You can enter the following command at a Windows PowerShell prompt to display the disk number and partition type:
```powershell
Get-Disk | ft -Auto
``````
Example output:
```powershell
PS C:\> Get-Disk | ft -Auto
@ -389,11 +415,43 @@ Number Friendly Name Serial Number HealthStatus OperationalStatus To
1 ST1000DM003-1ER162 Z4Y3GD8F Healthy Online 931.51 GB GPT
```
You can also view the partition type of a disk by opening the Disk Management tool, right-clicking the disk number, clicking **Properties**, and then clicking the **Volumes** tab. See the following example:
#### Disk Management tool
:::image type="content" alt-text="Volumes." source="images/mbr2gpt-volume.png":::
You can view the partition type of a disk by using the Disk Management tool:
If Windows PowerShell and Disk Management aren't available, such as when you're using Windows PE, you can determine the partition type at a command prompt with the DiskPart tool. To determine the partition style from a command line, type **diskpart** and then type **list disk**. See the following example:
1. Right-click on the Start Menu and select **Disk Management**. Alternatively, right-click on the Start Menu and select **Run**. In the **Run** dialog box that appears, enter `diskmgmt.msc` and then select **OK**.
1. In the **Disk Management** window that appears:
1. On the bottom pane, select the disk number of interest.
1. Select the **Action** menu and then select **All Tasks > Properties**. Alternatively, right-click on the disk number of interest and select **Properties**.
1. In the **Properties** dialog box that appears for the disk, select the **Volumes** tab.
1. Under the **Volumes** tab, the partition type is displayed next to **Partition style:**.
#### DiskPart tool
The partition type can be determined with the DiskPart tool. The DiskPart tool is useful in scenarios where the Disk Management tool and PowerShell aren't available, such as in WinPE. PowerShell isn't available in WinPE when the PowerShell optional component isn't loaded. To use the DiskPart tool to determine the partition type:
1. Open an elevated command prompt.
1. In the elevated command prompt that opens enter the following command:
```cmd
DiskPart.exe
```
1. The **DISKPART>** prompt is displayed in the command prompt windows. At the **DISKPART>** prompt, enter the following command:
```cmd
list disk
```
1. The partition type is displayed in the **Gpt** column. If the partition is GPT, an asterisk (**\***) is displayed in the column. If the partition is MBR, the column is blank.
The following shows an example output of the DiskPart tool showing the partition type for two disks:
```cmd
X:\>DiskPart.exe
@ -412,66 +470,3 @@ DISKPART> list disk
```
In this example, Disk 0 is formatted with the MBR partition style, and Disk 1 is formatted using GPT.
## Known issue
### MBR2GPT.exe can't run in Windows PE
When you start a Windows 10, version 1903-based computer in the Windows Preinstallation Environment (Windows PE), you encounter the following issues:
**Issue 1** When you run the `MBR2GPT.exe` command, the process exits without converting the drive.
**Issue 2** When you manually run the `MBR2GPT.exe` command in a Command Prompt window, there's no output from the tool.
**Issue 3** When `MBR2GPT.exe` runs inside an imaging process such as a Microsoft Configuration Manager task sequence, an MDT task sequence, or by using a script, you receive the following exit code: 0xC0000135/3221225781.
#### Cause
This issue occurs because in Windows 10, version 1903 and later versions, `MBR2GPT.exe` requires access to the ReAgent.dll file. However, this dll file and its associated libraries are currently not included in the Windows PE boot image for Windows 10, version 1903 and later.
#### Workaround
To fix this issue, mount the Windows PE image (WIM), copy the missing file from the [Windows 10, version 1903 Assessment and Development Kit (ADK)](https://go.microsoft.com/fwlink/?linkid=2086042) source, and then commit the changes to the WIM. Use follow these steps:
1. Mount the Windows PE WIM to a path (for example, C:\WinPE_Mount). For more information about how to mount WIM files, see [Mount an image](/windows-hardware/manufacture/desktop/mount-and-modify-a-windows-image-using-dism#mount-an-image).
2. Copy the ReAgent files and the ReAgent localization files from the Windows 10, version 1903 ADK source folder to the mounted WIM.
For example, if the ADK is installed to the default location of C:\Program Files (x86)\Windows Kits\10 and the Windows PE image is mounted to C:\WinPE_Mount, run the following commands from an elevated Command Prompt window:
> [!NOTE]
> You can access the ReAgent files if you have installed the User State Migration Tool (USMT) as a feature while installing Windows Assessment and Deployment Kit.
**Command 1:**
```cmd
copy "C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Setup\amd64\Sources\ReAgent*.*" "C:\WinPE_Mount\Windows\System32"
```
This command copies three files:
- ReAgent.admx
- ReAgent.dll
- ReAgent.xml
**Command 2:**
```cmd
copy "C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Setup\amd64\Sources\En-Us\ReAgent*.*" "C:\WinPE_Mount\Windows\System32\En-Us"
```
This command copies two files:
- ReAgent.adml
- ReAgent.dll.mui
> [!NOTE]
> If you aren't using an English version of Windows, replace "En-Us" in the path with the appropriate string that represents the system language.
3. After you copy all the files, commit the changes and unmount the Windows PE WIM. `MBR2GPT.exe` now functions as expected in Windows PE. For information about how to unmount WIM files while committing changes, see [Unmounting an image](/windows-hardware/manufacture/desktop/mount-and-modify-a-windows-image-using-dism#unmounting-an-image).
## Related articles
[Windows 10 Enterprise system requirements](https://technet.microsoft.com/windows/dn798752.aspx)
<BR>[Windows 10 Specifications](https://www.microsoft.com/windows/Windows-10-specifications)
<BR>[Windows 10 IT pro forums](https://social.technet.microsoft.com/Forums/en-US/home?category=Windows10ITPro)

18
windows/deployment/update/create-deployment-plan.md
View File

@ -18,9 +18,9 @@ ms.date: 12/31/2017
# Create a deployment plan
A "service management" mindset means that the devices in your organization fall into a continuum, with the software update process being constantly planned, deployed, monitored, and optimized. And once you use this process for feature updates, quality updates become a lightweight procedure that is simple and fast to execute, ultimately increasing velocity.
A "service management" mindset means that the devices in your organization fall into a continuum, with the software update process being constantly planned, deployed, monitored, and optimized. Once you use this process for feature updates, quality updates become a lightweight procedure that is simple and fast to execute, ultimately increasing velocity.
When you move to a service management model, you need effective ways of rolling out updates to representative groups of devices. We've found that a ring-based deployment works well for us at Microsoft and many other organizations across the globe. Deployment rings in Windows client are similar to the deployment groups most organizations constructed for previous major revision upgrades. They're simply a method to separate devices into a deployment timeline.
When you move to a service management model, you need effective ways of rolling out updates to representative groups of devices. We've found that a ring-based deployment works well for us at Microsoft and many other organizations across the globe. Deployment rings in Windows clients are similar to the deployment groups most organizations constructed for previous major revision upgrades. They're simply a method to separate devices into a deployment timeline.
At the highest level, each ring comprises a group of users or devices that receive a particular update concurrently. For each ring, IT administrators set criteria to control deferral time or adoption (completion) that should be met before deployment to the next broader ring of devices or users can occur.
@ -43,10 +43,10 @@ There are no definite rules for exactly how many rings to have for your deployme
## Advancing between rings
There are basically two strategies for moving deployments from one ring to the next. One is service-based, the other project based.
There are basically two strategies for moving deployments from one ring to the next. One is service-based, the other project-based.
- "Red button" (service based): Assumes that content is good until proven bad. Content flows until an issue is discovered, at which point the IT administrator presses the "red button" to stop further distribution.
- Green button (project based): Assumes that content is bad until proven good. Once all validation has passed, the IT administrator presses the "green button" to push the content to the next ring.
- "Red button" (service-based): Assumes that content is good until proven bad. Content flows until an issue is discovered, at which point the IT administrator presses the "red button" to stop further distribution.
- "Green button" (project-based): Assumes that content is bad until proven good. Once all validation has passed, the IT administrator presses the "green button" to push the content to the next ring.
When it comes to deployments, having manual steps in the process usually impedes update velocity. A "red button" strategy is better when that is your goal.
@ -60,9 +60,9 @@ The purpose of the Preview ring is to evaluate the new features of the update. I
### Who goes in the Preview ring?
The Preview ring users are the most tech savvy and resilient people, who won't lose productivity if something goes wrong. In general, these users are IT pros, and perhaps a few people in the business organization.
The Preview ring users are the most tech-savvy and resilient people, who won't lose productivity if something goes wrong. In general, these users are IT pros, and perhaps a few people in the business organization.
During your plan and prepare phases, you should focus on the following activities:
During your plan and preparation phases, you should focus on the following activities:
- Work with Windows Insider Preview builds.
- Identify the features and functionality your organization can or wants to use.
@ -87,7 +87,7 @@ Analytics can help with defining a good Limited ring of representative devices a
The most important part of this phase is finding a representative sample of devices and applications across your network. If possible, all hardware and all applications should be represented. It's important that the people selected for this ring are using their devices regularly to generate the data you'll need to make a decision for broader deployment across your organization. The IT department, lab devices, and users with the most cutting-edge hardware usually don't have the applications or device drivers that are truly a representative sample of your network.
During your pilot and validate phases, you should focus on the following activities:
During your pilot and validation phases, you should focus on the following activities:
- Deploy new innovations.
- Assess and act if issues are encountered.
@ -104,7 +104,7 @@ Once the devices in the Limited ring have had a sufficient stabilization period,
In most businesses, the Broad ring includes the rest of your organization. Because of the work in the previous ring to vet stability and minimize disruption (with diagnostic data to support your decision), a broad deployment can occur relatively quickly.
> [!NOTE]
> In some instances, you might hold back on mission-critical devices (such as medical devices) until deployment in the Broad ring is complete. Get best practices and recommendations for deploying Windows client feature updates to mission critical-devices.
> In some instances, you might hold back on mission-critical devices (such as medical devices) until deployment in the Broad ring is complete. Get best practices and recommendations for deploying Windows client feature updates to mission-critical devices.
During the broad deployment phase, you should focus on the following activities:

2
windows/deployment/update/deployment-service-overview.md
View File

@ -27,7 +27,7 @@ Windows Update for Business product family has three elements:
- [Windows Update for Business reports](wufb-reports-overview.md) to monitor update deployment
- Deployment service APIs to approve and schedule specific updates for deployment, which are available through the Microsoft Graph and associated SDKs (including PowerShell)
The deployment service complements existing Windows Update for Business capabilities, including existing device policies and the[Windows Update for Business reports workbook](wufb-reports-workbook.md).
The deployment service complements existing Windows Update for Business capabilities, including existing device policies and the [Windows Update for Business reports workbook](wufb-reports-workbook.md).
:::image type="content" source="media/7512398-deployment-service-overview.png" alt-text="Diagram displaying the three elements that are parts of the Windows Update for Business family.":::

32
windows/deployment/update/eval-infra-tools.md
View File

@ -11,22 +11,22 @@ ms.localizationpriority: medium
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 12/31/2017
ms.date: 10/31/2023
---
# Evaluate infrastructure and tools
Before you deploy an update, it's best to assess your deployment infrastructure (that is, tools such as Configuration Manager, Microsoft Intune, or similar) and current configurations (such as security baselines, administrative templates, and policies that affect updates). Then, set some criteria to define your operational readiness.
Before you deploy an update, assess your deployment infrastructure. For example, management systems like Configuration Manager, Microsoft Intune, or similar. Also assess current configurations such as security baselines, administrative templates, and policies that affect updates. Then set some criteria to define your operational readiness.
## Infrastructure
Do your deployment tools need updates?
- If you use Configuration Manager, is it on the Current Branch with the latest release installed.? Being on this branch ensures that it supports the next Windows client feature update. Configuration Manager releases are supported for 18 months.
- If you use Configuration Manager, is it on the current branch with the latest release installed? Being on this branch ensures that it supports the next Windows client feature update. Configuration Manager releases are supported for 18 months.
- Using a cloud-based management tool like Microsoft Intune reduces support challenges, since no related products need to be updated.
- If you use a non-Microsoft tool, check with its product support to make sure you're using the current version and that it supports the next Windows client feature update.
Rely on your experiences and data from previous deployments to help you judge how long infrastructure changes take and identify any problems you've encountered while doing so.
Rely on your experiences and data from previous deployments to help you judge how long infrastructure changes take and identify any problems you've encountered.
## Device settings
@ -36,35 +36,35 @@ Make sure your security baseline, administrative templates, and policies have th
Keep security baselines current to help ensure that your environment is secure and that new security feature in the coming Windows client update are set properly.
- **Microsoft security baselines**: You should implement security baselines from Microsoft. They are included in the [Security Compliance Toolkit](https://www.microsoft.com/download/details.aspx?id=55319), along with tools for managing them.
- **Industry- or region-specific baselines**: Your specific industry or region might have particular baselines that you must follow per regulations. Ensure that any new baselines support the version of Windows client you are about to deploy.
- **Microsoft security baselines**: You should implement security baselines from Microsoft. They're included in the [Security Compliance Toolkit](https://www.microsoft.com/download/details.aspx?id=55319), along with tools for managing them.
- **Industry- or region-specific baselines**: Your specific industry or region might have particular baselines that you must follow per regulations. Ensure that any new baselines support the version of Windows client you're about to deploy.
### Configuration updates
There are a number of Windows policies (set by Group Policy, Intune, or other methods) that affect when Windows updates are installed, deferral, end-user experience, and many other aspects. Check these policies to make sure they are set appropriately.
There are several Windows policies that affect when Windows updates are installed, deferral, end-user experience, and many other aspects. For example, policies set by group policy, Intune, or other methods. Check these policies to make sure they're set appropriately.
- **Windows Administrative templates**: Each Windows client feature update has a supporting Administrative template (.admx) file. Group Policy tools use Administrative template files to populate policy settings in the user interface. The templates are available in the Download Center, for example, this one for [Windows 11, version 22H2](https://www.microsoft.com/download/details.aspx?id=104593).
- **Policies for update compliance and end-user experience**: A number of settings affect when a device installs updates, whether and for how long a user can defer an update, restart behavior after installation, and many other aspects of update behavior. It's especially important to look for existing policies that are out of date or could conflict with new ones.
- **Windows Administrative templates**: Each Windows client feature update has a supporting Administrative template (.admx) file. Group Policy tools use Administrative template files to populate policy settings in the user interface. The templates are available in the Download Center, for example, this one for [Windows 11, version 23H2](https://www.microsoft.com/download/details.aspx?id=105667).
- **Policies for update compliance and end-user experience**: Several settings affect when a device installs updates, whether and for how long a user can defer an update, restart behavior after installation, and many other aspects of update behavior. It's especially important to look for existing policies that are out of date or could conflict with new ones.
## Define operational readiness criteria
When you’ve deployed an update, you’ll need to make sure the update isn’t introducing new operational issues. And you’ll also ensure that if incidents arise, the needed documentation and processes are available. Work with your operations and support team to define acceptable trends and what documents or processes require updating:
When you deploy an update, you need to make sure the update isn't introducing new operational issues. If incidents arise, make sure the needed documentation and processes are available. Work with your operations and support team to define acceptable trends and what documents or processes require updating:
- **Call trend**: Define what percentage increase in calls relating to Windows client feature updates are acceptable or can be supported.
- **Incident trend**: Define what percentage of increase in calls asking for support relating to Windows client feature updates are acceptable or can be supported.
- **Support documentation**: Review supporting documentation that requires an update to support new infrastructure tooling or configuration as part of the Windows client feature update.
- **Process changes:** Define and update any processes that will change as a result of the Windows 10 feature update.
- **Process changes:** Define and update any processes that will change as a result of the Windows feature update.
Your operations and support staff can help you determine if the appropriate information is being tracked at the moment. If it isn't, work out how to get this information so you can gain the right insight.
Your operations and support staff can help you determine if the appropriate information is being tracked at the moment. If it isn't, work out how to get this information so you can gain the right insight.
## Tasks
Finally, you can begin to carry out the work needed to ensure your infrastructure and configuration can support the update. To help you keep track, you can classify the work into the following overarching tasks:
- **Review infrastructure requirements**: Go over the details of requirements to support the update, and ensure they’ve all been defined.
- **Validate infrastructure against requirements**: Compare your infrastructure against the requirements that have been identified for the update.
- **Review infrastructure requirements**: Go over the details of requirements to support the update, and ensure they've all been defined.
- **Validate infrastructure against requirements**: Compare your infrastructure against the requirements that you identified for the update.
- **Define infrastructure update plan**: Detail how your infrastructure must change to support the update.
- **Review current support volume**: Understand the current support volume to understand how much of an effect the update has when it’s been deployed.
- **Identify gaps that require attention**: Identify issues that will need to be addressed to successfully deploy the update. For example, will your infrastructure engineer have to research how a new feature that comes with the update might affect the infrastructure?
- **Review current support volume**: Understand the current support volume to understand how much of an effect the update has when you deploy it.
- **Identify gaps that require attention**: Identify issues that you'll need to address to successfully deploy the update. For example, will your infrastructure engineer have to research how a new feature that comes with the update might affect the infrastructure?
- **Define operational update plan**: Detail how your operational services and processes must change to support the update.

9
windows/deployment/update/includes/wufb-reports-endpoints.md
View File

@ -5,10 +5,11 @@ manager: aaroncz
ms.technology: itpro-updates
ms.prod: windows-client
ms.topic: include
ms.date: 08/21/2023
ms.date: 12/15/2023
ms.localizationpriority: medium
---
<!--This file is shared by updates/wufb-reports-prerequisites.md and the update/update-compliance-configuration-manual.md articles. Headings are driven by article context. -->
<!-- This file is shared by update/wufb-reports-prerequisites.md and update/wufb-reports-configuration-manual.md articles. Headings are driven by article context. -->
Devices must be able to contact the following endpoints in order to authenticate and send diagnostic data:
@ -20,5 +21,5 @@ Devices must be able to contact the following endpoints in order to authenticate
| `settings-win.data.microsoft.com` | Used by Windows components and applications to dynamically update their configuration. Required for Windows Update functionality. |
| `adl.windows.com` | Required for Windows Update functionality. |
| `oca.telemetry.microsoft.com` | Online Crash Analysis, used to provide device-specific recommendations and detailed errors if there are certain crashes. |
| `login.live.com` | This endpoint facilitates your Microsoft account access and is required to create the primary identifier we use for devices. Without this service, devices won't be visible in the solution. The Microsoft Account Sign-in Assistant service must also be running (wlidsvc). |
| `*.blob.core.windows.net` | Azure blob data storage.|
| `login.live.com` | This endpoint facilitates your Microsoft account access and is required to create the primary identifier we use for devices. Without this service, devices aren't visible in the solution. The Microsoft Account Sign-in Assistant service must also be running (wlidsvc). |
| `ceuswatcab01.blob.core.windows.net` <br> `ceuswatcab02.blob.core.windows.net` <br> `eaus2watcab01.blob.core.windows.net` <br> `eaus2watcab02.blob.core.windows.net` <br> `weus2watcab01.blob.core.windows.net` <br> `weus2watcab02.blob.core.windows.net` | Azure blob data storage. <!-- 8603508 --> |

455
windows/deployment/update/media-dynamic-update.md
View File

@ -12,7 +12,8 @@ ms.localizationpriority: medium
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 07/17/2023
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Windows Server</a>
ms.date: 12/05/2023
---
# Update Windows installation media with Dynamic Update
@ -83,24 +84,24 @@ Properly updating the installation media involves a large number of actions oper
This table shows the correct sequence for applying the various tasks to the files. For example, the full sequence starts with adding the servicing stack update to WinRE (1) and concludes with adding boot manager from WinPE to the new media (28).
|Task |WinRE (winre.wim) |WinPE (boot.wim) |Operating system (install.wim) | New media |
|-----------------------------------|-------------------|------------------|--------------------------------|-----------|
|Add servicing stack Dynamic Update | 1 | 9 | 18 | |
|Add language pack | 2 | 10 | 19 | |
|Add localized optional packages | 3 | 11 | | |
|Add font support | 4 | 12 | | |
|Add text-to-speech | 5 | 13 | | |
|Update Lang.ini | | 14 | | |
|Add Features on Demand | | | 20 | |
|Add Safe OS Dynamic Update | 6 | | | |
|Add Setup Dynamic Update | | | | 26 |
|Add setup.exe from WinPE | | | | 27 |
|Add boot manager from WinPE | | | | 28 |
|Add latest cumulative update | | 15 | 21 | |
|Clean up the image | 7 | 16 | 22 | |
|Add Optional Components | | | 23 | |
|Add .NET and .NET cumulative updates | | | 24 | |
|Export image | 8 | 17 | 25 | |
|Task |WinRE (winre.wim) |Operating system (install.wim) | WinPE (boot.wim) | New media |
|-----------------------------------|-------------------|--------------------------------|------------------|-----------|
|Add servicing stack Dynamic Update | 1 | 9 | 17 | |
|Add language pack | 2 | 10 | 18 | |
|Add localized optional packages | 3 | | 19 | |
|Add font support | 4 | | 20 | |
|Add text-to-speech | 5 | | 21 | |
|Update Lang.ini | | | 22 | |
|Add Features on Demand | | 11 | | |
|Add Safe OS Dynamic Update | 6 | | | |
|Add Setup Dynamic Update | | | | 26 |
|Add setup.exe from WinPE | | | | 27 |
|Add boot manager from WinPE | | | | 28 |
|Add latest cumulative update | | 12 | 23 | |
|Clean up the image | 7 | 13 | 24 | |
|Add Optional Components | | 14 | | |
|Add .NET and .NET cumulative updates | | 15 | | |
|Export image | 8 | 16 | 25 | |
> [!NOTE]
> Starting in February 2021, the latest cumulative update and servicing stack update will be combined and distributed in the Microsoft Update Catalog as a new combined cumulative update. For Steps 1, 9, and 18 that require the servicing stack update for updating the installation media, you should use the combined cumulative update. For more information on the combined cumulative update, see [Servicing stack updates](./servicing-stack-updates.md).
@ -110,13 +111,13 @@ This table shows the correct sequence for applying the various tasks to the file
### Multiple Windows editions
The main operating system file (install.wim) contains multiple editions of Windows. It's possible that only an update for a given edition is required to deploy it, based on the index. Or, it might be that all editions need an update. Further, ensure that languages are installed before Features on Demand, and the latest cumulative update is always applied last.
The main operating system file (install.wim) might contain multiple editions of Windows. It's possible that only an update for a given edition is required to deploy it, based on the index. Or, it might be that all editions need an update. Further, ensure that languages are installed before Features on Demand, and the latest cumulative update is always applied last.
### Additional languages and features
You don't have to add more languages and features to the image to accomplish the updates, but it's an opportunity to customize the image with more languages, Optional Components, and Features on Demand beyond what is in your starting image. To do this, it's important to make these changes in the correct order: first apply servicing stack updates, followed by language additions, then by feature additions, and finally the latest cumulative update. The provided sample script installs a second language (in this case Japanese (ja-JP)). Since this language is backed by an lp.cab, there's no need to add a Language Experience Pack. Japanese is added to both the main operating system and to the recovery environment to allow the user to see the recovery screens in Japanese. This includes adding localized versions of the packages currently installed in the recovery image.
You don't have to add more languages and features to the image to accomplish the updates, but it's an opportunity to customize the image with more languages, Optional Components, and Features on Demand beyond what's in your starting image. When you add more languages and features, it's important to make these changes in the correct order: first apply servicing stack updates, followed by language additions, then by feature additions, and finally the latest cumulative update. The provided sample script installs a second language (in this case Japanese (ja-JP)). Since this language is backed by an lp.cab, there's no need to add a Language Experience Pack. Japanese is added to both the main operating system and to the recovery environment to allow the user to see the recovery screens in Japanese. This includes adding localized versions of the packages currently installed in the recovery image.
Optional Components, along with the .NET feature, can be installed offline, however doing so creates pending operations that require the device to restart. As a result, the call to perform image cleanup would fail. There are two options to avoid this. One option is to skip the image cleanup step, though that results in a larger install.wim. Another option is to install the .NET and Optional Components in a step after cleanup but before export. This is the option in the sample script. By doing this, you'll have to start with the original install.wim (with no pending actions) when you maintain or update the image the next time (for example, the next month).
Optional Components, along with the .NET feature, can be installed offline, however doing so creates pending operations that require the device to restart. As a result, the call to perform image cleanup would fail. There are two options to avoid the cleanup failure. One option is to skip the image cleanup step, though that results in a larger install.wim. Another option is to install the .NET and Optional Components in a step after cleanup but before export. This is the option in the sample script. By doing this, you'll have to start with the original install.wim (with no pending actions) when you maintain or update the image the next time (for example, the next month).
## Windows PowerShell scripts to apply Dynamic Updates to an existing image
@ -130,7 +131,7 @@ These examples are for illustration only, and therefore lack error handling. The
### Get started
The script starts by declaring global variables and creating folders to use for mounting images. Then, make a copy of the original media, from \oldMedia to \newMedia, keeping the original media in case there's a script error and it's necessary to start over from a known state. Also, it will provide a comparison of old versus new media to evaluate changes. To ensure that the new media updates, make sure they aren't read-only.
The script starts by declaring global variables and creating folders to use for mounting images. Then, make a copy of the original media, from \oldMedia to \newMedia, keeping the original media in case there's a script error and it's necessary to start over from a known state. Also, it provides a comparison of old versus new media to evaluate changes. To ensure that the new media updates, make sure they aren't read-only.
```powershell
#Requires -RunAsAdministrator
@ -194,128 +195,231 @@ Copy-Item -Path $MEDIA_OLD_PATH"\*" -Destination $MEDIA_NEW_PATH -Force -Recurse
Get-ChildItem -Path $MEDIA_NEW_PATH -Recurse | Where-Object { -not $_.PSIsContainer -and $_.IsReadOnly } | ForEach-Object { $_.IsReadOnly = $false }
```
### Update WinRE
### Update WinRE and each main OS Windows edition
The script assumes that only a single edition is being updated, indicated by Index = 1 (Windows 10 Education Edition). Then the script mounts the image, saves Winre.wim to the working folder, and mounts it. It then applies servicing stack Dynamic Update, since its components are used for updating other components. Since the script is optionally adding Japanese, it adds the language pack to the image, and installs the Japanese versions of all optional packages already installed in Winre.wim. Then, it applies the Safe OS Dynamic Update package.
The script will update each edition of Windows within the main operating system file (install.wim). For each edition, the main OS image is mounted.
It finishes by cleaning and exporting the image to reduce the image size.
For the first image, Winre.wim is copied to the working folder, and mounted. It then applies servicing stack Dynamic Update, since its components are used for updating other components. Since the script is optionally adding Japanese, it adds the language pack to the image, and installs the Japanese versions of all optional packages already installed in Winre.wim. Then, it applies the Safe OS Dynamic Update package. It finishes by cleaning and exporting the image to reduce the image size.
Next, for the mounted OS image, the script starts by applying the servicing stack Dynamic Update. Then, it adds Japanese language support and then the Japanese language features. Unlike the Dynamic Update packages, it uses `Add-WindowsCapability` to add these features. For a full list of such features, and their associated capability name, see [Available Features on Demand](/windows-hardware/manufacture/desktop/features-on-demand-non-language-fod). Now is the time to enable other Optional Components or add other Features on Demand. If such a feature has an associated cumulative update (for example, .NET), this is the time to apply those. The script then proceeds with applying the latest cumulative update. Finally, the script cleans and exports the image. You can install Optional Components, along with the .NET feature, offline, but that requires the device to be restarted. This is why the script installs .NET and Optional Components after cleanup and before export.
This process is repeated for each edition of Windows within the main operating system file. To reduce size, the serviced Winre.wim file from the first image is saved, and used to update each subsequent Windows edition. This reduces the final size of install.wim.
```powershell
# Mount the main operating system, used throughout the script
Write-Output "$(Get-TS): Mounting main OS"
Mount-WindowsImage -ImagePath $MEDIA_NEW_PATH"\sources\install.wim" -Index 1 -Path $MAIN_OS_MOUNT -ErrorAction stop| Out-Null
#
# update Windows Recovery Environment (WinRE)
# Update each main OS Windows image including the Windows Recovery Environment (WinRE)
#
Copy-Item -Path $MAIN_OS_MOUNT"\windows\system32\recovery\winre.wim" -Destination $WORKING_PATH"\winre.wim" -Force -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Mounting WinRE"
Mount-WindowsImage -ImagePath $WORKING_PATH"\winre.wim" -Index 1 -Path $WINRE_MOUNT -ErrorAction stop | Out-Null
# Add servicing stack update (Step 1 from the table)
# Get the list of images contained within WinPE
$WINOS_IMAGES = Get-WindowsImage -ImagePath $MEDIA_NEW_PATH"\sources\install.wim"
# Depending on the Windows release that you are updating, there are 2 different approaches for updating the servicing stack
# The first approach is to use the combined cumulative update. This is for Windows releases that are shipping a combined
# cumulative update that includes the servicing stack updates (i.e. SSU + LCU are combined). Windows 11, version 21H2 and
# Windows 11, version 22H2 are examples. In these cases, the servicing stack update is not published separately; the combined
# cumulative update should be used for this step. However, in hopefully rare cases, there may breaking change in the combined
# cumulative update format, that requires a standalone servicing stack update to be published, and installed first before the
# combined cumulative update can be installed.
Foreach ($IMAGE in $WINOS_IMAGES) {
# This is the code to handle the rare case that the SSU is published and required for the combined cumulative update
# Write-Output "$(Get-TS): Adding package $SSU_PATH"
# Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $SSU_PATH | Out-Null
# first mount the main OS image
Write-Output "$(Get-TS): Mounting main OS, image index $($IMAGE.ImageIndex)"
Mount-WindowsImage -ImagePath $MEDIA_NEW_PATH"\sources\install.wim" -Index $IMAGE.ImageIndex -Path $MAIN_OS_MOUNT -ErrorAction stop| Out-Null
# Now, attempt the combined cumulative update.
# There is a known issue where the servicing stack update is installed, but the cumulative update will fail. This error should
# be caught and ignored, as the last step will be to apply the Safe OS update and thus the image will be left with the correct
# packages installed.
if ($IMAGE.ImageIndex -eq "1") {
try
{
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $LCU_PATH | Out-Null
}
Catch
{
$theError = $_
Write-Output "$(Get-TS): $theError"
#
# update Windows Recovery Environment (WinRE) within this OS image
#
Copy-Item -Path $MAIN_OS_MOUNT"\windows\system32\recovery\winre.wim" -Destination $WORKING_PATH"\winre.wim" -Force -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Mounting WinRE"
Mount-WindowsImage -ImagePath $WORKING_PATH"\winre.wim" -Index 1 -Path $WINRE_MOUNT -ErrorAction stop | Out-Null
# Add servicing stack update (Step 1 from the table)
# Depending on the Windows release that you are updating, there are 2 different approaches for updating the servicing stack
# The first approach is to use the combined cumulative update. This is for Windows releases that are shipping a combined
# cumulative update that includes the servicing stack updates (i.e. SSU + LCU are combined). Windows 11, version 21H2 and
# Windows 11, version 22H2 are examples. In these cases, the servicing stack update is not published seperately; the combined
# cumulative update should be used for this step. However, in hopefully rare cases, there may breaking change in the combined
# cumulative update format, that requires a standalone servicing stack update to be published, and installed first before the
# combined cumulative update can be installed.
# This is the code to handle the rare case that the SSU is published and required for the combined cumulative update
# Write-Output "$(Get-TS): Adding package $SSU_PATH"
# Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $SSU_PATH | Out-Null
# Now, attempt the combined cumulative update.
# There is a known issue where the servicing stack update is installed, but the cumulative update will fail. This error should
# be caught and ignored, as the last step will be to apply the Safe OS update and thus the image will be left with the correct
# packages installed.
try
{
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $LCU_PATH | Out-Null
}
Catch
{
$theError = $_
Write-Output "$(Get-TS): $theError"
if ($theError.Exception -like "*0x8007007e*") {
Write-Output "$(Get-TS): This failure is a known issue with combined cumulative update, we can ignore."
}
else {
throw
}
}
# The second approach for Step 1 is for Windows releases that have not adopted the combined cumulative update
# but instead continue to have a separate servicing stack update published. In this case, we'll install the SSU
# update. This second approach is commented out below.
# Write-Output "$(Get-TS): Adding package $SSU_PATH"
# Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $SSU_PATH | Out-Null
#
# Optional: Add the language to recovery environment
#
# Install lp.cab cab
Write-Output "$(Get-TS): Adding package $WINPE_OC_LP_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $WINPE_OC_LP_PATH -ErrorAction stop | Out-Null
# Install language cabs for each optional package installed
$WINRE_INSTALLED_OC = Get-WindowsPackage -Path $WINRE_MOUNT
Foreach ($PACKAGE in $WINRE_INSTALLED_OC) {
if ( ($PACKAGE.PackageState -eq "Installed") `
-and ($PACKAGE.PackageName.startsWith("WinPE-")) `
-and ($PACKAGE.ReleaseType -eq "FeaturePack") ) {
$INDEX = $PACKAGE.PackageName.IndexOf("-Package")
if ($INDEX -ge 0) {
$OC_CAB = $PACKAGE.PackageName.Substring(0, $INDEX) + "_" + $LANG + ".cab"
if ($WINPE_OC_LANG_CABS.Contains($OC_CAB)) {
$OC_CAB_PATH = Join-Path $WINPE_OC_LANG_PATH $OC_CAB
Write-Output "$(Get-TS): Adding package $OC_CAB_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $OC_CAB_PATH -ErrorAction stop | Out-Null
if ($theError.Exception -like "*0x8007007e*") {
Write-Output "$(Get-TS): This failure is a known issue with combined cumulative update, we can ignore."
}
else {
throw
}
}
# The second approach for Step 1 is for Windows releases that have not adopted the combined cumulative update
# but instead continue to have a seperate servicing stack update published. In this case, we'll install the SSU
# update. This second approach is commented out below.
# Write-Output "$(Get-TS): Adding package $SSU_PATH"
# Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $SSU_PATH | Out-Null
#
# Optional: Add the language to recovery environment
#
# Install lp.cab cab
Write-Output "$(Get-TS): Adding package $WINPE_OC_LP_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $WINPE_OC_LP_PATH -ErrorAction stop | Out-Null
# Install language cabs for each optional package installed
$WINRE_INSTALLED_OC = Get-WindowsPackage -Path $WINRE_MOUNT
Foreach ($PACKAGE in $WINRE_INSTALLED_OC) {
if ( ($PACKAGE.PackageState -eq "Installed") `
-and ($PACKAGE.PackageName.startsWith("WinPE-")) `
-and ($PACKAGE.ReleaseType -eq "FeaturePack") ) {
$INDEX = $PACKAGE.PackageName.IndexOf("-Package")
if ($INDEX -ge 0) {
$OC_CAB = $PACKAGE.PackageName.Substring(0, $INDEX) + "_" + $LANG + ".cab"
if ($WINPE_OC_LANG_CABS.Contains($OC_CAB)) {
$OC_CAB_PATH = Join-Path $WINPE_OC_LANG_PATH $OC_CAB
Write-Output "$(Get-TS): Adding package $OC_CAB_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $OC_CAB_PATH -ErrorAction stop | Out-Null
}
}
}
}
# Add font support for the new language
if ( (Test-Path -Path $WINPE_FONT_SUPPORT_PATH) ) {
Write-Output "$(Get-TS): Adding package $WINPE_FONT_SUPPORT_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $WINPE_FONT_SUPPORT_PATH -ErrorAction stop | Out-Null
}
# Add TTS support for the new language
if (Test-Path -Path $WINPE_SPEECH_TTS_PATH) {
if ( (Test-Path -Path $WINPE_SPEECH_TTS_LANG_PATH) ) {
Write-Output "$(Get-TS): Adding package $WINPE_SPEECH_TTS_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $WINPE_SPEECH_TTS_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding package $WINPE_SPEECH_TTS_LANG_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $WINPE_SPEECH_TTS_LANG_PATH -ErrorAction stop | Out-Null
}
}
# Add Safe OS
Write-Output "$(Get-TS): Adding package $SAFE_OS_DU_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $SAFE_OS_DU_PATH -ErrorAction stop | Out-Null
# Perform image cleanup
Write-Output "$(Get-TS): Performing image cleanup on WinRE"
DISM /image:$WINRE_MOUNT /cleanup-image /StartComponentCleanup /ResetBase /Defer | Out-Null
# Dismount
Dismount-WindowsImage -Path $WINRE_MOUNT -Save -ErrorAction stop | Out-Null
# Export
Write-Output "$(Get-TS): Exporting image to $WORKING_PATH\winre.wim"
Export-WindowsImage -SourceImagePath $WORKING_PATH"\winre.wim" -SourceIndex 1 -DestinationImagePath $WORKING_PATH"\winre2.wim" -ErrorAction stop | Out-Null
}
Copy-Item -Path $WORKING_PATH"\winre2.wim" -Destination $MAIN_OS_MOUNT"\windows\system32\recovery\winre.wim" -Force -ErrorAction stop | Out-Null
#
# update Main OS
#
# Add servicing stack update (Step 18 from the table)
# Depending on the Windows release that you are updating, there are 2 different approaches for updating the servicing stack
# The first approach is to use the combined cumulative update. This is for Windows releases that are shipping a combined cumulative update that
# includes the servicing stack updates (i.e. SSU + LCU are combined). Windows 11, version 21H2 and Windows 11, version 22H2 are examples. In these
# cases, the servicing stack update is not published seperately; the combined cumulative update should be used for this step. However, in hopefully
# rare cases, there may breaking change in the combined cumulative update format, that requires a standalone servicing stack update to be published,
# and installed first before the combined cumulative update can be installed.
# This is the code to handle the rare case that the SSU is published and required for the combined cumulative update
# Write-Output "$(Get-TS): Adding package $SSU_PATH"
# Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $SSU_PATH | Out-Null
# Now, attempt the combined cumulative update. Unlike WinRE and WinPE, we don't need to check for error 0x8007007e
Write-Output "$(Get-TS): Adding package $LCU_PATH"
Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $LCU_PATH | Out-Null
# The second approach for Step 18 is for Windows releases that have not adopted the combined cumulative update
# but instead continue to have a seperate servicing stack update published. In this case, we'll install the SSU
# update. This second approach is commented out below.
# Write-Output "$(Get-TS): Adding package $SSU_PATH"
# Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $SSU_PATH | Out-Null
# Optional: Add language to main OS
Write-Output "$(Get-TS): Adding package $OS_LP_PATH"
Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $OS_LP_PATH -ErrorAction stop | Out-Null
# Optional: Add a Features on Demand to the image
Write-Output "$(Get-TS): Adding language FOD: Language.Fonts.Jpan~~~und-JPAN~0.0.1.0"
Add-WindowsCapability -Name "Language.Fonts.$LANG_FONT_CAPABILITY~~~und-$LANG_FONT_CAPABILITY~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD: Language.Basic~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.Basic~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD: Language.OCR~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.OCR~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD: Language.Handwriting~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.Handwriting~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD: Language.TextToSpeech~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.TextToSpeech~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD:Language.Speech~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.Speech~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
# Note: If I wanted to enable additional Features on Demand, I'd add these here.
# Add latest cumulative update
Write-Output "$(Get-TS): Adding package $LCU_PATH"
Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $LCU_PATH -ErrorAction stop | Out-Null
# Perform image cleanup
Write-Output "$(Get-TS): Performing image cleanup on main OS"
DISM /image:$MAIN_OS_MOUNT /cleanup-image /StartComponentCleanup | Out-Null
#
# Note: If I wanted to enable additional Optional Components, I'd add these here.
# In addition, we'll add .NET 3.5 here as well. Both .NET and Optional Components might require
# the image to be booted, and thus if we tried to cleanup after installation, it would fail.
#
Write-Output "$(Get-TS): Adding NetFX3~~~~"
Add-WindowsCapability -Name "NetFX3~~~~" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
# Add .NET Cumulative Update
Write-Output "$(Get-TS): Adding package $DOTNET_CU_PATH"
Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $DOTNET_CU_PATH -ErrorAction stop | Out-Null
# Dismount
Dismount-WindowsImage -Path $MAIN_OS_MOUNT -Save -ErrorAction stop | Out-Null
# Export
Write-Output "$(Get-TS): Exporting image to $WORKING_PATH\install2.wim"
Export-WindowsImage -SourceImagePath $MEDIA_NEW_PATH"\sources\install.wim" -SourceIndex $IMAGE.ImageIndex -DestinationImagePath $WORKING_PATH"\install2.wim" -ErrorAction stop | Out-Null
}
# Add font support for the new language
if ( (Test-Path -Path $WINPE_FONT_SUPPORT_PATH) ) {
Write-Output "$(Get-TS): Adding package $WINPE_FONT_SUPPORT_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $WINPE_FONT_SUPPORT_PATH -ErrorAction stop | Out-Null
}
# Add TTS support for the new language
if (Test-Path -Path $WINPE_SPEECH_TTS_PATH) {
if ( (Test-Path -Path $WINPE_SPEECH_TTS_LANG_PATH) ) {
Write-Output "$(Get-TS): Adding package $WINPE_SPEECH_TTS_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $WINPE_SPEECH_TTS_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding package $WINPE_SPEECH_TTS_LANG_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $WINPE_SPEECH_TTS_LANG_PATH -ErrorAction stop | Out-Null
}
}
# Add Safe OS
Write-Output "$(Get-TS): Adding package $SAFE_OS_DU_PATH"
Add-WindowsPackage -Path $WINRE_MOUNT -PackagePath $SAFE_OS_DU_PATH -ErrorAction stop | Out-Null
# Perform image cleanup
Write-Output "$(Get-TS): Performing image cleanup on WinRE"
DISM /image:$WINRE_MOUNT /cleanup-image /StartComponentCleanup /ResetBase /Defer | Out-Null
# Dismount
Dismount-WindowsImage -Path $WINRE_MOUNT -Save -ErrorAction stop | Out-Null
# Export
Write-Output "$(Get-TS): Exporting image to $WORKING_PATH\winre2.wim"
Export-WindowsImage -SourceImagePath $WORKING_PATH"\winre.wim" -SourceIndex 1 -DestinationImagePath $WORKING_PATH"\winre2.wim" -ErrorAction stop | Out-Null
Move-Item -Path $WORKING_PATH"\winre2.wim" -Destination $WORKING_PATH"\winre.wim" -Force -ErrorAction stop | Out-Null
Move-Item -Path $WORKING_PATH"\install2.wim" -Destination $MEDIA_NEW_PATH"\sources\install.wim" -Force -ErrorAction stop | Out-Null
```
### Update WinPE
@ -459,103 +563,6 @@ Foreach ($IMAGE in $WINPE_IMAGES) {
Move-Item -Path $WORKING_PATH"\boot2.wim" -Destination $MEDIA_NEW_PATH"\sources\boot.wim" -Force -ErrorAction stop | Out-Null
```
### Update the main operating system
For this next phase, there's no need to mount the main operating system, since it was already mounted in the previous scripts. This script starts by applying the servicing stack Dynamic Update. Then, it adds Japanese language support and then the Japanese language features. Unlike the Dynamic Update packages, it uses `Add-WindowsCapability` to add these features. For a full list of such features, and their associated capability name, see [Available Features on Demand](/windows-hardware/manufacture/desktop/features-on-demand-non-language-fod).
Now is the time to enable other Optional Components or add other Features on Demand. If such a feature has an associated cumulative update (for example, .NET), this is the time to apply those. The script then proceeds with applying the latest cumulative update. Finally, the script cleans and exports the image.
You can install Optional Components, along with the .NET feature, offline, but that requires the device to be restarted. This is why the script installs .NET and Optional Components after cleanup and before export.
```powershell
#
# update Main OS
#
# Add servicing stack update (Step 18 from the table)
# Depending on the Windows release that you are updating, there are 2 different approaches for updating the servicing stack
# The first approach is to use the combined cumulative update. This is for Windows releases that are shipping a combined cumulative update that
# includes the servicing stack updates (i.e. SSU + LCU are combined). Windows 11, version 21H2 and Windows 11, version 22H2 are examples. In these
# cases, the servicing stack update is not published separately; the combined cumulative update should be used for this step. However, in hopefully
# rare cases, there may breaking change in the combined cumulative update format, that requires a standalone servicing stack update to be published,
# and installed first before the combined cumulative update can be installed.
# This is the code to handle the rare case that the SSU is published and required for the combined cumulative update
# Write-Output "$(Get-TS): Adding package $SSU_PATH"
# Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $SSU_PATH | Out-Null
# Now, attempt the combined cumulative update. Unlike WinRE and WinPE, we don't need to check for error 0x8007007e
Write-Output "$(Get-TS): Adding package $LCU_PATH"
Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $LCU_PATH | Out-Null
# The second approach for Step 18 is for Windows releases that have not adopted the combined cumulative update
# but instead continue to have a separate servicing stack update published. In this case, we'll install the SSU
# update. This second approach is commented out below.
# Write-Output "$(Get-TS): Adding package $SSU_PATH"
# Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $SSU_PATH | Out-Null
# Optional: Add language to main OS
Write-Output "$(Get-TS): Adding package $OS_LP_PATH"
Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $OS_LP_PATH -ErrorAction stop | Out-Null
# Optional: Add a Features on Demand to the image
Write-Output "$(Get-TS): Adding language FOD: Language.Fonts.Jpan~~~und-JPAN~0.0.1.0"
Add-WindowsCapability -Name "Language.Fonts.$LANG_FONT_CAPABILITY~~~und-$LANG_FONT_CAPABILITY~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD: Language.Basic~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.Basic~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD: Language.OCR~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.OCR~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD: Language.Handwriting~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.Handwriting~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD: Language.TextToSpeech~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.TextToSpeech~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
Write-Output "$(Get-TS): Adding language FOD:Language.Speech~~~$LANG~0.0.1.0"
Add-WindowsCapability -Name "Language.Speech~~~$LANG~0.0.1.0" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
# Note: If I wanted to enable additional Features on Demand, I'd add these here.
# Add latest cumulative update
Write-Output "$(Get-TS): Adding package $LCU_PATH"
Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $LCU_PATH -ErrorAction stop | Out-Null
# Copy our updated recovery image from earlier into the main OS
# Note: If I were updating more than 1 edition, I'd want to copy the same recovery image file
# into each edition to enable single instancing
Copy-Item -Path $WORKING_PATH"\winre.wim" -Destination $MAIN_OS_MOUNT"\windows\system32\recovery\winre.wim" -Force -ErrorAction stop | Out-Null
# Perform image cleanup
Write-Output "$(Get-TS): Performing image cleanup on main OS"
DISM /image:$MAIN_OS_MOUNT /cleanup-image /StartComponentCleanup | Out-Null
#
# Note: If I wanted to enable additional Optional Components, I'd add these here.
# In addition, we'll add .NET 3.5 here as well. Both .NET and Optional Components might require
# the image to be booted, and thus if we tried to cleanup after installation, it would fail.
#
Write-Output "$(Get-TS): Adding NetFX3~~~~"
Add-WindowsCapability -Name "NetFX3~~~~" -Path $MAIN_OS_MOUNT -Source $FOD_PATH -ErrorAction stop | Out-Null
# Add .NET Cumulative Update
Write-Output "$(Get-TS): Adding package $DOTNET_CU_PATH"
Add-WindowsPackage -Path $MAIN_OS_MOUNT -PackagePath $DOTNET_CU_PATH -ErrorAction stop | Out-Null
# Dismount
Dismount-WindowsImage -Path $MAIN_OS_MOUNT -Save -ErrorAction stop | Out-Null
# Export
Write-Output "$(Get-TS): Exporting image to $WORKING_PATH\install2.wim"
Export-WindowsImage -SourceImagePath $MEDIA_NEW_PATH"\sources\install.wim" -SourceIndex 1 -DestinationImagePath $WORKING_PATH"\install2.wim" -ErrorAction stop | Out-Null
Move-Item -Path $WORKING_PATH"\install2.wim" -Destination $MEDIA_NEW_PATH"\sources\install.wim" -Force -ErrorAction stop | Out-Null
```
### Update remaining media files
This part of the script updates the Setup files. It simply copies the individual files in the Setup Dynamic Update package to the new media. This step brings in updated Setup files as needed, along with the latest compatibility database, and replacement component manifests. This script also does a final replacement of setup.exe and boot manager files using the previously saved versions from WinPE.

17
windows/deployment/update/servicing-stack-updates.md
View File

@ -15,21 +15,22 @@ appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Windows Server </a>
ms.date: 12/31/2017
ms.date: 12/08/2023
---
# Servicing stack updates
## What is a servicing stack update?
Servicing stack updates provide fixes to the servicing stack, the component that installs Windows updates. Additionally, it contains the "component-based servicing stack" (CBS), which is a key underlying component for several elements of Windows deployment, such as DISM, SFC, changing Windows features or roles, and repairing components. The CBS is a small component that typically doesn't have updates released every month.
Servicing stack updates provide fixes to the servicing stack, the component that installs Windows updates. Additionally, it contains the component-based servicing stack (CBS), which is a key underlying component for several elements of Windows deployment, such as DISM, SFC, changing Windows features or roles, and repairing components. [CBS](https://techcommunity.microsoft.com/t5/ask-the-performance-team/understanding-component-based-servicing/ba-p/373012) is a small component that typically doesn't have updates released every month.
## Why should servicing stack updates be installed and kept up to date?
Servicing stack updates improve the reliability of the update process to mitigate potential issues while installing the latest quality updates and feature updates. If you don't install the latest servicing stack update, there's a risk that your device can't be updated with the latest Microsoft security fixes.
Servicing stack updates improve the reliability of the update process to mitigate potential issues while installing the latest quality updates and feature updates. If you don't have the latest servicing stack update installed, there's a risk that your device can't be updated with the latest Microsoft security fixes.
## When are they released?
Servicing stack update are released depending on new issues or vulnerabilities. In rare occasions a servicing stack update may need to be released on demand to address an issue impacting systems installing the monthly security update. Starting in November 2018 new servicing stack updates will be classified as "Security" with a severity rating of "Critical."
Servicing stack update are released depending on new issues or vulnerabilities. In rare occasions, a servicing stack update might need to be released out of band to address an issue impacting systems installing the monthly security update. New servicing stack updates are classified as `Security` with a severity rating of `Critical`.
## What's the difference between a servicing stack update and a cumulative update?
@ -38,14 +39,14 @@ Both Windows client and Windows Server use the cumulative update mechanism, in w
Servicing stack updates improve the reliability of the update process to mitigate potential issues while installing the latest monthly security update release and feature updates. If you don't install the latest servicing stack update, there's a risk that your device can't be updated with the latest Microsoft security fixes.
Microsoft publishes all cumulative updates and SSUs for Windows 10, version 2004 and later together as one cumulative monthly update to the normal release category in WSUS.
Microsoft publishes all cumulative updates and servicing stack updates for Windows 10, version 2004 and later together as one cumulative monthly update to the normal release category in Windows Server Update Services (WSUS).
## Is there any special guidance?
Microsoft recommends you install the latest servicing stack updates for your operating system before installing the latest cumulative update.
Typically, the improvements are reliability and performance improvements that don't require any specific special guidance. If there's any significant impact, it will be present in the release notes.
Most users don't need to install an isolated servicing stack update. In the rare case that you need to install an isolated servicing stack update, Microsoft recommends you install the latest servicing stack updates for your operating system before installing the latest cumulative update.
## Installation notes
* Servicing stack updates contain the full servicing stack; as a result, typically administrators only need to install the latest servicing stack update for the operating system.
@ -56,6 +57,6 @@ Typically, the improvements are reliability and performance improvements that do
## Simplifying on-premises deployment of servicing stack updates
With the Windows Update experience, servicing stack updates and cumulative updates are deployed together to the device. The update stack automatically orchestrates the installation, so both are applied correctly. Starting in February 2021, the cumulative update includes the latest servicing stack updates, to provide a single cumulative update payload to both Windows Server Update Services (WSUS) and Microsoft Catalog. If you use an endpoint management tool backed by WSUS, such as Configuration Manager, you'll only have to select and deploy the monthly cumulative update. The latest servicing stack updates will automatically be applied correctly. Release notes and file information for cumulative updates, including those related to the servicing stack, will be in a single KB article. The combined monthly cumulative update is available on Windows 10, version 2004 and later starting with the 2021 2C release, KB4601382.
With the Windows Update experience, servicing stack updates and cumulative updates are deployed together to the device. The update stack automatically orchestrates the installation, so both are applied correctly. Starting in February 2021, the cumulative update includes the latest servicing stack updates, to provide a single cumulative update payload to both WSUS and the Microsoft Update Catalog. If you use an endpoint management tool backed by WSUS, such as Configuration Manager, you'll only have to select and deploy the monthly cumulative update. The latest servicing stack updates will automatically be applied correctly. Release notes and file information for cumulative updates, including those related to the servicing stack, will be in a single KB article. The combined monthly cumulative update is available on Windows 10, version 2004 and later starting with [KB4601382](https://support.microsoft.com/kb/4601382), released in February of 2021.

8
windows/deployment/update/waas-branchcache.md
View File

@ -9,9 +9,8 @@ ms.author: mstewart
manager: aaroncz
ms.localizationpriority: medium
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 12/31/2017
ms.date: 11/16/2023
---
# Configure BranchCache for Windows client updates
@ -33,7 +32,10 @@ For detailed information about how Distributed Cache mode and Hosted Cache mode
Whether you use BranchCache with Configuration Manager or WSUS, each client that uses BranchCache must be configured to do so. You typically make your configurations through Group Policy. For step-by-step instructions on how to use Group Policy to configure BranchCache for Windows clients, see [Client Configuration](/previous-versions/windows/it-pro/windows-7/dd637820(v=ws.10)) in the [BranchCache Early Adopter's Guide](/previous-versions/windows/it-pro/windows-7/dd637762(v=ws.10)).
In Windows 10, version 1607, the Windows Update Agent uses Delivery Optimization by default, even when the updates are retrieved from WSUS. When using BranchCache with Windows client, set the Delivery Optimization mode to Bypass to allow clients to use the Background Intelligent Transfer Service (BITS) protocol with BranchCache instead. For instructions on how to use BranchCache in Distributed Cache mode with WSUS, see the section WSUS and Configuration Manager with BranchCache in Distributed Cache mode.
In Windows 10, version 1607, the Windows Update Agent uses Delivery Optimization by default, even when the updates are retrieved from WSUS. When using BranchCache with Windows client, set the Delivery Optimization **Download mode** to '100' (Bypass) to allow clients to use the Background Intelligent Transfer Service (BITS) protocol with BranchCache instead. For instructions on how to use BranchCache in Distributed Cache mode with WSUS, see the section WSUS and Configuration Manager with BranchCache in Distributed Cache mode.
> [!Note]
> [Bypass Download mode (100)](../do/waas-delivery-optimization-reference.md#download-mode) is only available in Windows 10 (starting in version 1607) and deprecated in Windows 11. BranchCache isn't supported for content downloaded using Delivery Optimization in Windows 11. <!--8530422-->
## Configure servers for BranchCache

12
windows/deployment/update/waas-configure-wufb.md
View File

@ -16,7 +16,7 @@ appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Windows Server 2022</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Windows Server 2019</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Windows Server 2016</a>
ms.date: 08/22/2023
ms.date: 11/30/2023
---
# Configure Windows Update for Business
@ -210,7 +210,7 @@ Starting with Windows 10, version 1607, you can selectively opt out of receiving
| MDM for Windows 10, version 1607 and later: </br>../Vendor/MSFT/Policy/Config/Update/</br>**ExcludeWUDriversInQualityUpdate** | \Microsoft\PolicyManager\default\Update\ExcludeWUDriversInQualityUpdate |
## Enable optional updates
<!--7991583-->
<!--7991583-->
In addition to the monthly cumulative update, optional updates are available to provide new features and nonsecurity changes. Most optional updates are released on the fourth Tuesday of the month, known as optional nonsecurity preview releases. Optional updates can also include features that are gradually rolled out, known as controlled feature rollouts (CFRs). Installation of optional updates isn't enabled by default for devices that receive updates using Windows Update for Business. However, you can enable optional updates for devices by using the **Enable optional updates** policy.
To keep the timing of updates consistent, the **Enable optional updates** policy respects the [deferral period for quality updates](#configure-when-devices-receive-quality-updates). This policy allows you to choose if devices should receive CFRs in addition to the optional nonsecurity preview releases, or if the end-user can make the decision to install optional updates. This policy can change the behavior of the **Get the latest updates as soon as they're available** option in **Settings** > **Update & security** > ***Windows Update** > **Advanced options**.
@ -243,8 +243,8 @@ The following options are available for the policy:
| Policy | Sets registry key under HKLM\Software |
| --- | --- |
| GPO for Windows 11, version 22H2 with [KB5029351](https://support.microsoft.com/help/5029351) and later: </br>Computer Configuration > Administrative Templates > Windows Components > Windows Update > Manage updates offered from Windows Update > **Enable optional updates**| \Policies\Microsoft\Windows\WindowsUpdate\AllowOptionalContent |
| MDM for Windows 11, version 22H2 with [KB5029351](https://support.microsoft.com/help/5029351) and later: </br>./Device/Vendor/MSFT/Policy/Config/Update/</br>**[AllowOptionalContent](/windows/client-management/mdm/policy-csp-update?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#allowoptionalcontent)** | \Policies\Microsoft\Windows\WindowsUpdate\AllowOptionalContent |
| **GPO applies to**: <br/> <ul><li> Windows 11, version 22H2 with [KB5029351](https://support.microsoft.com/help/5029351), and later versions </li><li> Windows 10, version 22H2 with [KB5032278](https://support.microsoft.com/help/5032278), or a later cumulative update installed <!--8503602--> </li></ul> </br>**GPO location**: Computer Configuration > Administrative Templates > Windows Components > Windows Update > Manage updates offered from Windows Update > **Enable optional updates**| \Policies\Microsoft\Windows\WindowsUpdate\AllowOptionalContent |
| **MDM applies to**: <br/> <ul><li> Windows 11, version 22H2 with [KB5029351](https://support.microsoft.com/help/5029351) and later versions </li><li> Windows 10, version 22H2 with [KB5032278](https://support.microsoft.com/help/5032278), or a later cumulative update installed <!--8503602--></li></ul> </br>**MDM location**: ./Device/Vendor/MSFT/Policy/Config/Update/</br>**[AllowOptionalContent](/windows/client-management/mdm/policy-csp-update?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#allowoptionalcontent)** | \Policies\Microsoft\Windows\WindowsUpdate\AllowOptionalContent |
## Enable features that are behind temporary enterprise feature control
<!--6544872-->
@ -269,7 +269,7 @@ The following are quick-reference tables of the supported policy values for Wind
| GPO Key | Key type | Value |
| --- | --- | --- |
| AllowOptionalContent</br> </br>*Added in Windows 11, version 22H2*| REG_DWORD | 1: Automatically receive optional updates (including CFRs)</br> 2: Automatically receive optional updates </br> 3: Users can select which optional updates to receive </br> Other value or absent: Don't receive optional updates|
| AllowOptionalContent</br> </br>*Added in*: <br/> <ul><li> Windows 11, version 22H2 with [KB5029351](https://support.microsoft.com/help/5029351) and later </li><li> Windows 10, version 22H2 with [KB5032278](https://support.microsoft.com/help/5032278), or a later cumulative update installed </li></ul> </br>| REG_DWORD | 1: Automatically receive optional updates (including CFRs)</br> 2: Automatically receive optional updates </br> 3: Users can select which optional updates to receive </br> Other value or absent: Don't receive optional updates|
| AllowTemporaryEnterpriseFeatureControl </br> </br>*Added in Windows 11, version 22H2*| REG_DWORD | 1: Allowed. All features in the latest monthly cumulative update are enabled.</br> Other value or absent: Features that are shipped turned off by default will remain off |
| BranchReadinessLevel | REG_DWORD | 2: Systems take feature updates for the Windows Insider build - Fast </br> 4: Systems take feature updates for the Windows Insider build - Slow </br> 8: Systems take feature updates for the Release Windows Insider build </br></br> Other value or absent: Receive all applicable updates |
| DeferFeatureUpdates | REG_DWORD | 1: Defer feature updates</br>Other value or absent: Don't defer feature updates |
@ -285,7 +285,7 @@ The following are quick-reference tables of the supported policy values for Wind
| MDM Key | Key type | Value |
| --- | --- | --- |
| AllowOptionalContent </br> </br>*Added in Windows 11, version 22H2*| REG_DWORD | 1: Automatically receive optional updates (including CFRs)</br> 2: Automatically receive optional updates </br> 3: Users can select which optional updates to receive </br> Other value or absent: Don't receive optional updates|
| AllowOptionalContent </br> </br>*Added in*: <br/> <ul><li> Windows 11, version 22H2 with [KB5029351](https://support.microsoft.com/help/5029351) and later </li><li> Windows 10, version 22H2 with [KB5032278](https://support.microsoft.com/help/5032278), or a later cumulative update installed </li></ul> </br>| REG_DWORD | 1: Automatically receive optional updates (including CFRs)</br> 2: Automatically receive optional updates </br> 3: Users can select which optional updates to receive </br> Other value or absent: Don't receive optional updates|
| AllowTemporaryEnterpriseFeatureControl </br> </br>*Added in Windows 11, version 22H2*| REG_DWORD | 1: Allowed. All features in the latest monthly cumulative update are enabled.</br> Other value or absent: Features that are shipped turned off by default will remain off |
| BranchReadinessLevel | REG_DWORD |2: Systems take feature updates for the Windows Insider build - Fast </br> 4: Systems take feature updates for the Windows Insider build - Slow </br> 8: Systems take feature updates for the Release Windows Insider build </br>32: Systems take feature updates from General Availability Channel </br>Note: Other value or absent: Receive all applicable updates |
| DeferFeatureUpdatesPeriodinDays | REG_DWORD | 0-365: Defer feature updates by given days |

75
windows/deployment/update/waas-manage-updates-wufb.md
View File

@ -13,66 +13,70 @@ ms.localizationpriority: medium
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 12/31/2017
ms.date: 11/07/2023
---
# What is Windows Update for Business?
> **Looking for consumer information?** See [Windows Update: FAQ](https://support.microsoft.com/help/12373/windows-update-faq)
> **Looking for consumer information?** See [Windows Update: FAQ](https://support.microsoft.com/help/12373/windows-update-faq)
Windows Update for Business is a free service that is available for the following editions of Windows 10 and Windows 11:
- Pro, including Pro for Workstations
- Education
- Enterprise, including Enterprise LTSC, IoT Enterprise, and IoT Enterprise LTSC
Windows Update for Business enables IT administrators to keep the Windows client devices in their organization always up to date with the latest security defenses and Windows features by directly connecting these systems to Windows Update service. You can use Group Policy or Mobile Device Management (MDM) solutions such as Microsoft Intune to configure the Windows Update for Business settings that control how and when devices are updated.
Windows Update for Business enables IT administrators to keep their organization's Windows client devices always up to date with the latest security updates and Windows features by directly connecting these systems to the Windows Update service. You can use Group Policy or Mobile Device Management (MDM) solutions, such as Microsoft Intune, to configure the Windows Update for Business settings that control how and when devices are updated.
Specifically, Windows Update for Business lets you control update offerings and experiences to allow for reliability and performance testing on a subset of devices before deploying updates across the organization. It also provides a positive update experience for people in your organization.
## What can I do with Windows Update for Business?
Windows Update for Business enables commercial customers to manage which Windows Updates are received when as well as the experience a device has when it receives them.
Windows Update for Business enables commercial customers to manage which Windows Updates are received along with the experience a device has when it receives them.
You can control Windows Update for Business policies by using either Mobile Device Management (MDM) tools such as Microsoft Intune or Group Policy management tools such as local group policy or the Group Policy Management Console (GPMC), as well as various other non-Microsoft management tools. MDMs use Configuration Service Provider (CSP) policies instead of Group Policy. Intune additionally uses Cloud Policies. Not all policies are available in all formats (CSP, Group Policy, or Cloud policy).
You can control Windows Update for Business policies by using either MDM tools or Group Policy management, such as local group policy or the Group Policy Management Console (GPMC), and various other non-Microsoft management tools. MDMs use Configuration Service Provider (CSP) policies instead of Group Policy. Intune additionally uses Cloud Policies. Not all policies are available in all formats (CSP, Group Policy, or Cloud Policy).
### Manage deployment of Windows Updates
### Manage deployment of Windows Updates
By using Windows Update for Business, you can control which types of Windows Updates are offered to devices in your ecosystem, when updates are applied, and deployment to devices in your organization in waves.
By using Windows Update for Business, you can:
- Control the types of Windows Updates are offered to devices in your organization
- Control when updates are applied to the devices
- Deploy updates to devices in your organization in waves
### Manage which updates are offered
Windows Update for Business enables an IT administrator to receive and manage a variety of different types of Windows Updates.
### Manage which updates are offered
Windows Update for Business enables an IT administrator to receive and manage various types of Windows Updates.
## Types of updates managed by Windows Update for Business
Windows Update for Business provides management policies for several types of updates to Windows 10 devices:
- **Feature updates:** Previously referred to as "upgrades," feature updates contain not only security and quality revisions, but also significant feature additions and changes. Feature updates are released as soon as they become available. Feature updates aren't available for LTSC devices.
- **Quality updates:** Quality updates are traditional operating system updates, typically released on the second Tuesday of each month (though they can be released at any time). These include security, critical, and driver updates.
- **Driver updates:** Updates for non-Microsoft drivers that are relevant to your devices. Driver updates are on by default, but you can use Windows Update for Business policies to turn them off if you prefer.
- **Feature updates:** Previously referred to as upgrades, feature updates contain not only security and quality revisions, but also significant feature additions and changes. Feature updates are released as soon as they become available. Feature updates aren't available for LTSC devices.
- **Quality updates:** Quality updates are traditional operating system updates. Typically quality updates are released on the second Tuesday of each month, though they can be released at any time. These include security, critical, and driver updates.
- **Driver updates:** Updates for non-Microsoft drivers that are relevant to your devices. Driver updates are on by default, but you can use Windows Update for Business policies to turn them off if you prefer.
- **Microsoft product updates**: Updates for other Microsoft products, such as versions of Office that are installed by using Windows Installer (MSI). Versions of Office that are installed by using Click-to-Run can't be updated by using Windows Update for Business. Product updates are off by default. You can turn them on by using Windows Update for Business policies.
## Offering
You can control when updates are applied, for example by deferring when an update is installed on a device or by pausing updates for a certain period.
You can control when updates are applied. For example, you can defer when an update is installed on a device or by pausing updates for a certain period.
### Manage when updates are offered
You can defer or pause the installation of updates for a set period of time.
#### Enroll in prerelease updates
The branch readiness level enables administrators to specify which channel of feature updates they want to receive. Today there are branch readiness level options for both prerelease and released updates:
- Windows Insider Canary
- Windows Insider Dev
- Windows Insider Beta
- Windows Insider Preview
- General Availability Channel
- Windows Insider Canary channel
- Windows Insider Dev channel
- Windows Insider Beta channel
- Windows Insider Release Preview channel
#### Defer an update
A Windows Update for Business administrator can defer the installation of both feature and quality updates from deploying to devices within a bounded range of time from when those updates are first made available on the Windows Update service. You can use this deferral to allow time to validate deployments as they're pushed to devices. Deferrals work by allowing you to specify the number of days after an update is released before it's offered to a device. That is, if you set a feature update deferral period of 365 days, the device won't install a feature update that has been released for less than 365 days. To defer feature updates, use the **Select when Preview Builds and feature updates are Received** policy.
An administrator can defer the installation of both feature and quality updates from deploying to devices within a range of time based on when those updates are first made available on the Windows Update service. You can use this deferral to allow time to validate deployments as they're pushed to devices. Deferrals work by allowing you to specify the number of days after an update is released before it's offered to a device. That is, if you set a feature update deferral period of 365 days, the device won't install a feature update that has been released for less than 365 days. To defer feature updates, use the **Select when Preview Builds and feature updates are Received** policy.
|Category |Maximum deferral period |
|---------|---------|
@ -85,13 +89,12 @@ A Windows Update for Business administrator can defer the installation of both f
#### Pause an update
If you discover a problem while deploying a feature or quality update, the IT administrator can pause the update for 35 days from a specified start date to prevent other devices from installing it until the issue is mitigated.
If you pause a feature update, quality updates are still offered to devices to ensure they stay secure. The pause period for both feature and quality updates is calculated from a start date that you set.
If you discover a problem while deploying a feature or quality update, you can pause the update for 35 days from a specified start date to prevent other devices from installing it until the issue is mitigated. If you pause a feature update, quality updates are still offered to devices to ensure they stay secure. The pause period for both feature and quality updates is calculated from a start date that you set.
To pause feature updates, use the **Select when Preview Builds and feature updates are Received** policy and to pause quality updates use the **Select when Quality Updates are Received** policy. For more information, see [Pause feature updates](waas-configure-wufb.md#pause-feature-updates) and [Pause quality updates](waas-configure-wufb.md#pause-quality-updates).
Built-in benefits:
When updating from Windows Update, you get the added benefits of built-in compatibility checks to prevent against a poor update experience for your device as well as a check to prevent repeated rollbacks.
When updating from Windows Update, you get the added benefits of built-in compatibility checks to prevent against a poor update experience for your device and a check to prevent repeated rollbacks.
### Recommendations
@ -104,28 +107,38 @@ For the best experience with Windows Update, follow these guidelines:
### Manage the end-user experience when receiving Windows Updates
Windows Update for Business provides controls to help meet your organization's security standards as well as provide a great end-user experience. We do this by enabling you to set automatic updates at times that work well for people in your organization and set deadlines for quality and feature updates. Because Windows Update includes built-in intelligence, it's better to use fewer controls to manage the user experience.
Windows Update for Business provides controls to help meet your organization's security standards and provide a great end-user experience. We do this by enabling you to set automatic updates at times that work well for people in your organization and set deadlines for quality and feature updates. Because Windows Update includes built-in intelligence, it's better to use fewer controls to manage the user experience.
#### Recommended experience settings
Features like the smart busy check (which ensure updates don't happen when a user is signed in) and active hours help provide the best experience for end users while keeping devices more secure and up to date. Follow these steps to take advantage of these features:
1. Automatically download, install, and restart (default if no restart policies are set up or enabled).
2. Use the default notifications.
3. Set update deadlines.
1. Use the default notifications.
1. Set update deadlines.
##### Setting deadlines
##### Setting deadlines
A compliance deadline policy (released in June 2019) enables you to set separate deadlines and grace periods for feature and quality updates.
A compliance deadline policy enables you to set separate deadlines and grace periods for feature and quality updates.
This policy enables you to specify the number of days from an update's publication date that it must be installed on the device. The policy also includes a configurable grace period that specifies the number of days from when the update is installed on the device until the device is forced to restart. This approach is useful in a vacation scenario as it allows, for example, users who have been away to have a bit of time before being forced to restart their devices when they return from vacation.
#### Update Baseline
> [!NOTE]
> The Update Baseline toolkit is available only for Group Policy. Update Baseline does not affect your offering policies, whether you're using deferrals or target version to manage which updates are offered to your devices when. Update Baseline is not currently supported for Windows 11.
The large number of different policies offered can be overwhelming. Update Baseline provides a clear list of recommended Windows update policy settings for IT administrators who want the best user experience while also meeting their update compliance goals. The Update Baseline for Windows 10 includes policy settings recommendations covering deadline configuration, restart behavior, power policies, and more.
The Update Baseline toolkit makes it easy by providing a single command for IT Admins to apply the Update Baseline to devices. You can get the Update Baseline toolkit from the [Download Center](https://www.microsoft.com/download/details.aspx?id=101056).
>[!NOTE]
>The Update Baseline toolkit is available only for Group Policy. Update Baseline does not affect your offering policies, whether you’re using deferrals or target version to manage which updates are offered to your devices when. Update Baseline is not currently supported for Windows 11.
## Other Windows Update for Business services
The following services are part of the Windows Update for Business product family:
- [Windows Update for Business reports](wufb-reports-overview.md) is a cloud-based solution that provides information about your Microsoft Entra joined devices' compliance with Windows updates. Windows Update for Business reports is offered through the Azure portal. Windows Update for Business reports helps you:
- Monitor security, quality, driver, and feature updates for Windows 11 and Windows 10 devices
- Report on devices with update compliance issues
- Analyze and display your data in multiple ways
- The [Windows Update for Business deployment service](deployment-service-overview.md) is a cloud service designed to work with your existing Windows Update for Business policies and Windows Update for Business reports. The deployment service provides additional control over the approval, scheduling, and safeguarding of updates delivered from Windows Update to managed devices.

52
windows/deployment/update/waas-wufb-csp-mdm.md
View File

@ -11,7 +11,7 @@ ms.localizationpriority: medium
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 10/10/2023
ms.date: 01/18/2024
---
# Walkthrough: Use CSPs and MDMs to configure Windows Update for Business
@ -47,19 +47,19 @@ Drivers are automatically enabled because they're beneficial to device systems.
### Set when devices receive feature and quality updates
#### I want to receive pre-release versions of the next feature update
#### I want to receive prerelease versions of the next feature update
1. Ensure that you're enrolled in the Windows Insider Program for Business. This is a free program available to commercial customers to aid them in their validation of feature updates before they're released. Joining the program enables you to receive updates prior to their release as well as receive emails and content related to what is coming in the next updates.
1. Ensure that you're enrolled in the Windows Insider Program for Business. Windows Insider is a free program available to commercial customers to aid them in their validation of feature updates before they're released. Joining the program enables you to receive updates prior to their release as well as receive emails and content related to what is coming in the next updates.
1. For any of test devices you want to install pre-release builds, use [Update/ManagePreviewBuilds](/windows/client-management/mdm/policy-csp-update#update-managepreviewbuilds). Set this to **Enable preview builds**.
1. For any of test devices you want to install prerelease builds, use [Update/ManagePreviewBuilds](/windows/client-management/mdm/policy-csp-update#update-managepreviewbuilds). Set the option to **Enable preview builds**.
1. Use [Update/BranchReadinessLevel](/windows/client-management/mdm/policy-csp-update#update-branchreadinesslevel) and select one of the preview Builds. Windows Insider Program Slow is the recommended channel for commercial customers who are using pre-release builds for validation.
1. Use [Update/BranchReadinessLevel](/windows/client-management/mdm/policy-csp-update#update-branchreadinesslevel) and select one of the preview Builds. Windows Insider Program Slow is the recommended channel for commercial customers who are using prerelease builds for validation.
1. Additionally, you can defer pre-release feature updates the same way as released updates, by setting a deferral period up to 14 days by using [Update/DeferFeatureUpdatesPeriodInDays](/windows/client-management/mdm/policy-csp-update#update-deferfeatureupdatesperiodindays). If you're testing with Windows Insider Program Slow builds, we recommend that you receive the preview updates to your IT department on day 0, when the update is released, and then have a 7-10 day deferral before rolling out to your group of testers. This ensures that if a problem is discovered, you can pause the rollout of the preview update before it reaches your tests.
1. Additionally, you can defer prerelease feature updates the same way as released updates, by setting a deferral period up to 14 days by using [Update/DeferFeatureUpdatesPeriodInDays](/windows/client-management/mdm/policy-csp-update#update-deferfeatureupdatesperiodindays). If you're testing with Windows Insider Program Slow builds, we recommend that you receive the preview updates to your IT department on day 0, when the update is released, and then have a 7-10 day deferral before rolling out to your group of testers. This schedule helps ensure that if a problem is discovered, you can pause the rollout of the preview update before it reaches your tests.
#### I want to manage which released feature update my devices receive
A Windows Update for Business administrator can defer or pause updates. You can defer feature updates for up to 365 days and defer quality updates for up to 30 days. Deferring simply means that you won't receive the update until it has been released for at least the number of deferral days you specified (offer date = release date + deferral date). You can pause feature or quality updates for up to 35 days from a given start date that you specify.
A Windows Update for Business administrator can defer or pause updates. You can defer feature updates for up to 365 days and defer quality updates for up to 30 days. Deferring simply means that you don't receive the update until it has been released for at least the number of deferral days you specified (offer date = release date + deferral date). You can pause feature or quality updates for up to 35 days from a given start date that you specify.
- To defer a feature update: [Update/DeferFeatureUpdatesPeriodInDays](/windows/client-management/mdm/policy-csp-update#update-deferfeatureupdatesperiodindays)
- To pause a feature update: [Update/PauseFeatureUpdatesStartTime](/windows/client-management/mdm/policy-csp-update#update-pausefeatureupdatesstarttime)
@ -72,7 +72,7 @@ In this example, there are three rings for quality updates. The first ring ("pil
![illustration of devices divided into three rings.](images/waas-wufb-3-rings.png)
When the quality update is released, it is offered to devices in the pilot ring the next time they scan for updates.
When the quality update is released, it's offered to devices in the pilot ring the next time they scan for updates.
##### Five days later
The devices in the fast ring are offered the quality update the next time they scan for updates.
@ -80,11 +80,11 @@ The devices in the fast ring are offered the quality update the next time they s
![illustration of devices with fast ring deployed.](images/waas-wufb-fast-ring.png)
##### Ten days later
Ten days after the quality update is released, it is offered to the devices in the slow ring the next time they scan for updates.
Ten days after the quality update is released, it's offered to the devices in the slow ring the next time they scan for updates.
![illustration of devices with slow ring deployed.](images/waas-wufb-slow-ring.png)
If no problems occur, all of the devices that scan for updates will be offered the quality update within ten days of its release, in three waves.
If no problems occur, all of the devices that scan for updates are offered the quality update within ten days of its release, in three waves.
##### What if a problem occurs with the update?
@ -109,13 +109,13 @@ If you need a device to stay on a version beyond the point when deferrals on the
#### I want to manage when devices download, install, and restart after updates
We recommended that you allow to update automatically--this is the default behavior. If you don't set an automatic update policy, the device will attempt to download, install, and restart at the best times for the user by using built-in intelligence such as intelligent active hours and smart busy check.
We recommended that you allow to update automatically, which is the default behavior. If you don't set an automatic update policy, the device attempts to download, install, and restart at the best times for the user by using built-in intelligence such as intelligent active hours and smart busy check.
For more granular control, you can set the maximum period of active hours the user can set with [Update/ActiveHoursMaxRange](/windows/client-management/mdm/policy-csp-update#update-activehoursmaxrange). You could also set specific start and end times for active ours with [Update/ActiveHoursEnd](/windows/client-management/mdm/policy-csp-update#update-activehoursend) and [Update/ActiveHoursStart](/windows/client-management/mdm/policy-csp-update#update-activehoursstart).
It's best to refrain from setting the active hours policy because it's enabled by default when automatic updates are not disabled and provides a better experience when users can set their own active hours.
It's best to refrain from setting the active hours policy because it's enabled by default when automatic updates aren't disabled and provides a better experience when users can set their own active hours.
To update outside of the active hours, use [Update/AllowAutoUpdate](/windows/client-management/mdm/policy-csp-update#update-allowautoupdate) with Option 2 (which is the default setting). For even more granular control, consider using automatic updates to schedule the install time, day, or week. To do this, use Option 3, and then set the following policies as appropriate for your plan:
To update outside of the active hours, use [Update/AllowAutoUpdate](/windows/client-management/mdm/policy-csp-update#update-allowautoupdate) with Option 2 (which is the default setting). For even more granular control, consider using automatic updates to schedule the install time, day, or week. To use a schedule, use Option 3, and then set the following policies as appropriate for your plan:
- [Update/ScheduledInstallDay](/windows/client-management/mdm/policy-csp-update#update-scheduledinstallday)
- [Update/ScheduledInstallEveryWeek](/windows/client-management/mdm/policy-csp-update#update-scheduledinstalleveryweek)
@ -132,7 +132,7 @@ If you don't want to allow any automatic updates prior to the deadline, set [Upd
#### I want to keep devices secure and compliant with update deadlines
We recommend that you use set specific deadlines for feature and quality updates to ensure that devices stay secure on Windows 10, version 1709 and later. This works by enabling you to specify the number of days that can elapse after an update is offered to a device before it must be installed. Also you can set the number of days that can elapse after a pending restart before the user is forced to restart. Use these settings:
We recommend that you use set specific deadlines for feature and quality updates to ensure that devices stay secure on Windows 10, version 1709 and later. Deadlines work by enabling you to specify the number of days that can elapse after an update is offered to a device before it must be installed. Also you can set the number of days that can elapse after a pending restart before the user is forced to restart. Use these settings:
- [Update/ConfigureDeadlineForFeatureUpdates](/windows/client-management/mdm/policy-csp-update#update-configuredeadlineforfeatureupdates)
- [Update/ConfigureDeadlineForQualityUpdates ](/windows/client-management/mdm/policy-csp-update#update-configuredeadlineforqualityupdates)
@ -140,7 +140,7 @@ We recommend that you use set specific deadlines for feature and quality updates
- [Update/ConfigureDeadlineGracePeriodForFeatureUpdates](/windows/client-management/mdm/policy-csp-update#configuredeadlinegraceperiodforfeatureupdates)
- [Update/ConfigureDeadlineNoAutoReboot](/windows/client-management/mdm/policy-csp-update#update-configuredeadlinenoautoreboot)
These policies also offer an option to opt out of automatic restarts until a deadline is reached by presenting an "engaged restart experience" until the deadline has actually expired. At that point the device will automatically schedule a restart regardless of active hours.
These policies also offer an option to opt out of automatic restarts until a deadline is reached by presenting an "engaged restart experience" until the deadline has actually expired. At that point, the device automatically schedules a restart regardless of active hours.
These notifications are what the user sees depending on the settings you choose:
@ -172,7 +172,7 @@ When **Specify deadlines for automatic updates and restarts** is set (For Window
There are additional settings that affect the notifications.
We recommend that you use the default notifications as they aim to provide the best user experience while adjusting for the compliance policies that you have set. If you do have further needs that aren't met by the default notification settings, you can use the [Update/UpdateNotificationLevel](/windows/client-management/mdm/policy-csp-update#update-updatenotificationlevel) policy with these values:
We recommend that you use the default notifications as they aim to provide the best user experience while adjusting for the compliance policies that you set. If you do have further needs that aren't met by the default notification settings, you can use the [Update/UpdateNotificationLevel](/windows/client-management/mdm/policy-csp-update#update-updatenotificationlevel) policy with these values:
**0** (default) - Use the default Windows Update notifications<br/>
**1** - Turn off all notifications, excluding restart warnings<br/>
@ -181,14 +181,14 @@ We recommend that you use the default notifications as they aim to provide the b
> [!NOTE]
> Option **2** creates a poor experience for personal devices; it's only recommended for kiosk devices where automatic restarts have been disabled.
Still more options are available in [Update/ScheduleRestartWarning](/windows/client-management/mdm/policy-csp-update#update-schedulerestartwarning). This setting allows you to specify the period for auto-restart warning reminder notifications (from 2-24 hours; 4 hours is the default) before the update. You can also specify the period for auto-restart imminent warning notifications with [Update/ScheduleImminentRestartWarning](/windows/client-management/mdm/policy-csp-update#update-scheduleimminentrestartwarning) (15-60 minutes is the default). We recommend using the default notifications.
Still more options are available in [Update/ScheduleRestartWarning](/windows/client-management/mdm/policy-csp-update#update-schedulerestartwarning). This setting allows you to specify the period for auto restart warning reminder notifications (from 2-24 hours; 4 hours is the default) before the update. You can also specify the period for auto restart imminent warning notifications with [Update/ScheduleImminentRestartWarning](/windows/client-management/mdm/policy-csp-update#update-scheduleimminentrestartwarning) (15-60 minutes is the default). We recommend using the default notifications.
#### I want to manage the update settings a user can access
Every Windows device provides users with a variety of controls they can use to manage Windows Updates. They can access these controls by Search to find Windows Updates or by going selecting **Updates and Security** in **Settings**. We provide the ability to disable a variety of these controls that are accessible to users.
Every Windows device provides users with various controls they can use to manage Windows Updates. They can access these controls by Search to find Windows Updates or by going selecting **Updates and Security** in **Settings**. We provide the ability to disable a variety of these controls that are accessible to users.
Users with access to update pause settings can prevent both feature and quality updates for 7 days. You can prevent users from pausing updates through the Windows Update settings page by using [Update/SetDisablePauseUXAccess](/windows/client-management/mdm/policy-csp-update#update-setdisablepauseuxaccess).
When you disable this setting, users will see **Some settings are managed by your organization** and the update pause settings are greyed out.
When you disable this setting, users see **Some settings are managed by your organization** and the update pause settings are greyed out.
If you use Windows Server Update Server (WSUS), you can prevent users from scanning Windows Update. To do this, use [Update/SetDisableUXWUAccess](/windows/client-management/mdm/policy-csp-update#update-setdisableuxwuaccess).
@ -202,6 +202,14 @@ The features that are turned off by default from servicing updates will be enabl
You can enable these features by using [AllowTemporaryEnterpriseFeatureControl](/windows/client-management/mdm/policy-csp-update?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#allowtemporaryenterprisefeaturecontrol). The following options are available:
- **0** (default): Allowed. All features in the latest monthly cumulative update are enabled.
- When the policy is set to **0**, all features that are currently turned off will turn on when the device next reboots
- **1** - Not allowed. Features that are shipped turned off by default will remain off
- **0** (default): Not allowed. Features that are shipped turned off by default will remain off
- **1**: Allowed. All features in the latest monthly cumulative update are enabled.
- When the policy is set to **1**, all features that are currently turned off will turn on when the device next reboots.
#### I want to enable optional updates
<!--7991583-->
*Applies to:*
- Windows 11, version 22H2 with [KB5029351](https://support.microsoft.com/help/5029351) and later <!--7991583-->
- Windows 10, version 22H2 with [KB5032278](https://support.microsoft.com/help/5032278), or a later cumulative update installed <!--8503602-->
In addition to the monthly cumulative update, optional updates are available to provide new features and nonsecurity changes. Most optional updates are released on the fourth Tuesday of the month, known as optional nonsecurity preview releases. Optional updates can also include features that are gradually rolled out, known as controlled feature rollouts (CFRs). Installation of optional updates isn't enabled by default for devices that receive updates using Windows Update for Business. However, you can enable optional updates for devices by using [AllowOptionalContent](/windows/client-management/mdm/policy-csp-update?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#allowoptionalcontent). For more information about optional content, see [Enable optional updates](waas-configure-wufb.md#enable-optional-updates).

6
windows/deployment/update/waas-wufb-group-policy.md
View File

@ -17,7 +17,7 @@ appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Windows Server 2022</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Windows Server 2019</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Windows Server 2016</a>
ms.date: 10/10/2023
ms.date: 11/30/2023
---
# Walkthrough: Use Group Policy to configure Windows Update for Business
@ -202,7 +202,9 @@ If you use Windows Server Update Server (WSUS), you can prevent users from scann
#### I want to enable optional updates
<!--7991583-->
(*Starting in Windows 11, version 22H2 or later*)
*Applies to:*
- Windows 11, version 22H2 with [KB5029351](https://support.microsoft.com/help/5029351) and later <!--7991583-->
- Windows 10, version 22H2 with [KB5032278](https://support.microsoft.com/help/5032278), or a later cumulative update installed <!--8503602-->
In addition to the monthly cumulative update, optional updates are available to provide new features and nonsecurity changes. Most optional updates are released on the fourth Tuesday of the month, known as optional nonsecurity preview releases. Optional updates can also include features that are gradually rolled out, known as controlled feature rollouts (CFRs). Installation of optional updates isn't enabled by default for devices that receive updates using Windows Update for Business. However, you can enable optional updates for devices by using the **Computer Configuration > Administrative Templates > Windows Components > Windows Update > Manage updates offered from Windows Update > Enable optional updates** policy.

51
windows/deployment/update/windows-update-logs.md
View File

@ -13,7 +13,7 @@ ms.collection:
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 12/31/2017
ms.date: 12/08/2023
---
# Windows Update log files
@ -24,18 +24,20 @@ The following table describes the log files created by Windows Update.
|Log file|Location|Description|When to use |
|-|-|-|-|
|windowsupdate.log|C:\Windows\Logs\WindowsUpdate|Starting in Windows 8.1 and continuing in Windows 10, Windows Update client uses Event Tracing for Windows (ETW) to generate diagnostic logs.|If you receive an error message when you run Windows Update, you can use the information that is included in the Windowsupdate.log log file to troubleshoot the issue.|
|UpdateSessionOrchestration.etl|C:\ProgramData\USOShared\Logs|Starting Windows 10, the Update Orchestrator is responsible for sequence of downloading and installing various update types from Windows Update. And the events are logged to these .etl files.|When you see that the updates are available but download is not getting triggered. <br>When Updates are downloaded but installation is not triggered.<br>When Updates are installed but reboot is not triggered. |
|windowsupdate.log|C:\Windows\Logs\WindowsUpdate|Starting in Windows 8.1 and continuing in Windows 10, Windows Update client uses Event Tracing for Windows (ETW) to generate diagnostic logs.|If you receive an error message when you run Windows Update, you can use the information included in the Windowsupdate.log log file to troubleshoot the issue.|
|UpdateSessionOrchestration.etl|C:\ProgramData\USOShared\Logs|Starting Windows 10, the Update Orchestrator Service is responsible for sequence of downloading and installing various update types from Windows Update. And the events are logged to these .etl files.|<ul> <li>When you see that the updates are available but download isn't getting triggered. </li><li>When updates are downloaded but installation isn't triggered. </li> <li>When updates are installed but reboot isn't triggered. </li></ul> |
|NotificationUxBroker.etl|C:\ProgramData\USOShared\Logs|Starting Windows 10, the notification toast or the banner is triggered by NotificationUxBroker.exe. |When you want to check whether the notification was triggered or not. |
|CBS.log|%systemroot%\Logs\CBS|This log provides insight on the update installation part in the servicing stack.|To troubleshoot the issues related to Windows Update installation.|
## Generating WindowsUpdate.log
## Generating WindowsUpdate.log
To merge and convert Windows Update trace files (.etl files) into a single readable WindowsUpdate.log file, see [Get-WindowsUpdateLog](/powershell/module/windowsupdate/get-windowsupdatelog?preserve-view=tru&view=win10-ps).
>[!NOTE]
>When you run the **Get-WindowsUpdateLog** cmdlet, an copy of WindowsUpdate.log file is created as a static log file. It does not update as the old WindowsUpdate.log unless you run **Get-WindowsUpdateLog** again.
### Windows Update log components
## Windows Update log components
The Windows Update engine has different component names. The following are some of the most common components that appear in the WindowsUpdate.log file:
- AGENT- Windows Update agent
@ -54,7 +56,7 @@ The Windows Update engine has different component names. The following are some
- PT- Synchronizes updates information to the local datastore
- REPORT- Collects reporting information
- SERVICE- Startup/shutdown of the Automatic Updates service
- SETUP- Installs new versions of the Windows Update client when it is available
- SETUP- Installs new versions of the Windows Update client when it's available
- SHUTDWN- Install at shutdown feature
- WUREDIR- The Windows Update redirector files
- WUWEB- The Windows Update ActiveX control
@ -68,7 +70,7 @@ The Windows Update engine has different component names. The following are some
>[!NOTE]
>Many component log messages are invaluable if you are looking for problems in that specific area. However, they can be useless if you don't filter to exclude irrelevant components so that you can focus on what's important.
### Windows Update log structure
## Windows Update log structure
The Windows update log structure is separated into four main identities:
- Time Stamps
@ -82,7 +84,7 @@ The Windows update log structure is separated into four main identities:
The WindowsUpdate.log structure is discussed in the following sections.
#### Time stamps
### Time stamps
The time stamp indicates the time at which the logging occurs.
- Messages are usually in chronological order, but there may be exceptions.
- A pause during a sync can indicate a network problem, even if the scan succeeds.
@ -90,15 +92,15 @@ The time stamp indicates the time at which the logging occurs.
![Windows Update time stamps.](images/update-time-log.png)
#### Process ID and thread ID
### Process ID and thread ID
The Process IDs and Thread IDs are random, and they can vary from log to log and even from service session to service session within the same log.
- The first four hex digits are the process ID.
- The next four hex digits are the thread ID.
- The first four digits, in hex, are the process ID.
- The next four digits, in hex, are the thread ID.
- Each component, such as the USO, Windows Update engine, COM API callers, and Windows Update installer handlers, has its own process ID.
![Windows Update process and thread IDs.](images/update-process-id.png)
#### Component name
### Component name
Search for and identify the components that are associated with the IDs. Different parts of the Windows Update engine have different component names. Some of them are as follows:
- ProtocolTalker - Client-server sync
@ -111,31 +113,36 @@ Search for and identify the components that are associated with the IDs. Differe
![Windows Update component name.](images/update-component-name.png)
#### Update identifiers
### Update identifiers
The following items are update identifiers:
#### Update ID and revision number
##### Update ID and revision number
There are different identifiers for the same update in different contexts. It's important to know the identifier schemes.
- Update ID: A GUID (indicated in the previous screenshot) that's assigned to a given update at publication time
- Update ID: A GUID (indicated in the previous screenshot) assigned to a given update at publication time
- Revision number: A number incremented every time that a given update (that has a given update ID) is modified and republished on a service
- Revision numbers are reused from one update to another (not a unique identifier).
- The update ID and revision number are often shown together as "{GUID}.revision."
![Windows Update update identifiers.](images/update-update-id.png)
##### Revision ID
- A Revision ID (don't confuse this value with "revision number") is a serial number that's issued when an update is initially published or revised on a given service.
- An existing update that's revised keeps the same update ID (GUID), has its revision number incremented (for example, from 100 to 101), but gets a new revision ID that is not related to the previous ID.
#### Revision ID
- A Revision ID (don't confuse this value with "revision number") is a serial number issued when an update is initially published or revised on a given service.
- An existing update that is revised keeps the same update ID (GUID), has its revision number incremented (for example, from 100 to 101), but gets a new revision ID that isn't related to the previous ID.
- Revision IDs are unique on a given update source, but not across multiple sources.
- The same update revision might have different revision IDs on Windows Update and WSUS.
- The same revision ID might represent different updates on Windows Update and WSUS.
##### Local ID
- Local ID is a serial number issued when an update is received from a service by a given Windows Update client
#### Local ID
- Local ID is a serial number issued by a given Windows Update client when an update is received from a service.
- Typically seen in debug logs, especially involving the local cache for update info (Datastore)
- Different client PCs will assign different Local IDs to the same update
- Different client PCs assign different Local IDs to the same update
- You can find the local IDs that a client is using by getting the client's %WINDIR%\SoftwareDistribution\Datastore\Datastore.edb file
##### Inconsistent terminology
#### Inconsistent terminology
- Sometimes the logs use terms inconsistently. For example, the InstalledNonLeafUpdateIDs list actually contains revision IDs, not update IDs.
- Recognize IDs by form and context:

49
windows/deployment/update/wufb-reports-configuration-manual.md
View File

@ -4,7 +4,7 @@ titleSuffix: Windows Update for Business reports
description: How to manually configure devices for Windows Update for Business reports using a PowerShell script.
ms.prod: windows-client
ms.technology: itpro-updates
ms.topic: conceptual
ms.topic: how-to
author: mestew
ms.author: mstewart
manager: aaroncz
@ -12,61 +12,60 @@ ms.localizationpriority: medium
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 11/15/2022
ms.date: 12/15/2023
---
# Manually configuring devices for Windows Update for Business reports
# Manually configure devices for Windows Update for Business reports
<!--37063317, 30141258, 37063041-->
There are a number of requirements to consider when manually configuring devices for Windows Update for Business reports. These requirements can potentially change with newer versions of Windows client. The [Windows Update for Business reports configuration script](wufb-reports-configuration-script.md) will be updated when any configuration requirements change so only a redeployment of the script will be required.
There are many requirements to consider when manually configuring devices for Windows Update for Business reports. These requirements can potentially change with later versions of Windows client. When any configuration requirements change, we'll update the [Windows Update for Business reports configuration script](wufb-reports-configuration-script.md). If that happens, you only need to redeploy the script.
The requirements are separated into different categories:
1. Ensuring the [**required policies**](#required-policies) for Windows Update for Business reports are correctly configured.
2. Devices in every network topography must send data to the [**required endpoints**](#required-endpoints) for Windows Update for Business reports. For example, devices in both main and satellite offices, which might have different network configurations, must be able to reach the endpoints.
3. Ensure [**Required Windows services**](#required-services) are running or are scheduled to run. It's recommended all Microsoft and Windows services are set to their out-of-box defaults to ensure proper functionality.
3. Ensure [**Required Windows services**](#required-services) are running or are scheduled to run. For proper functionality, leave Windows services set to their out-of-box default configurations.
## Required policies
Windows Update for Business reports has a number of policies that must be appropriately configured in order for devices to be processed by Microsoft and visible in Windows Update for Business reports. Thee policies are listed below, separated by whether the policies will be configured via [Mobile Device Management](/windows/client-management/mdm/) (MDM) or Group Policy. For both tables:
The Windows Update for Business reports service has several policies that you need to configure appropriately. These policies allow Microsoft to process your devices and show them in Windows Update for Business reports. The policies are listed in the following subsections, separated by [mobile device management](/windows/client-management/mdm/) (MDM) or group policy.
- **Policy** corresponds to the location and name of the policy.
- **Value** Indicates what value the policy must be set to. Windows Update for Business reports requires *at least* Basic (or Required) diagnostic data, but can function off Enhanced or Full (or Optional).
- **Function** details why the policy is required and what function it serves for Windows Update for Business reports. It will also detail a minimum version the policy is required, if any.
The following definitions apply for both tables:
### Mobile Device Management policies
- **Policy**: The location and name of the policy.
- **Value**: Set the policy to this value. Windows Update for Business reports requires at least *Required* (previously *Basic*) diagnostic data, but can function with *Enhanced* or *Optional* (previously *Full*).
- **Function**: Details for why the policy is required and what function it serves for Windows Update for Business reports. It also details a minimum version the policy requires, if any.
Each MDM Policy links to its documentation in the configuration service provider (CSP) hierarchy, providing its exact location in the hierarchy and more details.
### MDM policies
| Policy | Data type | Value | Function | Required or recommended|
Each MDM policy links to more detailed documentation in the configuration service provider (CSP) hierarchy.
| Policy | Data type | Value | Function | Required or recommended |
|---|---|---|---|---|
|**System/**[**AllowTelemetry**](/windows/client-management/mdm/policy-csp-system#system-allowtelemetry) |Integer | 1 - Basic |Configures the maximum allowed diagnostic data to be sent to Microsoft. Individual users can still set this value lower than what the policy defines. For more information, see the following policy. | Required |
|**System/**[**ConfigureTelemetryOptInSettingsUx**](/windows/client-management/mdm/policy-csp-system#system-configuretelemetryoptinsettingsux) |Integer |1 - Disable Telemetry opt-in Settings | Determines whether users of the device can adjust diagnostic data to levels lower than the level defined by AllowTelemetry. We recommend that you disable this policy or the effective diagnostic data level on devices might not be sufficient. | Recommended |
|**System/**[**AllowDeviceNameInDiagnosticData**](/windows/client-management/mdm/policy-csp-system#system-allowdevicenameindiagnosticdata) |Integer | 1 - Allowed | Allows device name to be sent for Windows Diagnostic Data. If this policy is Not Configured or set to 0 (Disabled), Device Name won't be sent and won't be visible in Windows Update for Business reports, showing `#` instead. | Recommended |
| **System/**[**ConfigureTelemetryOptInChangeNotification**](/windows/client-management/mdm/policy-csp-system#configuretelemetryoptinchangenotification) | Integer | 1 - Disabled | Disables user notifications that appear for changes to the diagnostic data level. | Recommended |
| **System/**[**AllowTelemetry**](/windows/client-management/mdm/policy-csp-system#allowtelemetry) | Integer | `1`: Basic (Required) | Configures the device to send the minimum required diagnostic data. | Required |
| **System/**[**ConfigureTelemetryOptInSettingsUx**](/windows/client-management/mdm/policy-csp-system#configuretelemetryoptinsettingsux) | Integer | `1`: Disable diagnostic data opt-in settings | Determines whether users of the device can adjust diagnostic data to levels lower than you define by the *AllowTelemetry* policy. Set the recommended value to disable opt-in settings, or users can change the effective diagnostic data level that might not be sufficient. | Recommended |
| **System/**[**AllowDeviceNameInDiagnosticData**](/windows/client-management/mdm/policy-csp-system#allowdevicenameindiagnosticdata) | Integer | `1`: Allowed | Allows the device to send its name with Windows diagnostic data. If you don't configure this policy or set it to `0`: Disabled, then the data doesn't include the device name. If the data doesn't include the device name, you can't see the device in Windows Update for Business reports. In this instance, the reports show `#` instead. | Recommended |
| **System/**[**ConfigureTelemetryOptInChangeNotification**](/windows/client-management/mdm/policy-csp-system#configuretelemetryoptinchangenotification) | Integer | `1`: Disabled | Disables user notifications that appear for changes to the diagnostic data level. | Recommended |
### Group policies
All Group policies that need to be configured for Windows Update for Business reports are under **Computer Configuration>Administrative Templates>Windows Components\Data Collection and Preview Builds**. All of these policies must be in the *Enabled* state and set to the defined *Value* below.
All group policies that you need to configure for Windows Update for Business reports are under the following path: **Computer Configuration > Administrative Templates > Windows Components > Data Collection and Preview Builds**. All of these policies must be in the *Enabled* state and set to the defined *Value*.
| Policy | Value | Function | Required or recommended|
|---|---|---|---|
|**Allow Diagnostic Data** | Send required diagnostic data (minimum) | Configures the maximum allowed diagnostic data to be sent to Microsoft. Individual users can still set this value lower than what the policy defines. For more information, see the **Configure diagnostic data opt-in setting user interface**. | Required |
|**Configure diagnostic data opt-in setting user interface** | Disable diagnostic data opt in settings | Determines whether users of the device can adjust diagnostic data to levels lower than the level defined by AllowTelemetry. We recommend that you disable this policy, otherwise the effective diagnostic data level on devices might not be sufficient. | Recommended |
|**Allow device name to be sent in Windows diagnostic data** | Enabled | Allows device name to be sent for Windows Diagnostic Data. If this policy is Not Configured or Disabled, Device Name won't be sent and won't be visible in Windows Update for Business reports, showing `#` instead. | Recommended |
|**Configure diagnostic data opt-in change notifications** | Disable diagnostic data change notifications | Disables user notifications that appear for changes to the diagnostic data level. | Recommended |
| **Allow Diagnostic Data** | Send required diagnostic data | Configures the device to send the minimum required diagnostic data. | Required |
| **Configure diagnostic data opt-in setting user interface** | Disable diagnostic data opt-in settings | Determines whether users of the device can adjust diagnostic data to levels lower than you define by the *Allow Diagnostic Data* policy. Set the recommended value to disable opt-in settings, or users can change the effective diagnostic data level that might not be sufficient. | Recommended |
| **Allow device name to be sent in Windows diagnostic data** | Enabled | Allows the device to send its name with Windows diagnostic data. If you don't configure this policy or set it to *Disabled*, then the data doesn't include the device name. If the data doesn't include the device name, you can't see the device in Windows Update for Business reports. In this instance, the reports show `#` instead. | Recommended |
| **Configure diagnostic data opt-in change notifications** | Disable diagnostic data change notifications | Disables user notifications that appear for changes to the diagnostic data level. | Recommended |
## Required endpoints
To enable data sharing between devices, your network, and Microsoft's Diagnostic Data Service, configure your proxy to allow devices to contact the below endpoints.
<!--Using include for endpoint access requirements-->
[!INCLUDE [Endpoints for Windows Update for Business reports](./includes/wufb-reports-endpoints.md)]
## Required services
Many Windows and Microsoft services are required to ensure that not only the device can function, but Windows Update for Business reports can see device data. It's recommended that you allow all default services from the out-of-box experience to remain running. The [Windows Update for Business reports Configuration Script](wufb-reports-configuration-script.md) checks whether the majority of these services are running or are allowed to run automatically.
Many Windows services are required for Windows Update for Business reports to see device data. Allow all default services from the out-of-box experience to remain running. Use the [Windows Update for Business reports configuration script](wufb-reports-configuration-script.md) to check whether required services are running or are allowed to run automatically.
## Next steps

28
windows/deployment/update/wufb-reports-prerequisites.md
View File

@ -11,7 +11,7 @@ manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 08/30/2023
ms.date: 12/15/2023
---
# Windows Update for Business reports prerequisites
@ -22,12 +22,12 @@ Before you begin the process of adding Windows Update for Business reports to yo
## Azure and Microsoft Entra ID
- An Azure subscription with [Microsoft Entra ID](/azure/active-directory/)
- An Azure subscription with [Microsoft Entra ID](/azure/active-directory/).
- Devices must be Microsoft Entra joined and meet the below OS, diagnostic, and endpoint access requirements.
- Devices can be [Microsoft Entra joined](/azure/active-directory/devices/concept-azure-ad-join) or [Microsoft Entra hybrid joined](/azure/active-directory/devices/concept-azure-ad-join-hybrid).
- Devices that are [Microsoft Entra registered](/azure/active-directory/devices/concept-azure-ad-register) only (Workplace joined) aren't supported with Windows Update for Business reports.
- The Log Analytics workspace must be in a [supported region](#log-analytics-regions)
- Data in the **Driver update** tab of the [workbook](wufb-reports-workbook.md) is only available for devices that receive driver and firmware updates from the [Windows Update for Business deployment service](deployment-service-overview.md)
- Devices that are [Microsoft Entra registered](/azure/active-directory/devices/concept-azure-ad-register) only (workplace joined) aren't supported with Windows Update for Business reports.
- The Log Analytics workspace must be in a [supported region](#log-analytics-regions).
- Data in the **Driver update** tab of the [workbook](wufb-reports-workbook.md) is only available for devices that receive driver and firmware updates from the [Windows Update for Business deployment service](deployment-service-overview.md).
## Permissions
@ -38,7 +38,7 @@ Before you begin the process of adding Windows Update for Business reports to yo
- Windows 11 Professional, Education, Enterprise, and [Enterprise multi-session](/azure/virtual-desktop/windows-10-multisession-faq) editions
- Windows 10 Professional, Education, Enterprise, and [Enterprise multi-session](/azure/virtual-desktop/windows-10-multisession-faq) editions
Windows Update for Business reports only provides data for the standard Desktop Windows client version and isn't currently compatible with Windows Server, Surface Hub, IoT, or other versions.
Windows Update for Business reports only provides data for the standard desktop Windows client version and isn't currently compatible with Windows Server, Surface Hub, IoT, or other versions.
## Windows client servicing channels
@ -49,27 +49,25 @@ Windows Update for Business reports supports Windows client devices on the follo
### Windows operating system updates
- For [Changes to Windows diagnostic data collection](/windows/privacy/changes-to-windows-diagnostic-data-collection#services-that-rely-on-enhanced-diagnostic-data), installing the January 2023 release preview cumulative update, or a later equivalent update, is recommended
For [changes to Windows diagnostic data collection](/windows/privacy/changes-to-windows-diagnostic-data-collection#services-that-rely-on-enhanced-diagnostic-data), installing the January 2023 release preview cumulative update, or a later equivalent update, is recommended.
## Diagnostic data requirements
At minimum, Windows Update for Business reports requires devices to send diagnostic data at the *Required* level (previously *Basic*). For more information about what's included in different diagnostic levels, see [Configure Windows diagnostic data in your organization](/windows/privacy/configure-windows-diagnostic-data-in-your-organization).
At minimum, Windows Update for Business reports requires devices to send diagnostic data at the *Required* level (previously *Basic*). For more information about what data each diagnostic level includes, see [Configure Windows diagnostic data in your organization](/windows/privacy/configure-windows-diagnostic-data-in-your-organization).
The following levels are recommended, but not required:
- The *Enhanced* level for Windows 10 devices
- The *Optional* level for Windows 11 devices (previously *Full*) <!--8027083-->
Device names don't appear in Windows Update for Business reports unless you individually opt-in devices by using a policy. The configuration script does this for you, but when using other client configuration methods, set one of the following to display device names:
- The *Enhanced* level for Windows 10 devices.
- The *Optional* level for Windows 11 devices (previously *Full*). <!--8027083-->
- CSP: System/[AllowDeviceNameInDiagnosticData](/windows/client-management/mdm/policy-csp-system#system-allowdevicenameindiagnosticdata)
- Group Policy: **Allow device name to be sent in Windows diagnostic data** under **Computer Configuration\Administrative Templates\Windows Components\Data Collection and Preview Builds**
Device names don't appear in Windows Update for Business reports unless you individually opt in devices by using a policy. The configuration script does this action for you, but when using other client configuration methods, set one of the following policies to display device names:
- CSP: System/[AllowDeviceNameInDiagnosticData](/windows/client-management/mdm/policy-csp-system#system-allowdevicenameindiagnosticdata)
- Group Policy: **Allow device name to be sent in Windows diagnostic data** under **Computer Configuration\Administrative Templates\Windows Components\Data Collection and Preview Builds**
> [!TIP]
> Windows Update for Business reports uses [services configuration](/windows/privacy/manage-connections-from-windows-operating-system-components-to-microsoft-services#bkmk-svccfg), also called OneSettings. Disabling the services configuration can cause some of the client data to be incorrect or missing in reports. For more information, see the [DisableOneSettingsDownloads](/windows/client-management/mdm/policy-csp-system#disableonesettingsdownloads) policy settings.
Microsoft is committed to providing you with effective controls over your data and ongoing transparency into our data handling practices. For more information about data handling and privacy for Windows diagnostic data, see [Configure Windows diagnostic data in your organization](/windows/privacy/configure-windows-diagnostic-data-in-your-organization) and [Changes to Windows diagnostic data collection](/windows/privacy/changes-to-windows-diagnostic-data-collection#services-that-rely-on-enhanced-diagnostic-data).
## Endpoints

280
windows/deployment/update/wufb-reports-schema-enumerated-types.md Normal file
View File

@ -0,0 +1,280 @@
---
title: Enumerated types
titleSuffix: Windows Update for Business reports
description: Enumerated types for Windows Update for Business reports.
ms.prod: windows-client
ms.technology: itpro-updates
ms.topic: reference
author: mestew
ms.author: mstewart
manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 12/06/2023
---
# Enumerated types for Windows Update for Business reports
<!--8506381-->
The following enumerated types are used in Windows Update for Business reports:
## OSEdition
SKU of Windows the device is running.
|Value | Description |
|---|---|
| **Enterprise** | Windows Enterprise |
| **Professional** | Windows Professional |
| **ProfessionalWorkstation** | Windows Professional workstation |
| **ProfessionalN** | Similar to Windows Professional edition but doesn't include Windows media player. |
| **Education** | Windows Education |
## OSArchitecture
Architecture of the OS running on the client.
|Value | Description |
|---|---|
| **amd64** | OS is 64-bit |
| **x86** | OS is 32-bit |
| **Unknown** | The OS architecture is unknown |
## OSFeatureUpdateStatus
Feature updates status
|Value | Description |
|---|---|
| **Unknown** | Default, sent if client data unavailable. |
| **InService** | Client is on a version of Windows 10 that is serviced. |
| **EndOfService** | Client is on a version of Windows 10 that is no longer serviced. |
## OSQualityUpdateStatus
Quality updates status
|Value | Description |
|---|---|
| **Latest** | Client is on the latest quality update |
| **NotLatest** | Client isn't on the latest quality update |
## OSSecurityUpdateStatus
Security updates status
|Value | Description |
|---|---|
| **Latest** | Client is on the latest security update |
| **NotLatest** | Client isn't on the latest security update |
| **MultipleSecurityUpdatesMissing** | Client is missing multiple security updates |
## OSFeatureUpdateComplianceStatus, OSSecurityUpdateComplianceStatus, OSQualityUpdateComplianceStatus
Compliance status
|Value | Description |
|---|---|
| **Compliant** | The latest deployment from the Windows Update for Business deployment service is installed on the client |
| **NotCompliant** | The latest deployment from the Windows Update for Business deployment service isn't installed on the client|
| **NotApplicable** | Client isn't part of any Windows Update for Business deployment service deployments |
## OSServicingChannel
Servicing channel of client
|Value | Description |
|---|---|
| **Unknown** | Default, release branch can't be defined. |
| **SAC** | Semi-annual release channel |
| **LTSC** | Long-term servicing channel |
| **WIP-S** | Windows Insider Preview - Slow ring |
| **WIP-F**| Windows Insider Preview - Fast ring |
| **Internal** | An identifiable, but internal release ring |
## ServiceState
High-level service state OSServicingChannel
|Value | Description |
|---|---|
| **Pending** | Windows Update for Business deployment service isn't targeting this update to this device because the update isn't ready. |
| **Offering** | Service is offering the update to the device. The update is available for the device to get if it scans Windows Update. |
| **OnHold** | Service is holding off on offering update to the device indefinitely. Until either the service or admin changes some condition, devices remain in this state. |
| **Canceled** | Service canceled offering update to the device, and the device is confirmed to not be installing the update. |
## ServiceSubstate
Lower-level service state
| Value | ServiceState |
|---|---|
| **Validation** | Update can't be offered to the device because a validation issue with the device and deployment service. |
| **Scheduled** | Update isn't ready to be offered to the device, but is scheduled for offering at a later date. |
| **OfferReady** | Update is currently being offered to the device from Windows Update. |
| **RemovedFromDeployment** | Update offering was canceled because it was removed from the deployment because of an explicit administrator action. |
| **AdminCancelled** | Update offering was canceled because of an explicit administrator action. |
| **ServiceCancelled** | Update offering was canceled because of an automatic action by the deployment service. |
| **AdminPaused** | Update is on hold because the deployment was paused with an explicit administrator action. |
| **ServicePaused** | Update is on hold because of an automatic action by the deployment service. |
| **SafeguardHold** | Update isn't offered because an existing safeguard hold on the device. |
## ClientState
High-level client state
|Value | Description |
|---|---|
| **Unknown** | Default value, if ClientSubstate is unknown (in other words, no client data) |
| **Offering** | Update is being offered to device |
| **Installing** | Update is in progress on device |
| **Uninstalling** | Update is being uninstalled from device |
| **Installed** | Update has been installed to device |
| **Uninstalled** | Update has been uninstalled from device |
| **Canceled** | Update has been canceled from device |
| **OnHold** | Update has been on Hold |
## ClientSubstate
Lower-level client state
|Value | Description |
|---|---|
| **Unknown** | Default value, if ClientSubstate is unknown (in other words, no client data) |
| **Offering** | Update is being offered to device |
| **Installing** | Update is in progress on device |
| **Uninstalling** | Update is being uninstalled from device |
| **Installed** | Update has been installed to device |
| **Uninstalled** | Update has been uninstalled from device |
| **Canceled** | Update has been canceled from device |
| **OnHold** | Update has been on Hold |
## UpdateCategory
Type of update.
|Value | Description |
|---|---|
| **WindowsQualityUpdate** | Windows feature update |
| **WindowsFeatureUpdate** | Windows quality update |
| **DriverUpdate** | Driver update |
## UpdateClassification
Whether this update is an upgrade, security, nonsecurity, or driver
|Value | Description |
|---|---|
| **Security** | Update is a quality update containing security fixes |
| **NonSecurity** | Update is a quality update not containing security fixes |
| **Upgrade** | Update is a feature update |
## UpdateSource
Source of the update
|Value | Description |
|---|---|
| **Inferred** | |
| **MuV6** | Update through old Windows Update, or via WSUS (uses old protocol) |
| **UUP** | Update through modern Windows Update |
## ReadinessStatus
Whether the device is capable of taking target OS and version.
|Value | Description |
|---|---|
| **Capable** | The device meets all requirements to upgrade to Windows 11. |
| **Not Capable** | The device doesn't meet the requirements to upgrade to Windows 11. Check Readiness Reason for the reason. |
| **Unknown** | Microsoft doesn't have enough data points to determine the eligibility status. |
## ReadinessReason
Reason why the device isn't capable of updating to target OS and version.
|Value | Description |
|---|---|
| **tpm** | [Trusted Platform Module](/windows/security/hardware-security/tpm/trusted-platform-module-overview) (TPM) version 2.0 is required. If your device doesn't meet the minimum requirements because of TPM, see [Enable TPM 2.0 on your PC](https://support.microsoft.com/windows/enable-tpm-2-0-on-your-pc-1fd5a332-360d-4f46-a1e7-ae6b0c90645c) to see if there are any remediation steps you can take. |
| **cpufms** | CPU not supported. For more information, see [Windows Processor Requirements](/windows-hardware/design/minimum/windows-processor-requirements) |
| **sysdrivesize** | 64 GB or larger storage device required. If your PC doesn't have a large enough storage drive, sometimes there are options for upgrading the drive. Consult your PC manufacturer's website or with a retailer to see if there are options to meet the minimum requirements for Windows 11. |
| **UefiSecureBoot** | UEFI (Unified Extensible Firmware Interface) and Secure Boot capability. If your device doesn't meet the minimum requirements because it's not Secure Boot capable. For more information, see [Windows 11 and Secure Boot](https://support.microsoft.com/topic/a8ff1202-c0d9-42f5-940f-843abef64fad) to see if you're able to enable Secure Boot. Secure Boot can only be enabled with UEFI. |
## AlertType
Type of alert.
|Value | Description |
|---|---|
| **ServiceUpdateAlert** | Alert is relevant to Windows Update for Business deployment service's offering of the content to the client. |
| **ClientUpdateAlert** | Alert is relevant to client's ability to progress through the installation of the update content. |
| **ServiceDeviceAlert** | Alert is relevant to device's status within Windows Update for Business deployment service |
| **ClientDeviceAlert** | Alert is relevant to device's state |
| **DeploymentAlert** | Alert is relevant to an entire deployment, or a significant number of devices in the deployment. |
## AlertSubtype
Subtype of alert.
| Value | Description |
|---|---|
| **CancelledByUser** | The user canceled the update. |
| **CertificateIssue** | An expired certificate was encountered. |
| **DamagedMedia** | The update file appears to be damaged. |
| **DeviceRegistrationInvalidAzureADJoin** | Device isn't able to register or authenticate properly with the deployment service due to not being device-level Entra ID joined. Devices that are workplace-joined aren't compatible with the deployment service. |
| **DiskFull** | An operation couldn't be completed because the disk is full. |
| **DiskIssue** | Windows Update has found disk corruption. |
| **DownloadCancelled** | The download was canceled. |
| **DownloadCredentialsIssue** | A proxy server or firewall on your network might require credentials. |
| **DownloadIssue** | There was a download issue. |
| **DownloadIssueServiceDisabled** | The service the download depends on is disabled. |
| **DownloadTimeout** | A timeout occurred. |
| **EndOfService** | Client OS is no longer being serviced |
| **EndOfServiceApproaching** | Client OS servicing period completes in less than 60 days |
| **FileNotFound** | The installer couldn't find a Windows component that it needs. |
| **InstallAccessDenied** | Access denied. |
| **InstallCancelled** | Install canceled. |
| **InstallFileLocked** | Couldn't access the file because it's already in use. |
| **InstallIssue** | There was an installation issue. |
| **InstallSetupBlock** | There's an application or driver blocking the upgrade. |
| **InstallSetupError** | Encountered an error while installing the new version of Windows. |
| **InstallSetupRestartRequired** | A restart is required. |
| **InstallSharingViolation** | An application is likely interfering with Windows Update. |
| **InstallSystemError** | A system error occurred while installing the new version of Windows. |
| **InsufficientUpdateConnectivity** | Device hasn't had sufficient connectivity to Windows Update to progress through the update process and will experience delays. |
| **MultipleSecurityUpdatesMissing** | Client is missing multiple security updates |
| **NetworkIssue** | The server timed out waiting for the requested. |
| **PathNotFound** | The specified path can't be found. |
| **RestartIssue** | The restart to apply updates is being blocked by one or more applications. |
| **SafeguardHold** | Update can't be installed due to a known Safeguard Hold. |
| **UnexpectedShutdown** | The installation stopped because Windows was shutting down or restarting. |
| **WindowsComponentCorruption** | This device has a corrupted Windows component |
| **WUBusy** | Windows Update tried to install an update while another installation process was already running. |
| **WUComponentMissing** | Windows Update might be missing a component or the update file might be damaged. |
| **WUDamaged** | The update file might be damaged. |
| **WUFileCorruption** | Windows Update encountered corrupted files. |
| **WUIssue** | An unexpected issue was encountered during the installation. |
| **WUSetupError** | The setup process was suspended. |
## AlertStatus
Status of alert
|Value | Description |
|---|---|
| **Active** | Alert is active, still requires attention. |
| **Resolved** | Alert is resolved and no longer requires attention. |
| **Deleted** | Alert was deleted from the backend system. |
### AlertClassification
Whether this alert is an error, a warning, or informational.
| **Value** | Description |
|---|---|
| **Informational** | Alert is informational in nature. |
| **Warning** | Alert is a warning |
| **Error** | Alert is an error, or is related to an error. There should be an error code that maps to either something from the client or from the service. |
| **Recommendation** | Alert is a recommendation, something to optimize. |

100
windows/deployment/update/wufb-reports-schema-ucclient.md
View File

@ -11,7 +11,7 @@ manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 08/09/2023
ms.date: 12/06/2023
---
# UCClient
@ -19,41 +19,63 @@ ms.date: 08/09/2023
UCClient acts as an individual device's record. It contains data such as the currently installed build, the device's name, the OS edition, and active hours (quantitative).
## Schema for UCClient
|Field |Type |Example |Description |
|---|---|---|---|
| **AzureADDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra Device ID |
| **AzureADTenantId** | [string](/azure/kusto/query/scalar-data-types/string) | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID |
| **Country** | [string](/azure/kusto/query/scalar-data-types/string) | `US` | The last-reported location of device (country or region), based on IP address. Shown as country code. |
| **DeviceFamily** | [string](/azure/kusto/query/scalar-data-types/string) | `PC, Phone` | The device family such as PC, Phone. |
| **DeviceName** | [string](/azure/kusto/query/scalar-data-types/string) | `JohnPC-Contoso` | Client-provided device name |
| **GlobalDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `g:9832741921341` | The global device identifier |
| **LastCensusScanTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The last time this device performed a successful census scan, if any. |
| **LastWUScanTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The last time this device performed a successful Windows Update scan, if any. |
| **OSArchitecture** | [string](/azure/kusto/query/scalar-data-types/string) | `x86` | The architecture of the operating system (not the device) this device is currently on. |
| **OSBuild** | [string](/azure/kusto/query/scalar-data-types/string) | `10.0.22621.1702` | The full operating system build installed on this device, such as Major.Minor.Build.Revision |
| **OSBuildNumber** | [int](/azure/kusto/query/scalar-data-types/int) | `22621` | The major build number, in int format, the device is using. |
| **OSEdition** | [string](/azure/kusto/query/scalar-data-types/string) | `Professional` | The Windows edition |
| **OSFeatureUpdateComplianceStatus** | [string](/azure/kusto/query/scalar-data-types/string)| `Compliant` | Whether or not the device is on the latest feature update that's offered from the Windows Update for Business deployment service, else NotApplicable. |
| **OSFeatureUpdateEOSTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The end of service date of the feature update currently installed on the device. |
| **OSFeatureUpdateReleaseTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The release date of the feature update currently installed on the device. |
| **OSFeatureUpdateStatus** | [string](/azure/kusto/query/scalar-data-types/string) | `InService;EndOfService` | Whether or not the device is on the latest available feature update, for its feature update. |
| **OSQualityUpdateComplianceStatus** | [string](/azure/kusto/query/scalar-data-types/string) | `NotCompliant` | Whether or not the device is on the latest quality update that's offered from the Windows Update for Business deployment service, else NotApplicable. |
| **OSQualityUpdateReleaseTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The release date of the quality update currently installed on the device. |
| **OSQualityUpdateStatus** | [string](/azure/kusto/query/scalar-data-types/string)| `Latest;NotLatest` | Whether or not the device is on the latest available quality update, for its feature update. |
| **OSRevisionNumber** | [int](/azure/kusto/query/scalar-data-types/int) | `836` | The revision, in int format, this device is on. |
| **OSSecurityUpdateComplianceStatus** | [string](/azure/kusto/query/scalar-data-types/string) | `NotCompliant` | Whether or not the device is on the latest security update (quality update where the Classification=Security) that's offered from the Windows Update for Business deployment service, else NotApplicable. |
| **OSSecurityUpdateStatus** | [string](/azure/kusto/query/scalar-data-types/string)| `Latest;NotLatest;MultipleSecurityUpdatesMissing` | Whether or not the device is on the latest available security update, for its feature update. |
| **OSServicingChannel** | [string](/azure/kusto/query/scalar-data-types/string) | `SAC` | The elected Windows 10 servicing channel of the device. |
| **OSVersion** | [string](/azure/kusto/query/scalar-data-types/string) | `1909` | The Windows 10 operating system version currently installed on the device, such as 19H2, 20H1, 20H2. |
| **SCCMClientId** | [string](/azure/kusto/query/scalar-data-types/string) | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | Configuration Manager client ID, if available. |
| **TimeGenerated** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The time the snapshot generated this specific record. This field is to determine to which batch snapshot this record belongs. |
| **Type** | [string](/azure/kusto/query/scalar-data-types/string) | `DeviceEvent` | The EntityType. |
| **WUFeatureDeadlineDays** | [int](/azure/kusto/query/scalar-data-types/int) | `0` | CSP: ConfigureDeadlineForFeatureUpdates. The Windows update feature update deadline configuration in days. `-1` indicates not configured, `0` indicates configured but set to `0`. Values > `0` indicate the deadline in days. |
| **WUFeatureDeferralDays** | [int](/azure/kusto/query/scalar-data-types/int) | `0` | CSP: DeferFeatureUpdates. The Windows update feature update deferral configuration in days. `-1` indicates not configured, `0` indicates configured but set to `0`. Values > `0` indicate the policy setting. |
| **WUFeatureGracePeriodDays** | [int](/azure/kusto/query/scalar-data-types/int) | `7` | The Windows Update grace period for feature update in days. -1 indicates not configured, `0` indicates configured and set to `0`. Values greater than `0` indicate the grace period in days. |
| **WUFeaturePauseState** | [string](/azure/kusto/query/scalar-data-types/string) | `NotConfigured` | Indicates pause status of device for feature updates, possible values are Paused, NotPaused, NotConfigured. |
| **WUQualityDeadlineDays** | [int](/azure/kusto/query/scalar-data-types/int) | `7` | CSP: ConfigureDeadlineForQualityUpdates. The Windows update quality update deadline configuration in days. `-1` indicates not configured, `0` indicates configured but set to `0`. Values > `0` indicate the deadline in days. |
| **WUQualityDeferralDays** | [int](/azure/kusto/query/scalar-data-types/int) | `-1` | CSP: DeferQualityUpdates. The Windows Update quality update deferral configuration in days. `-1` indicates not configured, `0` indicates configured but set to `0`. Values greater than `0` indicate the policy setting. |
| **WUQualityGracePeriodDays** | [int](/azure/kusto/query/scalar-data-types/int) | `0` | The Windows Update grace period for quality update in days. `-1` indicates not configured, `0` indicates configured and set to `0`. Values greater than `0` indicate the grace period in days. |
| **WUQualityPauseState** | [string](/azure/kusto/query/scalar-data-types/string) | `NotConfigured` | Indicates pause status of device for quality updates, possible values are Paused, NotPaused, NotConfigured. |
<!--8506381-->
| Field |Type | Enumerated type |Example |Description |
|---|---|---|---|---|
| **AzureADDeviceID** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra Device ID |
| **AzureADTenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID |
| **City** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. Device city, based on IP address. |
| **Country** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `US` | The last-reported location of device (country or region), based on IP address. Shown as country code. |
| **DeviceFamily** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `PC, Phone` | The device family such as PC, Phone. |
| **DeviceFormFactor** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Notebook, Desktop, Phone.` | Currently, data isn't gathered to populate this field. The device form factor |
| **DeviceManufacturer** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Hewlett-Packard.` | Currently, data isn't gathered to populate this field. The device OEM manufacturer |
| **DeviceModel** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `The device's OEM model ` | Currently, data isn't gathered to populate this field. The device OEM model |
| **DeviceName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `JohnPC-Contoso` | Client-provided device name |
| **GlobalDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `g:9832741921341` | The global device identifier |
| **IsVirtual** | [bool](/azure/data-explorer/kusto/query/scalar-data-types/bool) | No | `Yes, No` | Whether device is a virtual device. |
| **LastCensusScanTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The last time this device performed a successful census scan, if any. |
| **LastWUScanTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The last time this device performed a successful Windows Update scan, if any. |
| **NewTest_CF [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | Currently, data isn't gathered to populate this field. |
| **OSArchitecture** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `x86` | The architecture of the operating system (not the device) this device is currently on. |
| **OSBuild** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `10.0.22621.1702` | The full operating system build installed on this device, such as Major.Minor.Build.Revision |
| **OSBuildNumber** | [int](/azure/kusto/query/scalar-data-types/int) | No | `22621` | The major build number, in int format, the device is using. |
| **OSEdition** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Professional` | The Windows edition |
| **OSFeatureUpdateComplianceStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Compliant` | Whether the device is on the latest feature update that's offered from the Windows Update for Business deployment service, else NotApplicable. |
| **OSFeatureUpdateEOSTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The end of service date of the feature update currently installed on the device. |
| **OSFeatureUpdateReleaseTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The release date of the feature update currently installed on the device. |
| **OSFeatureUpdateStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `InService;EndOfService` | Whether the device is on the latest available feature update, for its feature update. |
| **OSQualityUpdateComplianceStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `NotCompliant` | Whether the device is on the latest quality update that's offered from the Windows Update for Business deployment service, else NotApplicable. |
| **OSQualityUpdateReleaseTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The release date of the quality update currently installed on the device. |
| **OSQualityUpdateStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Latest;NotLatest` | Whether the device is on the latest available quality update, for its feature update. |
| **OSRevisionNumber** | [int](/azure/kusto/query/scalar-data-types/int) | No | `836` | The revision, in int format, this device is on. |
| **OSSecurityUpdateComplianceStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `NotCompliant` | Whether the device is on the latest security update (quality update where the Classification=Security) that's offered from the Windows Update for Business deployment service, else NotApplicable. |
| **OSSecurityUpdateStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Latest;NotLatest;MultipleSecurityUpdatesMissing` | Whether the device is on the latest available security update, for its feature update. |
| **OSServicingChannel** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `SAC` | The elected Windows 10 servicing channel of the device. |
| **OSVersion** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `1909` | The Windows 10 operating system version currently installed on the device, such as 19H2, 20H1, 20H2. |
| **PrimaryDiskFreeCapacityMb** | | No | | Currently, data isn't gathered to populate this field. Free disk capacity of the primary disk in Megabytes. |
| **SCCMClientId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | Configuration Manager client ID, if available. |
| **SourceSystem** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Azure` | |
| **TenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID of the device. |
| **TimeGenerated [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The time the snapshot generated this specific record. This field is to determine to which batch snapshot this record belongs. |
| **Type** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `UCClient` | The entity type |
| **UpdateConnectivityLevel** | | Yes | | Currently, data isn't gathered to populate this field. Whether or not this device is maintaining a sufficiently cumulative and continuous connection to Windows Update so the update can progress optimally. |
| **WUAutomaticUpdates** | | No | | Currently, data isn't gathered to populate this field. Manage automatic update behavior to scan, download, and install updates. |
| **WUDeadlineNoAutoRestart** | | No | | Currently, data isn't gathered to populate this field. Devices won't automatically restart outside of active hours until the deadline is reached - It's 1 by default and indicates enabled, 0 indicates disabled |
| **WUDODownloadMode** | | No | | Currently, data isn't gathered to populate this field. The Windows Update DO DownloadMode configuration. |
| **WUFeatureDeadlineDays** | [int](/azure/kusto/query/scalar-data-types/int) | No | `0` | CSP: ConfigureDeadlineForFeatureUpdates. The Windows Update feature update deadline configuration in days. -1 indicates not configured, 0 indicates configured but set to 0. Values > 0 indicate the deadline in days. |
| **WUFeatureDeferralDays** | [int](/azure/kusto/query/scalar-data-types/int) | No | `0` | CSP: DeferFeatureUpdates. The Windows Update feature update deferral configuration in days. -1 indicates not configured, 0 indicates configured but set to 0. Values > 0 indicate the policy setting. |
| **WUFeatureGracePeriodDays** | [int](/azure/kusto/query/scalar-data-types/int) | No | `7` | The Windows Update grace period for feature update in days. -1 indicates not configured, 0 indicates configured and set to 0. Values greater than 0 indicate the grace period in days. |
| **WUFeaturePauseEndTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | Currently, data isn't gathered to populate this field. The time Windows Update feature update pause will end, if activated, else null. |
| **WUFeaturePauseStartTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | Currently, data isn't gathered to populate this field. The time Windows Update feature update pause was activated, if activated, else null. Feature updates are paused for 35 days from the specified start date. |
| **WUFeaturePauseState** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `NotConfigured` | Indicates pause status of device for feature updates. Possible values are Paused, NotPaused, NotConfigured. |
| **WUNotificationLevel** | | No | | Currently, data isn't gathered to populate this field. This policy allows you to define what Windows Update notifications users see. 0 (default) - Use the default Windows Update notifications. 1 - Turn off all notifications, excluding restart warnings. 2 - Turn off all notifications, including restart warnings |
| **WUPauseUXDisabled** | | No | | Currently, data isn't gathered to populate this field. This policy allows the IT admin to disable the Pause Updates feature. When this policy is enabled, the user can't access the Pause updates' feature. Supported values 0, 1. |
| **WUQualityDeadlineDays** | [int](/azure/kusto/query/scalar-data-types/int) | No | `7` | CSP: ConfigureDeadlineForQualityUpdates. The Windows update quality update deadline configuration in days. -1 indicates not configured, 0 indicates configured but set to 0. Values > 0 indicate the deadline in days. |
| **WUQualityDeferralDays** | [int](/azure/kusto/query/scalar-data-types/int) | No | `-1` | CSP: DeferQualityUpdates. The Windows Update quality update deferral configuration in days. -1 indicates not configured, 0 indicates configured but set to 0. Values greater than 0 indicate the policy setting. |
| **WUQualityGracePeriodDays** | [int](/azure/kusto/query/scalar-data-types/int) | No | `0` | The Windows Update grace period for quality update in days. -1 indicates not configured, 0 indicates configured and set to 0. Values greater than 0 indicate the grace period in days. |
| **WUQualityPauseEndTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | Currently, data isn't gathered to populate this field. The time Windows Update quality update pause- will end, if activated, else null. |
| **WUQualityPauseStartTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | Currently, data isn't gathered to populate this field. The time Windows Update quality update pause- was activated; if activated; else null. |
| **WUQualityPauseState** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `NotConfigured` | Indicates pause status of device for quality updates. Possible values are Paused, NotPaused, NotConfigured. |
| **WURestartNotification** | | No | | Currently, data isn't gathered to populate this field. Allows the IT Admin to specify the method by which the auto restart required notification is dismissed. The following list shows the supported values: 1 (default) = Auto Dismissal. 2 - User Dismissal. |
| **WUServiceURLConfigured**| | No | | Currently, data isn't gathered to populate this field. The device checks for updates from Microsoft Update. Set to a URL, such as http://abcd-srv:8530. The device checks for updates from the WSUS server at the specified URL. Not configured. The device checks for updates from Microsoft Update. Set to a URL, such as http://abcd-srv:8530. The device checks for updates from the WSUS server at the specified URL. |
| **WUUXDisabled** | | No | | Currently, data isn't gathered to populate this field. This policy allows the IT admin to remove access to scan Windows Update. When this policy is enabled, the user can't access the Windows Update scan, download, and install features. Default is 0. Supported values 0, 1. |

51
windows/deployment/update/wufb-reports-schema-ucclientreadinessstatus.md
View File

@ -11,7 +11,7 @@ manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 06/06/2022
ms.date: 12/06/2023
---
# UCClientReadinessStatus
@ -20,26 +20,29 @@ ms.date: 06/06/2022
UCClientReadinessStatus is an individual device's record about its readiness for updating to Windows 11. If the device isn't capable of running Windows 11, the record includes which Windows 11 [hardware requirements](/windows/whats-new/windows-11-requirements#hardware-requirements) the device doesn't meet.
## Schema for UCClientReadinessStatus
|Field |Type |Example |Description |
|---|---|---|---|
| **DeviceName** | [string](/azure/kusto/query/scalar-data-types/string) | `JohnPC-Contoso` | Client-provided device name |
| **GlobalDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `g:9832741921341` | The global device identifier. |
| **SCCMClientId** | [string](/azure/kusto/query/scalar-data-types/string) | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | Configuration Manager Client ID, if available. |
| **AzureADTenantId** | [string](/azure/kusto/query/scalar-data-types/string) | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID |
| **AzureADDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra Device ID |
| **OSName** | [string](/azure/kusto/query/scalar-data-types/string) | `Windows 10` | The operating system name. |
| **OSVersion** | [string](/azure/kusto/query/scalar-data-types/string) | `1909` | The Win10 OS Version (such as 19H2, 20H1, 20H2) currently installed on the device. |
| **OSBuild** | [string](/azure/kusto/query/scalar-data-types/string) | `10.0.18363.836` | The full OS build installed on this device, such as Major.Minor.Build.Revision |
| **TargetOSName** | [string](/azure/kusto/query/scalar-data-types/string) | `Windows 11` | The name of the operating system being targeted to the device for this readiness record.|
| **TargetOSVersion** | [string](/azure/kusto/query/scalar-data-types/string) | `21H2` | The operating system version being targeted to the device for this readiness record.|
| **TargetOSBuild** | [string](/azure/kusto/query/scalar-data-types/string) | `10.0.22000.1` | The full operating system build number that's being targeted to the device for this readiness record.|
| **ReadinessStatus** | [string](/azure/kusto/query/scalar-data-types/string) | `Not capable` | The readiness status of the device is either capable, not capable, or unknown. This status is determined by Windows Update.|
| **ReadinessReason** | [string](/azure/kusto/query/scalar-data-types/string) | `CPU;TPM` | Lists which [hardware requirements](/windows/whats-new/windows-11-requirements#hardware-requirements) are blocking the device from being capable of installing Windows 11. Field is null if the device is capable. This status is determined by the Windows Update applicability. |
| **ReadinessScanTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The date and time when readiness was assessed and the assessment was sent.|
| **ReadinessExpiryTime**| [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The date and time when the readiness assessment will expire.|
| **SetupReadinessStatus**| [string](/azure/kusto/query/scalar-data-types/string) | `Not capable` | The readiness status of the device is either capable, not capable, or unknown. This status is determined by Windows setup.|
| **SetupReadinessReason** | [string](/azure/kusto/query/scalar-data-types/string) | `CPU;TPM` | Lists which [hardware requirements](/windows/whats-new/windows-11-requirements#hardware-requirements) are blocking the device from being capable of installing Windows 11. Field is null if the device is capable. This status is determined by Windows setup. |
| **SetupReadinessTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The date and time when readiness was assessed by setup and the assessment was sent.|
| **SetupReadinessExpiryTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The date and time when the setup readiness assessment will expire.|
| **TimeGenerated** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 10:26:03.478039` | The date and time when Azure Monitor Logs ingested this record for your Log Analytics workspace.|
<!--8506381-->
|Field |Type | Enumerated type |Example |Description |
|---|---|---|---|---|
| **AzureADDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra Device ID |
| **AzureADTenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID |
| **DeviceName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `JohnPC-Contoso` | Client-provided device name |
| **GlobalDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `g:9832741921341` | The global device identifier. |
| **OSBuild** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `10.0.18363.836` | The full OS build installed on this device, such as Major.Minor.Build.Revision |
| **OSName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Windows 10` | The operating system name. |
| **OSVersion** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `1909` | The Win10 OS version (such as 19H2, 20H1, 20H2) currently installed on the device. |
| **ReadinessExpiryTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | The date and time when the readiness assessment will expire. |
| **ReadinessReason** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `CPU;TPM` | Lists which hardware requirements are blocking the device from being capable of installing Windows 11. Field is null if the device is capable. This status is determined by the Windows Update applicability. |
| **ReadinessScanTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | The date and time when readiness was assessed and the assessment was sent. |
| **ReadinessStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Not capable` | The readiness status of the device is either capable, not capable, or unknown. This status is determined by Windows Update. |
| **SCCMClientId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | Configuration Manager Client ID, if available. |
| **SetupReadinessExpiryTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | The date and time when the setup readiness assessment will expire. |
| **SetupReadinessReason** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `CPU;TPM` | Lists which hardware requirements are blocking the device from being capable of installing Windows 11. Field is null if the device is capable. This status is determined by Windows setup. |
| **SetupReadinessStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Not capable` | The readiness status of the device is either capable, not capable, or unknown. This status is determined by Windows setup. |
| **SetupReadinessTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | The date and time when readiness was assessed by setup and the assessment was sent. |
| **SourceSystem** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Azure` | |
| **TargetOSBuild** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `10.0.22000.1` | The full operating system build number that's being targeted to the device for this readiness record. |
| **TargetOSName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Windows 11` | The name of the operating system being targeted to the device for this readiness record. |
| **TargetOSVersion** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `21H2` | The operating system version being targeted to the device for this readiness record. |
| **TenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID of the device. |
| **TimeGenerated [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | The date and time when Azure Monitor Logs ingested this record for your Log Analytics workspace. |
| **Type** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `UCClientReadinessStatus` | The entity type |

82
windows/deployment/update/wufb-reports-schema-ucclientupdatestatus.md
View File

@ -11,7 +11,7 @@ manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 06/05/2023
ms.date: 12/06/2023
---
# UCClientUpdateStatus
@ -20,39 +20,47 @@ ms.date: 06/05/2023
Update Event that combines the latest client-based data with the latest service-based data to create a complete picture for one device (client) and one update.
## Schema for UCClientUpdateStatus
| Field | Type | Example | Description |
|---|---|---|---|
| **AzureADDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | A string corresponding to the Microsoft Entra tenant to which the device belongs. |
| **AzureADTenantId** | [string](/azure/kusto/query/scalar-data-types/string) | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | A string corresponding to this device's Microsoft Entra device ID |
|**CatalogId** | [string](/azure/kusto/query/scalar-data-types/string) | `b0f410599615e2ce15e6614ac3fc4ec62d80324020351e172edef89091a64f2f` | The update catalog ID |
| **ClientState** | [string](/azure/kusto/query/scalar-data-types/string) | `Installing` | Higher-level bucket of ClientSubstate. |
| **ClientSubstate** | [string](/azure/kusto/query/scalar-data-types/string) | `DownloadStart` | Last-known state of this update relative to the device, from the client. |
| **ClientSubstateRank** | [int](/azure/kusto/query/scalar-data-types/int) | `2300` | Ranking of client substates for sequential ordering in funnel-type views. The rankings between ServiceSubstate and ClientSubstate can be used together. |
| **ClientSubstateTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | Date and time of last client substate transition |
| **DeploymentId** | [string](/azure/kusto/query/scalar-data-types/string) | `cf1b12a3-3d84-4ce3-bc8e-de48459e252d` | The identifier of the deployment that is targeting this update to this device, else empty. |
| **DeviceName** | [string](/azure/kusto/query/scalar-data-types/string) | `JohnPC-Contoso` | Device's given name |
| **FurthestClientSubstate** | [string](/azure/kusto/query/scalar-data-types/string) | `DownloadComplete` | Furthest clientSubstate |
| **FurthestClientSubstateRank** | [int](/azure/kusto/query/scalar-data-types/int) | `2400` | Ranking of furthest clientSubstate |
| **GlobalDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `g:9832741921341` | Microsoft internal global device identifier |
| **IsUpdateHealty** | [bool](/azure/data-explorer/kusto/query/scalar-data-types/bool) | `1` | True: No issues preventing this device from updating to this update have been found. False: There is something that may prevent this device from updating. |
| **OfferReceivedTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | Date and time when device last reported entering OfferReceived, else empty. |
| **RestartRequiredTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | Date and time when device first reported entering RebootRequired (or RebootPending), else empty. |
| **SCCMClientId** | [string](/azure/kusto/query/scalar-data-types/string) | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | A string corresponding to the Configuration Manager Client ID on the device. |
| **SourceSystem** | [string](/azure/kusto/query/scalar-data-types/string)| `Azure`| |
| **TargetBuild** | [string](/azure/kusto/query/scalar-data-types/string) | `10.0.18363.836` | The full build of the content this DeviceUpdateEvent is tracking. For Windows 10 updates, this value would correspond to the full build (10.0.14393.385). |
| **TargetBuildNumber** | [int](/azure/kusto/query/scalar-data-types/int) | `18363` | Integer of the Major portion of Build. |
| **TargetKBNumber** | [string](/azure/kusto/query/scalar-data-types/string) | `KB4524570` | KB Article. |
| **TargetRevisionNumber** | [int](/azure/kusto/query/scalar-data-types/int) | `836` | Integer or the minor (or revision) portion of the build. |
| **TargetVersion** | [int](/azure/kusto/query/scalar-data-types/int) | `1909` | The target operating system version, such as 1909. |
| **TimeGenerated** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The time the snapshot generated this specific record. This is to determine to which batch snapshot this record belongs. |
| **Type** | [string](/azure/kusto/query/scalar-data-types/string) | `DeviceUpdateEvent` | The EntityType |
| **UpdateCategory** | [string](/azure/kusto/query/scalar-data-types/string) | `WindowsFeatureUpdate` | The type of content this DeviceUpdateEvent is tracking. |
| **UpdateClassification** | [string](/azure/kusto/query/scalar-data-types/string) | `Upgrade` | Whether the update classification is an upgrade (feature update), security (quality update), non-security (quality update), or driver |
| **UpdateDisplayName** | [string](/azure/kusto/query/scalar-data-types/string) | `Windows 10 1909` | The long-form display name for the given update. Varies on content type (feature update. quality update) |
| **UpdateId** | [string](/azure/kusto/query/scalar-data-types/string) | `10e519f0-06ae-4141-8f53-afee63e995f0` |Update ID of the targeted update|
| **UpdateInstalledTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | DateTime when event transitioned to UpdateInstalled, else empty. |
| **UpdateManufacturer** | [string](/azure/kusto/query/scalar-data-types/string) | `Microsoft` | Manufacturer of update. Microsoft for feature or quality updates, for drivers the name of driver manufacturer. |
| **UpdateReleaseTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The release date of the update |
| **UpdateSource** | [string](/azure/kusto/query/scalar-data-types/string) | `UUP` | The source of the update such as UUP, MUv6, Media |
<!--8506381-->
|Field |Type | Enumerated type |Example |Description |
|---|---|---|---|---|
| **AzureADDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra Device ID |
| **AzureADTenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID |
| **CatalogId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `b0f410599615e2ce15e6614ac3fc4ec62d80324020351e172edef89091a64f2f` | This field applies to drivers only. The Catalog ID of the update from Windows Update for Business deployment service. |
| **ClientState** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Installing` | This field applies to drivers only. Higher-level bucket of ClientSubstate. |
| **ClientSubstate** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `DownloadStart` | Last-known state of this update relative to the device, from the client. |
| **ClientSubstateRank** | [int](/azure/kusto/query/scalar-data-types/int) | No | `2300` | Ranking of client substates for sequential ordering in funnel-type views. The rankings between ServiceSubstate and ClientSubstate can be used together. |
| **ClientSubstateTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | Date and time of last client substate transition |
| **DeploymentId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `cf1b12a3-3d84-4ce3-bc8e-de48459e252d` | The identifier of the deployment that is targeting this update to this device, else empty. |
| **DeviceName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `JohnPC-Contoso` | Device's given name |
| **EventData** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. Json to fill with arbitrary K/V pairs. Used to populate contextual data that would otherwise be sparsely populated if elevated to a field always present in the schema. |
| **FurthestClientSubstate** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `DownloadComplete` | Furthest clientSubstate |
| **FurthestClientSubstateRank** | [int](/azure/kusto/query/scalar-data-types/int) | No | `2400` | Ranking of furthest clientSubstate |
| **GlobalDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `g:9832741921341` | Microsoft internal global device identifier |
| **IsUpdateHealthy** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `1` | Currently, data isn't gathered to populate this field. True: No issues preventing this device from updating to this update have been found. False: There's something that may prevent this device from updating. |
| **OfferReceivedTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | Date and time when device last reported entering OfferReceived, else empty. |
| **RestartRequiredTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | Date and time when device first reported entering RebootRequired (or RebootPending), else empty. |
| **SCCMClientId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | A string corresponding to the Configuration Manager Client ID on the device. |
| **SourceSystem** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Azure` | |
| **TargetBuild** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `10.0.18363.836` | The full build of the content this DeviceUpdateEvent is tracking. For Windows 10 updates, this value would correspond to the full build (10.0.14393.385). |
| **TargetBuildNumber** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `18363` | Integer of the Major portion of Build. |
| **TargetKBNumber** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `KB4524570` | KB Article. |
| **TargetRevisionNumber** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `836` | Integer or the minor (or revision) portion of the build. |
| **TargetVersion** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `1909` | The target operating system version, such as 1909. |
| **TenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID of the device. |
| **TimeGenerated [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | The time the snapshot generated this specific record. This is to determine to which batch snapshot this record belongs. |
| **Type** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `UCClientUpdateStatus` | The entity type |
| **UpdateCategory** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `WindowsFeatureUpdate` | The type of content this DeviceUpdateEvent is tracking. |
| **UpdateClassification** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Upgrade` | Whether the update classification is an upgrade (feature update), security (quality update), nonsecurity (quality update), or driver |
| **UpdateConnectivityLevel** | | Yes | | Currently, data isn't gathered to populate this field. Whether or not this device is maintaining a sufficiently cumulative and continuous connection to Windows Update so the update can progress optimally. |
| **UpdateDisplayName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Windows 10 1909` | The long-form display name for the given update. Varies on content type (feature update. quality update) |
| **UpdateHealthGroupL1** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. Grouping design to describe the current update installation's "health", L1 (highest-level). |
| **UpdateHealthGroupL2** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. Integer for ranking the L1 UpdateHealthGroup. |
| **UpdateHealthGroupL3** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. Second grouping, subset of L1, more detailed. |
| **UpdateHealthGroupRankL1** | [int](/azure/kusto/query/scalar-data-types/int) | No | | Currently, data isn't gathered to populate this field. Integer for ranking the L2 UpdateHealthGroup. |
| **UpdateHealthGroupRankL2** | [int](/azure/kusto/query/scalar-data-types/int) | No | | Currently, data isn't gathered to populate this field. Third grouping, subset of L3, more detailed. |
| **UpdateHealthGroupRankL3** | [int](/azure/kusto/query/scalar-data-types/int) | No | | Currently, data isn't gathered to populate this field. Integer for ranking the L3 UpdateHealthGroup. |
| **UpdateId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `10e519f0-06ae-4141-8f53-afee63e995f0` | This field applies to drivers only. Update ID of the targeted update |
| **UpdateInstalledTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | DateTime when event transitioned to UpdateInstalled, else empty. |
| **UpdateManufacturer** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Microsoft` | This field applies to drivers only. Manufacturer of update. Microsoft for feature or quality updates, for drivers the name of driver manufacturer. |
| **UpdateReleaseTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020/05/14 09:26:03.478 AM` | The release date of the update |
| **UpdateSource** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `UUP` | The source of the update such as UUP, MUv6, Media |

57
windows/deployment/update/wufb-reports-schema-ucdevicealert.md
View File

@ -11,7 +11,7 @@ manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 06/06/2022
ms.date: 12/06/2023
---
# UCDeviceAlert
@ -19,32 +19,29 @@ ms.date: 06/06/2022
These alerts are activated as a result of an issue that is device-specific. It isn't specific to the combination of a specific update and a specific device. Like UpdateAlerts, the AlertType indicates where the Alert comes from (ServiceDeviceAlert, ClientDeviceAlert). For example, an EndOfService alert is a ClientDeviceAlert, as a build no longer being serviced (EOS) is a client-wide state. Meanwhile, DeviceRegistrationIssues in the Windows Update for Business deployment service will be a ServiceDeviceAlert, as it's a device-wide state in the service to not be correctly registered.
## Schema for UCDeviceAlert
|Field |Type |Example |Description |
|---|---|---|---|
| **AlertClassification** | [string](/azure/kusto/query/scalar-data-types/string) | `Error` | Whether this alert is an Error, a Warning, or Informational |
| **AlertId** | [string](/azure/kusto/query/scalar-data-types/string) | `9e107d9d372bb6826bd81d3542a419d6` | The unique identifier of this alert |
| **AlertRank** | [int](/azure/kusto/query/scalar-data-types/int) | `1000` | Integer ranking of alert for prioritization during troubleshooting |
| **AlertStatus** | [string](/azure/kusto/query/scalar-data-types/string) | `Active` | Whether this alert is Active, Resolved, or Deleted |
| **AlertSubtype** | [string](/azure/kusto/query/scalar-data-types/string) | `DiskFull` | The subtype of alert. |
| **AlertType** | [string](/azure/kusto/query/scalar-data-types/string) | `ClientUpdateAlert` | The type of alert such as ClientUpdateAlert or ServiceUpdateAlert. Indicates which fields will be present. |
| **AzureADDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra device ID of the device, if available. |
| **AzureADTenantId** | [string](/azure/kusto/query/scalar-data-types/string) | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID of the device. |
| **ClientSubstate** | [string](/azure/kusto/query/scalar-data-types/string) | `DownloadStart` | If the alert is from the client, the ClientSubstate at the time this alert was activated or updated, else empty. |
| **ClientSubstateRank** | [int](/azure/kusto/query/scalar-data-types/int) | `2300` | Rank of ClientSubstate |
| **DeploymentId** | [string](/azure/kusto/query/scalar-data-types/string) | `cf1b12a3-3d84-4ce3-bc8e-de48459e252d` | The deployment this alert is relative to, if there's one. |
| **Description** | [string](/azure/kusto/query/scalar-data-types/string) | `Disk full` | A localized string translated from a combination of other alert fields + language preference that describes the issue in detail. |
| **DeviceName** | [string](/azure/kusto/query/scalar-data-types/string) | `JohnPC-Contoso` | The given device's name |
| **GlobalDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `g:1298371934870` | Internal Microsoft global identifier, if available. |
| **Recommendation** | [string](/azure/kusto/query/scalar-data-types/string) | `Free up disk space.` | A localized string translated from RecommendedAction, Message, and other fields (depending on source of alert) that provides a recommended action. |
| **ResolvedTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The time this alert was resolved, else empty. |
| **SCCMClientId** | [string](/azure/kusto/query/scalar-data-types/string) | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | Configuration Manager client ID of the device, if available. |
| **ServiceSubstate** | [string](/azure/kusto/query/scalar-data-types/string) | `OfferReady` | If the alert is from the service, the ServiceSubstate at the time this alert was activated or updated, else Empty. |
| **ServiceSubstateRank** | [int](/azure/kusto/query/scalar-data-types/int) | `100` | Rank of ServiceSubstate |
| **StartTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The time this alert was activated. |
| **TargetBuild** | [string](/azure/kusto/query/scalar-data-types/string) | `18363.836` | The Windows 10 Major. Revision this UpdateAlert is relative to. |
| **TargetVersion** | [string](/azure/kusto/query/scalar-data-types/string) | `1909` | The Windows 10 build this UpdateAlert is relative to. |
| **TimeGenerated** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The time the snapshot generated this specific record. This is to determine to which batch snapshot this record belongs. |
| **Type** | [string](/azure/kusto/query/scalar-data-types/string) | `UpdateAlert` | The entity type. |
| **UpdateCategory** | [string](/azure/kusto/query/scalar-data-types/string) | `WindowsFeatureUpdate` | The type of content this DeviceUpdateEvent is tracking. |
| **UpdateClassification** | [string](/azure/kusto/query/scalar-data-types/string) | `Upgrade` | Whether this content is an upgrade (feature update), security (quality update), non-security (quality update), or driver |
<!--8506381-->
|Field |Type | Enumerated type |Example |Description |
|---|---|---|---|---|
| **AlertClassification** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Error` | Whether this alert is an Error, a Warning, or Informational |
| **AlertData** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. An optional string formatted as a json payload containing metadata for the alert. |
| **AlertId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `9e107d9d372bb6826bd81d3542a419d6` | The unique identifier of this alert |
| **AlertRank** | [int](/azure/kusto/query/scalar-data-types/int) | No | `1000` | Integer ranking of alert for prioritization during troubleshooting |
| **AlertStatus** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Active` | Whether this alert is Active, Resolved, or Deleted |
| **AlertSubtype** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `DiskFull` | The subtype of alert. |
| **AlertType** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `ClientUpdateAlert` | The type of alert such as ClientUpdateAlert or ServiceUpdateAlert. Indicates which fields are present. |
| **AzureADDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra Device ID |
| **AzureADTenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID |
| **Description** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Disk full` | A localized string translated from a combination of other alert fields + language preference that describes the issue in detail. |
| **DeviceName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `JohnPC-Contoso` | The given device's name |
| **ErrorCode** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. The Error Code, if any, that triggered this Alert. In the case of Client-based explicit alerts, error codes can have extended error codes, which are appended to the error code with an underscore separator. |
| **ErrorSymName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. The symbolic name that maps to the Error Code, if any. Otherwise empty. |
| **GlobalDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `g:1298371934870` | Internal Microsoft global identifier, if available. |
| **Recommendation** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Free up disk space.` | A localized string translated from RecommendedAction, Message, and other fields (depending on source of alert) that provides a recommended action. |
| **ResolvedTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The time this alert was resolved, else empty. |
| **SCCMClientId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | Configuration Manager client ID of the device, if available. |
| **SourceSystem** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Azure` | |
| **StartTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The time this alert was activated. |
| **TenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID of the device. |
| **TimeGenerated [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The time the snapshot generated this specific record. This is to determine to which batch snapshot this record belongs. |
| **Type** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `UCDeviceAlert` | The entity type |
| **URL** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `aka.ms/errordetail32152` | Currently, data isn't gathered to populate this field. An optional URL to get more in-depth information related to this alert. |

2
windows/deployment/update/wufb-reports-schema-ucdoaggregatedstatus.md
View File

@ -12,7 +12,7 @@ ms.reviewer: carmenf
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 11/17/2022
ms.date: 12/06/2023
---
# UCDOAggregatedStatus

2
windows/deployment/update/wufb-reports-schema-ucdostatus.md
View File

@ -11,7 +11,7 @@ ms.reviewer: carmenf
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 11/17/2022
ms.date: 12/06/2023
---
# UCDOStatus

75
windows/deployment/update/wufb-reports-schema-ucserviceupdatestatus.md
View File

@ -11,7 +11,7 @@ manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 06/06/2022
ms.date: 12/06/2023
---
# UCServiceUpdateStatus
@ -19,38 +19,41 @@ ms.date: 06/06/2022
Update Event that comes directly from the service-side. The event has only service-side information for one device (client), and one update, in one deployment. This event has certain fields removed from it in favor of being able to show data in near real time.
## Schema for UCServiceUpdateStatus
| Field | Type | Example | Description |
|---|---|---|---|
| **AzureADDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | If this DeviceUpdateEvent is from content deployed by a deployment scheduler service policy, this GUID will map to that policy, otherwise it will be empty. |
| **AzureADTenantId** | [string](/azure/kusto/query/scalar-data-types/string) | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | A GUID corresponding to the Microsoft Entra tenant to which the device belongs. |
|**CatalogId** | [string](/azure/kusto/query/scalar-data-types/string) | `b0f410599615e2ce15e6614ac3fc4ec62d80324020351e172edef89091a64f2f` | The update catalog ID |
| **DeploymentApprovedTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2022-05-14 09:26:03.478039` | Date and time of the update approval |
| **DeploymentId** | [string](/azure/kusto/query/scalar-data-types/string) |`cf1b12a3-3d84-4ce3-bc8e-de48459e252d` | If this DeviceUpdateEvent is from content deployed by a deployment scheduler service policy, this GUID will map to that policy, otherwise it will be empty. |
| **DeploymentName** | [string](/azure/kusto/query/scalar-data-types/string) |`My deployment` | Friendly name of the created deployment |
| **DeploymentIsExpedited** | [bool](/azure/data-explorer/kusto/query/scalar-data-types/bool) | `1` | Whether the content is being expedited |
| **DeploymentRevokeTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2022-05-14 09:26:03.478039` | Date and time the update was revoked |
| **GlobalDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `g:9832741921341` | Microsoft internal global device identifier |
| **OfferReadyTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | DateTime of OfferReady transition. If empty, not yet been offered. |
| **PolicyCreatedTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | Date and time the policy was created |
| **PolicyId** | [string](/azure/kusto/query/scalar-data-types/string) | `9011c330-1234-5678-9abc-def012345678` | The policy identifier targeting the update to this device |
| **PolicyName** | [string](/azure/kusto/query/scalar-data-types/string) | `My policy` | Friendly name of the policy |
| **ServiceState** | [string](/azure/kusto/query/scalar-data-types/string) | `Offering` | High-level state of update's status relative to device, service-side. |
| **ServiceSubstate** | [string](/azure/kusto/query/scalar-data-types/string) | `OfferReady` | Low-level state of update's status relative to device, service-side. |
| **ServiceSubstateTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | Date and time of last ServiceSubstate transition. |
| **SourceSystem** | [string](/azure/kusto/query/scalar-data-types/string)| `Azure`| |
| **TargetBuild** | [string](/azure/kusto/query/scalar-data-types/string) | `10.0.18363.836` | The full build for the content this event is tracking. For Windows 10, this string corresponds to "10.0.Build.Revision" |
| **TargetVersion** | [int](/azure/kusto/query/scalar-data-types/int) | `1909` | The version of content this DeviceUpdateEvent is tracking. For Windows 10 updates, this number would correspond to the year/month version format used, such as 1903. |
| **TenantId** | [string](/azure/kusto/query/scalar-data-types/string) | `9011c330-1234-5678-9abc-def012345678` | Microsoft Entra tenant ID |
| **TimeGenerated** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | Time the snapshot ran can also be the same as EventDateTimeUTC in some cases. |
| **Type** | [string](/azure/kusto/query/scalar-data-types/string) | `ServiceUpdateEvent` | The EntityType |
| **UpdateCategory** | [string](/azure/kusto/query/scalar-data-types/string) | `WindowsFeatureUpdate` | The type of content this DeviceUpdateEvent is tracking. |
| **UpdateClassification** | [string](/azure/kusto/query/scalar-data-types/string) | `Upgrade` | Whether this update is an upgrade (feature update), security (quality update), non-security (quality update), or driver |
| **UpdateDisplayName** | [string](/azure/kusto/query/scalar-data-types/string) | `Windows 10 1909` | The long-form display name for the given update. Varies on content type (feature update. quality update) |
| **UpdateId** | [string](/azure/kusto/query/scalar-data-types/string) | `10e519f0-06ae-4141-8f53-afee63e995f0` |Update ID of the targeted update|
| **UpdateManufacturer** | [string](/azure/kusto/query/scalar-data-types/string) | `Microsoft` | Manufacturer of update. Microsoft for feature or quality updates, for drivers the name of driver manufacturer. |
|**UpdateProvider** | [string](/azure/kusto/query/scalar-data-types/string) | `Microsoft` | Update provider of drivers and firmware |
| **UpdateRecommendedTime** |[datetime](/azure/kusto/query/scalar-data-types/datetime) | `2022-05-14 09:26:03.478039` | Date and time when the update was recommended to the device |
| **UpdateReleaseTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The release date of the update |
|**UpdateVersion** | [string](/azure/kusto/query/scalar-data-types/string) | `20.0.19.3` | Update version of drivers or firmware |
| **UpdateVersionTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | Update version date time stamp for drivers and firmware |
<!--8506381-->
| Field |Type | Enumerated type |Example |Description |
|---|---|---|---|---|
| **AzureADDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra Device ID |
| **AzureADTenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID |
| **CatalogId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `b0f410599615e2ce15e6614ac3fc4ec62d80324020351e172edef89091a64f2f` | This field applies to drivers only. The Catalog ID of the update from Windows Update for Business deployment service. |
| **DeploymentApprovedTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | This field applies to drivers only. Date and time of the update approval |
| **DeploymentId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `cf1b12a3-3d84-4ce3-bc8e-de48459e252d` | If this DeviceUpdateEvent is from content deployed by a deployment scheduler service policy, this GUID maps to that policy, otherwise it's empty. |
| **DeploymentIsExpedited** | [bool](/azure/data-explorer/kusto/query/scalar-data-types/bool) | No | `1` | Currently, data isn't gathered to populate this field. It indicated whether the content is being expedited |
| **DeploymentName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `My deployment` | Currently, data isn't gathered to populate this field. Friendly name of the created deployment |
| **DeploymentRevokeTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | This field applies to drivers only. Date and time the update was revoked |
| **GlobalDeviceId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `g:9832741921341` | Currently, data isn't gathered to populate this field. Microsoft internal global device identifier |
| **OfferReadyTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | DateTime of OfferReady transition. If empty, not yet been offered. |
| **PolicyCreatedTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | This field applies to drivers only. Date and time the policy was created |
| **PolicyId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `9011c330-1234-5678-9abc-def012345678` | This field applies to drivers only. The policy identifier targeting the update to this device |
| **PolicyName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `My policy` | Currently, data isn't gathered to populate this field. This field applies to drivers only. Friendly name of the policy. |
| **ProjectedOfferReadyTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | Projected time update will be offered to device. If empty, unknown. |
| **ServiceState** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Offering` | High-level state of update's status relative to device, service-side. |
| **ServiceSubstate** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `OfferReady` | Low-level state of update's status relative to device, service-side. |
| **ServiceSubstateRank** | [int](/azure/kusto/query/scalar-data-types/int) | No | | Currently, data isn't gathered to populate this field. Ranking of Substates for sequential ordering in funnel-type views. The rankings between ServiceSubstate and ClientSubstate can be used together. |
| **ServiceSubstateTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | Date and time of last ServiceSubstate transition. |
| **SourceSystem** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Azure` | |
| **TargetBuild** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `10.0.18363.836` | The full build for the content this event is tracking. For Windows 10, this string corresponds to "10.0.Build.Revision" |
| **TargetVersion** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `1909` | The version of content this DeviceUpdateEvent is tracking. For Windows 10 updates, this number would correspond to the year/month version format used, such as 1903. |
| **TenantId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `9011c330-1234-5678-9abc-def012345678` | Microsoft Entra tenant ID |
| **TimeGenerated [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | | `2020-05-14 09:26:03.478039` | Time the snapshot ran can also be the same as EventDateTimeUTC in some cases. |
| **Type** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `UCServiceUpdateStatus` | The entity type |
| **UdpateIsSystemManifest** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | | Currently, data isn't gathered to populate this field. This field applies to drivers only. |
| **UpdateCategory** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `WindowsFeatureUpdate` | The type of content this DeviceUpdateEvent is tracking. |
| **UpdateClassification** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Upgrade` | Whether this update is an upgrade (feature update), security (quality update), nonsecurity (quality update), or driver |
| **UpdateDisplayName** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Windows 10 1909` | The long-form display name for the given update. Varies on content type (feature update. quality update) |
| **UpdateId** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `10e519f0-06ae-4141-8f53-afee63e995f0` | This field applies to drivers only. Update ID of the targeted update |
| **UpdateManufacturer** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Microsoft` | This field applies to drivers only. Manufacturer of update. Microsoft for feature or quality updates, for drivers the name of driver manufacturer. |
| **UpdateProvider** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Microsoft` | This field applies to drivers only. Update provider of drivers and firmware |
| **UpdateRecommendedTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | This field applies to drivers only. Date and time when the update was recommended to the device |
| **UpdateReleaseTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | Currently, data isn't gathered to populate this field. The release date of the update |
| **UpdateVersion** | [string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `20.0.19.3` | This field applies to drivers only. Update version of drivers or firmware |
| **UpdateVersionTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | This field applies to drivers only. Update version date time stamp for drivers and firmware |

71
windows/deployment/update/wufb-reports-schema-ucupdatealert.md
View File

@ -11,7 +11,7 @@ manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 06/06/2022
ms.date: 12/06/2023
---
# UCUpdateAlert
@ -20,36 +20,39 @@ Alert for both client and service updates. Contains information that needs atten
## Schema for UCUpdateAlert
|Field |Type |Example |Description |
|---|---|---|---|
| **AlertClassification** | [string](/azure/kusto/query/scalar-data-types/string) | `Error` | Whether this alert is an Error, a Warning, or Informational |
| **AlertData** | [string](/azure/kusto/query/scalar-data-types/string) {json} | `{ "freeDiskCapacityMb": 3213, "contentSizeMb": 4381}` | An optional string formatted as a json payload containing metadata for the alert. |
| **AlertId** | [string](/azure/kusto/query/scalar-data-types/string) | `9e107d9d372bb6826bd81d3542a419d6` | The unique identifier of this alert |
| **AlertRank** | [int](/azure/kusto/query/scalar-data-types/int) | `1000` | Integer ranking of alert for prioritization during troubleshooting |
| **AlertStatus** | [string](/azure/kusto/query/scalar-data-types/string) | `Active` | Whether this alert is Active, Resolved, or Deleted |
| **AlertSubtype** | [string](/azure/kusto/query/scalar-data-types/string) | `DiskFull` | The subtype of alert |
| **AlertType** | [string](/azure/kusto/query/scalar-data-types/string) | `ClientUpdateAlert` | The type of alert such as ClientUpdateAlert or ServiceUpdateAlert. Indicates which fields will be present |
| **AzureADDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra device ID of the device, if available. |
| **AzureADTenantId** | [string](/azure/kusto/query/scalar-data-types/string) | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID of the device. |
| **ClientSubstate** | [string](/azure/kusto/query/scalar-data-types/string) | `DownloadStart` | If the alert is from the client, the ClientSubstate at the time this alert was activated or updated, else empty. |
| **ClientSubstateRank** | [int](/azure/kusto/query/scalar-data-types/int) | `2300` | Rank of ClientSubstate |
| **DeploymentId** | [string](/azure/kusto/query/scalar-data-types/string) | `cf1b12a3-3d84-4ce3-bc8e-de48459e252d` | The deployment this alert is relative to, if there's one. |
| **Description** | [string](/azure/kusto/query/scalar-data-types/string) | `Disk full` | A localized string translated from a combination of other Alert fields + language preference that describes the issue in detail. |
| **DeviceName** | [string](/azure/kusto/query/scalar-data-types/string) | `JohnPC-Contoso` | The given device's name |
| **ErrorCode** | [string](/azure/kusto/query/scalar-data-types/string) | `0x8326CFA2D_C3FD` | The error code, if any, that triggered this alert. In the case of client-based explicit alerts, error codes can have extended error codes, which are appended to the error code with an underscore separator. |
| **ErrorSymName** | [string](/azure/kusto/query/scalar-data-types/string) | `WU_E_DISK_FULL` | The symbolic name that maps to the error code, if any, otherwise empty. |
| **GlobalDeviceId** | [string](/azure/kusto/query/scalar-data-types/string) | `g:1298371934870` | Internal Microsoft Global identifier, if available. |
| **Recommendation** | [string](/azure/kusto/query/scalar-data-types/string) | `Free up disk space.` | A localized string translated from RecommendedAction, Message, and other fields (depending on the source of the alert) that provides a recommended action. |
| **ResolvedTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The time this alert was resolved, else empty. |
| **SCCMClientId** | [string](/azure/kusto/query/scalar-data-types/string) | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | Configuration Manager client ID of the device, if available. |
| **ServiceSubstate** | [string](/azure/kusto/query/scalar-data-types/string) | `OfferReady` | If the alert is from the service, the ServiceSubstate at the time this alert was activated or updated, else empty. |
| **StartTime** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The time this alert was activated. |
| **TargetBuild** | [string](/azure/kusto/query/scalar-data-types/string) | `18363.836` | The Windows 10 Major. Revision this UpdateAlert is relative to. |
| **TargetVersion** | [string](/azure/kusto/query/scalar-data-types/string) | `1909` | The Windows 10 build this UpdateAlert is relative to. |
| **TenantId** |[string](/azure/kusto/query/scalar-data-types/string) | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID of the device. |
| **TimeGenerated** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | `2020-05-14 09:26:03.478039` | The time the snapshot generated this specific record. This is to determine to which batch snapshot this record belongs. |
| **Type** | [string](/azure/kusto/query/scalar-data-types/string) | `UpdateAlert` | The entity type. |
| **UpdateCategory** | [string](/azure/kusto/query/scalar-data-types/string) | `WindowsFeatureUpdate` | The type of content this DeviceUpdateEvent is tracking. |
| **UpdateClassification** | [string](/azure/kusto/query/scalar-data-types/string) | `Upgrade` | Whether this update is an upgrade (feature update), security (quality update), non-security (quality update), or driver |
| **URL** | [string](/azure/kusto/query/scalar-data-types/string) | `aka.ms/errordetail32152` | An optional URL to get more in-depth information related to this alert. |
| **UpdateId** | [string](/azure/kusto/query/scalar-data-types/string) | `10e519f0-06ae-4141-8f53-afee63e995f0` |Update ID of the targeted update|
|Field |Type | ENUM <!--8506381--> |Example |Description |
|---|---|---|---|---|
| **AlertClassification** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Error` | Whether this alert is an error, a warning, or informational |
| **AlertData** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `{ "freeDiskCapacityMb": 3213, "contentSizeMb": 4381}` | An optional string formatted as a json payload containing metadata for the alert. |
| **AlertId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `9e107d9d372bb6826bd81d3542a419d6` | The unique identifier of this alert |
| **AlertRank** |[int](/azure/kusto/query/scalar-data-types/int) | No | `1000` | Integer ranking of alert for prioritization during troubleshooting |
| **AlertStatus** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Active` | Whether this alert is active, resolved, or deleted |
| **AlertSubtype** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `DiskFull` | The subtype of alert |
| **AlertType** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `ClientUpdateAlert` | The type of alert such as ClientUpdateAlert or ServiceUpdateAlert. Indicates which fields are present. |
| **AzureADDeviceId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `71db1a1a-f1a6-4a25-b88f-79c2f513dae0` | Microsoft Entra Device ID |
| **AzureADTenantId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID |
| **CatalogId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `b0f410599615e2ce15e6614ac3fc4ec62d80324020351e172edef89091a64f2f` | This field applies to drivers only. The Catalog ID of the update from Windows Update for Business deployment service. |
| **ClientSubstate** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `DownloadStart` | If the alert is from the client, the ClientSubstate at the time this alert was activated or updated, else empty. |
| **ClientSubstateRank** |[int](/azure/kusto/query/scalar-data-types/int) | No | `2300` | Rank of ClientSubstate |
| **DeploymentId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `cf1b12a3-3d84-4ce3-bc8e-de48459e252d` | The deployment this alert is relative to, if there's one. |
| **Description** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Disk full` | A localized string translated from a combination of other Alert fields + language preference that describes the issue in detail. |
| **DeviceName** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `JohnPC-Contoso` | The given device's name |
| **ErrorCode** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `0x8326CFA2D_C3FD` | The error code, if any, that triggered this alert. In the case of client-based explicit alerts, error codes can have extended error codes, which are appended to the error code with an underscore separator. |
| **ErrorSymName** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `WU_E_DISK_FULL` | The symbolic name that maps to the error code, if any, otherwise empty. |
| **GlobalDeviceId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `g:1298371934870` | Internal Microsoft Global identifier, if available. |
| **Recommendation** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Free up disk space.` | A localized string translated from RecommendedAction, Message, and other fields (depending on the source of the alert) that provides a recommended action. |
| **ResolvedTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The time this alert was resolved, else empty. |
| **SCCMClientId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `5AB72FAC-93AB-4954-9AB0-6557D0EFA245` | Configuration manager client ID of the device, if available. |
| **ServiceSubstate** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `OfferReady` | If the alert is from the service, the ServiceSubstate at the time this alert was activated or updated, else empty. |
| **ServiceSubstateRank** |[int](/azure/kusto/query/scalar-data-types/int) | No | | Rank of 'ClientSubstate' |
| **SourceSystem** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `Azure` | |
| **StartTime [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The time this alert was activated. |
| **TargetBuild** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `18363.836` | The Windows 10 Major. Revision this 'UpdateAlert' is relative to. |
| **TargetVersion** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `1909` | The Windows 10 build this UpdateAlert is relative to. |
| **TenantId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `69ca04b0-703d-4b3a-9184-c4e3c15d6f5e` | Microsoft Entra tenant ID of the device. |
| **TimeGenerated [UTC]** | [datetime](/azure/kusto/query/scalar-data-types/datetime) | No | `2020-05-14 09:26:03.478039` | The time the snapshot generated this specific record. This is to determine to which batch snapshot this record belongs. |
| **Type** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `UCUpdateAlert` | The entity type |
| **UpdateCategory** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `WindowsFeatureUpdate` | The type of content this DeviceUpdateEvent is tracking. |
| **UpdateClassification** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | Yes | `Upgrade` | Whether this update is an upgrade (feature update), security (quality update), nonsecurity (quality update), or driver |
| **UpdateId** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `10e519f0-06ae-4141-8f53-afee63e995f0` | This field applies to drivers only. The Update ID of the targeted update. |
| **URL** |[string](/azure/data-explorer/kusto/query/scalar-data-types/string) | No | `aka.ms/errordetail32152` | An optional URL to get more in-depth information related to this alert. |

2
windows/deployment/update/wufb-reports-schema.md
View File

@ -11,7 +11,7 @@ manager: aaroncz
appliesto:
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>
- ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>
ms.date: 11/15/2022
ms.date: 12/06/2023
---
# Windows Update for Business reports schema

129
windows/deployment/upgrade/log-files.md
View File

@ -1,6 +1,6 @@
---
title: Log files and resolving upgrade errors
description: Learn how to interpret and analyze the log files that are generated during the Windows 10 upgrade process.
description: Learn how to interpret and analyze the log files that are generated during the Windows upgrade process.
ms.prod: windows-client
author: frankroj
manager: aaroncz
@ -11,107 +11,103 @@ ms.collection:
- highpri
- tier2
ms.technology: itpro-deploy
ms.date: 10/28/2022
ms.date: 01/18/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Windows upgrade log files
**Applies to**
> [!NOTE]
>
> This article is a 400-level article (advanced).
>
> See [Resolve Windows upgrade errors](resolve-windows-upgrade-errors.md) for a full list of articles in this section.
- Windows 10
Several log files are created during each phase of the upgrade process. These log files are essential for troubleshooting upgrade problems. By default, the folders that contain these log files are hidden on the upgrade target computer. To view the log files, configure Windows Explorer to view hidden items, or use a tool to automatically gather these logs. The most useful log is **setupact.log**. The log files are located in a different folder depending on the Windows Setup phase. Recall that the phase can be determined from the extend code.
> [!NOTE]
> This is a 400-level topic (advanced).<br>
> See [Resolve Windows 10 upgrade errors](resolve-windows-10-upgrade-errors.md) for a full list of topics in this article.
Several log files are created during each phase of the upgrade process. These log files are essential for troubleshooting upgrade problems. By default, the folders that contain these log files are hidden on the upgrade target computer. To view the log files, configure Windows Explorer to view hidden items, or use a tool to automatically gather these logs. The most useful log is **setupact.log**. The log files are located in a different folder depending on the Windows Setup phase. Recall that you can determine the phase from the extend code.
> [!NOTE]
> Also see the [Windows Error Reporting](windows-error-reporting.md) section in this document for help locating error codes and log files.
The following table describes some log files and how to use them for troubleshooting purposes:
>
> Also see the [Windows Error Reporting](windows-error-reporting.md) article in this section for help with locating error codes and log files.
The following table describes some log files and how to use them for troubleshooting purposes:
|Log file |Phase: Location |Description |When to use|
|---|---|---|---|
|setupact.log|Down-Level:<br>$Windows.~BT\Sources\Panther|Contains information about setup actions during the downlevel phase. |All down-level failures and starting point for rollback investigations.<br> Setup.act is the most important log for diagnosing setup issues.|
|setupact.log|OOBE:<br>$Windows.~BT\Sources\Panther\UnattendGC|Contains information about actions during the OOBE phase.|Investigating rollbacks that failed during OOBE phase and operations - 0x4001C, 0x4001D, 0x4001E, 0x4001F.|
|setupact.log|Rollback:<br>$Windows.~BT\Sources\Rollback|Contains information about actions during rollback.|Investigating generic rollbacks - 0xC1900101.|
|setupact.log|Pre-initialization (prior to downlevel):<br>Windows|Contains information about initializing setup.|If setup fails to launch.|
|setupact.log|Post-upgrade (after OOBE):<br>Windows\Panther|Contains information about setup actions during the installation.|Investigate post-upgrade related issues.|
|setuperr.log|Same as setupact.log|Contains information about setup errors during the installation.|Review all errors encountered during the installation phase.|
|miglog.xml|Post-upgrade (after OOBE):<br>Windows\Panther|Contains information about what was migrated during the installation.|Identify post upgrade data migration issues.|
|BlueBox.log|Down-Level:<br>Windows\Logs\Mosetup|Contains information communication between `setup.exe` and Windows Update.|Use during WSUS and Windows Update down-level failures or for 0xC1900107.|
|Supplemental rollback logs:<br>Setupmem.dmp<br>setupapi.dev.log<br>Event logs (*.evtx)|$Windows.~BT\Sources\Rollback|Additional logs collected during rollback.|Setupmem.dmp: If OS bug checks during upgrade, setup will attempt to extract a mini-dump.<br>Setupapi: Device install issues - 0x30018<br>Event logs: Generic rollbacks (0xC1900101) or unexpected reboots.|
|**setupact.log**|Down-Level:<br>$Windows.~BT\Sources\Panther|Contains information about setup actions during the downlevel phase. |All down-level failures and starting point for rollback investigations.<br> Setup.act is the most important log for diagnosing setup issues.|
|**setupact.log**|OOBE:<br>$Windows.~BT\Sources\Panther\UnattendGC|Contains information about actions during the OOBE phase.|Investigating rollbacks that failed during OOBE phase and operations - 0x4001C, 0x4001D, 0x4001E, 0x4001F.|
|**setupact.log**|Rollback:<br>$Windows.~BT\Sources\Rollback|Contains information about actions during rollback.|Investigating generic rollbacks - 0xC1900101.|
|**setupact.log**|Pre-initialization (prior to downlevel):<br>Windows|Contains information about initializing setup.|If setup fails to launch.|
|**setupact.log**|Post-upgrade (after OOBE):<br>Windows\Panther|Contains information about setup actions during the installation.|Investigate post-upgrade related issues.|
|**setuperr.log**|Same as setupact.log|Contains information about setup errors during the installation.|Review all errors encountered during the installation phase.|
|**miglog.xml**|Post-upgrade (after OOBE):<br>Windows\Panther|Contains information about what was migrated during the installation.|Identify post upgrade data migration issues.|
|**BlueBox.log**|Down-Level:<br>Windows\Logs\Mosetup|Contains information communication between `setup.exe` and Windows Update.|Use during WSUS and Windows Update down-level failures or for 0xC1900107.|
|Supplemental rollback logs:<br>**Setupmem.dmp**<br>**setupapi.dev.log**<br>Event logs (*.evtx)|$Windows.~BT\Sources\Rollback|Additional logs collected during rollback.|Setupmem.dmp: If OS bug checks during upgrade, setup attempts to extract a mini-dump.<br>Setupapi: Device install issues - 0x30018<br>Event logs: Generic rollbacks (0xC1900101) or unexpected reboots.|
## Log entry structure
A setupact.log or setuperr.log entry (files are located at C:\Windows) includes the following elements:
A `setupact.log` or `setuperr.log` entry includes the following elements:
1. **The date and time** - 2016-09-08 09:20:05
1. **The date and time** - 2023-09-08 09:20:05
1. **The log level** - Info, Warning, Error, Fatal Error
2. **The log level** - Info, Warning, Error, Fatal Error
1. **The logging component** - CONX, MOUPG, PANTHR, SP, IBSLIB, MIG, DISM, CSI, CBS
The logging components SP (setup platform), MIG (migration engine), and CONX (compatibility information) are useful for troubleshooting Windows Setup errors.
3. **The logging component** - CONX, MOUPG, PANTHR, SP, IBSLIB, MIG, DISM, CSI, CBS
The logging components SP (setup platform), MIG (migration engine), and CONX (compatibility information) are useful for troubleshooting Windows Setup errors.
4. **The message** - Operation completed successfully.
1. **The message** - Operation completed successfully.
See the following example:
| Date/Time | Log level | Component | Message |
|------|------------|------------|------------|
|2016-09-08 09:23:50,| Warning | MIG | Couldn't replace object C:\Users\name\Cookies. Target Object can't be removed.|
|2023-09-08 09:23:50,| Warning | MIG | Couldn't replace object C:\Users\name\Cookies. Target Object can't be removed.|
## Analyze log files
The following instructions are meant for IT professionals. Also see the [Upgrade error codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json) section in this guide to familiarize yourself with [result codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#result-codes) and [extend codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#extend-codes).
The following instructions are meant for IT professionals. Also see the [Upgrade error codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json) section in this guide to become familiar with [result codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#result-codes) and [extend codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#extend-codes).
To analyze Windows Setup log files:
1. Determine the Windows Setup error code. This code should be returned by Windows Setup if it isn't successful with the upgrade process.
1. Determine the Windows Setup error code. Windows Setup should return an error code if it isn't successful with the upgrade process.
2. Based on the [extend code](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#extend-codes) portion of the error code, determine the type and location of a log file to investigate.
1. Based on the [extend code](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#extend-codes) portion of the error code, determine the type and location of a log file to investigate.
3. Open the log file in a text editor, such as notepad.
1. Open the log file in a text editor, such as notepad.
4. Using the [result code](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#result-codes) portion of the Windows Setup error code, search for the result code in the file and find the last occurrence of the code. Alternatively search for the "abort" and abandoning" text strings described in step 7 below.
1. Using the [result code](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#result-codes) portion of the Windows Setup error code, search for the result code in the file and find the last occurrence of the code. Alternatively search for the "abort" and abandoning" text strings described in step 7 below.
5. To find the last occurrence of the result code:
1. To find the last occurrence of the result code:
1. Scroll to the bottom of the file and select after the last character.
2. Select **Edit**.
3. Select **Find**.
4. Type the result code.
5. Under **Direction** select **Up**.
6. Select **Find Next**.
1. Select **Edit**.
1. Select **Find**.
1. Type the result code.
1. Under **Direction** select **Up**.
1. Select **Find Next**.
6. When you've located the last occurrence of the result code, scroll up a few lines from this location in the file and review the processes that failed prior to generating the result code.
1. When the last occurrence of the result code is located, scroll up a few lines from this location in the file and review the processes that failed prior to generating the result code.
7. Search for the following important text strings:
1. Search for the following important text strings:
- `Shell application requested abort`
- `Abandoning apply due to error for object`
8. Decode Win32 errors that appear in this section.
1. Decode Win32 errors that appear in this section.
9. Write down the timestamp for the observed errors in this section.
1. Write down the timestamp for the observed errors in this section.
10. Search other log files for additional information matching these timestamps or errors.
1. Search other log files for additional information matching these timestamps or errors.
For example, assume that the error code for an error is 0x8007042B - 0x2000D. Searching for "8007042B" reveals the following content from the setuperr.log file:
For example, assume that the error code for an error is **0x8007042B - 0x2000D**. Searching for **8007042B** reveals the following content from the `setuperr.log` file:
> [!NOTE]
> Some lines in the text below are shortened to enhance readability. For example
>
> - The date and time at the start of each line (ex: 2016-10-05 15:27:08) is shortened to minutes and seconds
>
> Some lines in the following text are shortened to enhance readability. For example
>
> - The date and time at the start of each line (ex: 2023-10-05 15:27:08) is shortened to minutes and seconds
> - The certificate file name, which is a long text string, is shortened to just "CN."
**setuperr.log** content:
@ -127,20 +123,20 @@ For example, assume that the error code for an error is 0x8007042B - 0x2000D. Se
27:09, Error SP CSetupPlatformPrivate::Execute: Execution of operations queue failed, abandoning. Error: 0x8007042B[gle=0x000000b7]
```
The first line indicates there was an error **0x00000570** with the file **C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18 [CN]** (shown below):
The first line indicates there was an error **0x00000570** with the file **C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18 [CN]**:
```console
27:08, Error SP Error READ, 0x00000570 while gathering/applying object: File, C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18 [CN]. Will return 0[gle=0x00000570]
```
The error 0x00000570 is a [Win32 error code](/openspecs/windows_protocols/ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d) corresponding to: ERROR_FILE_CORRUPT: The file or directory is corrupted and unreadable.
The error **0x00000570** is a [Win32 error code](/openspecs/windows_protocols/ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d) corresponding to: **ERROR_FILE_CORRUPT: The file or directory is corrupted and unreadable**.
Therefore, Windows Setup failed because it wasn't able to migrate the corrupt file **C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18\[CN]**. This file is a local system certificate and can be safely deleted. Searching the setupact.log file for more details, the phrase "Shell application requested abort" is found in a location with the same timestamp as the lines in setuperr.log. This confirms our suspicion that this file is the cause of the upgrade failure:
Therefore, Windows Setup failed because it wasn't able to migrate the corrupt file **C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18\[CN]**. This file is a local system certificate and can be safely deleted. After the `setupact.log` file is searched for more details, the phrase **Shell application requested abort** is found in a location with the same timestamp as the lines in `setuperr.log`. This analysis confirms the suspicion that this file is the cause of the upgrade failure:
**setupact.log** content:
```console
27:00, Info Gather started at 10/5/2016 23:27:00
27:00, Info Gather started at 10/5/2023 23:27:00
27:00, Info [0x080489] MIG Setting system object filter context (System)
27:00, Info [0x0803e5] MIG Not unmapping HKCU\Software\Classes; it is not mapped
27:00, Info [0x0803e5] MIG Not unmapping HKCU; it is not mapped
@ -157,7 +153,7 @@ Therefore, Windows Setup failed because it wasn't able to migrate the corrupt fi
27:08, Info MIG COutOfProcPluginFactory::LaunchSurrogateHost::CommandLine: -shortened-
27:08, Info MIG COutOfProcPluginFactory::LaunchSurrogateHost: Successfully launched host and got control object.
27:08, Error Gather failed. Last error: 0x00000000
27:08, Info Gather ended at 10/5/2016 23:27:08 with result 44
27:08, Info Gather ended at 10/5/2023 23:27:08 with result 44
27:08, Info Leaving MigGather method
27:08, Error SP SPDoFrameworkGather: Gather operation failed. Error: 0x0000002C
```
@ -166,7 +162,7 @@ Therefore, Windows Setup failed because it wasn't able to migrate the corrupt fi
```console
>>> [Device Install (UpdateDriverForPlugAndPlayDevices) - PCI\VEN_8086&DEV_8C4F]
>>> Section start 2019/09/26 20:13:01.623
>>> Section start 2023/09/26 20:13:01.623
cmd: rundll32.exe "C:\WINDOWS\Installer\MSI6E4C.tmp",zzzzInvokeManagedCustomActionOutOfProc SfxCA_95972906 484 ChipsetWiX.CustomAction!Intel.Deployment.ChipsetWiX.CustomActions.InstallDrivers
ndv: INF path: C:\WINDOWS\TEMP\{15B1CD41-69F5-48EA-9F45-0560A40FE2D8}\Drivers\lynxpoint\LynxPointSystem.inf
ndv: Install flags: 0x00000000
@ -250,15 +246,12 @@ Therefore, Windows Setup failed because it wasn't able to migrate the corrupt fi
<<< [Exit status: FAILURE(0xC1900101)]
```
This analysis indicates that the Windows upgrade error can be resolved by deleting the C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18\[CN] file.
This analysis indicates that the Windows upgrade error can be resolved by deleting the `C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18\[CN]` file.
> [!NOTE]
> In this example, the full, unshortened file name is C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18\be8228fb2d3cb6c6b0ccd9ad51b320b4_a43d512c-69f2-42de-aef9-7a88fabdaa3f.
>
> In this example, the full file name is `C:\ProgramData\Microsoft\Crypto\RSA\S-1-5-18\be8228fb2d3cb6c6b0ccd9ad51b320b4_a43d512c-69f2-42de-aef9-7a88fabdaa3f`.
## Related articles
[Windows 10 FAQ for IT professionals](../planning/windows-10-enterprise-faq-itpro.yml)
<br>[Windows 10 Enterprise system requirements](https://technet.microsoft.com/windows/dn798752.aspx)
<br>[Windows 10 Specifications](https://www.microsoft.com/windows/Windows-10-specifications)
<br>[Windows 10 IT pro forums](https://social.technet.microsoft.com/Forums/en-US/home?category=Windows10ITPro)
<br>[Fix Windows Update errors by using the DISM or System Update Readiness tool](/troubleshoot/windows-server/deployment/fix-windows-update-errors)
- [Fix Windows Update errors by using the DISM or System Update Readiness tool](/troubleshoot/windows-server/deployment/fix-windows-update-errors).

61
windows/deployment/upgrade/resolve-windows-10-upgrade-errors.md
View File

@ -1,61 +0,0 @@
---
title: Resolve Windows 10 upgrade errors - Windows IT Pro
manager: aaroncz
ms.author: frankroj
description: Resolve Windows 10 upgrade errors for ITPros. Technical information for IT professionals to help diagnose Windows setup errors.
ms.prod: windows-client
author: frankroj
ms.localizationpriority: medium
ms.topic: article
ms.technology: itpro-deploy
ms.date: 10/28/2022
---
# Resolve Windows 10 upgrade errors: Technical information for IT Pros
**Applies to**
- Windows 10
>[!IMPORTANT]
>This article contains technical instructions for IT administrators. If you are not an IT administrator, try some of the [quick fixes](/troubleshoot/windows-client/deployment/windows-10-upgrade-quick-fixes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json) described in this article then contact [Microsoft Support](https://support.microsoft.com/contactus/) starting with the Virtual Agent. To talk to a person about your issue, click **Get started** to interact with the Virtual Agent, then enter "Talk to a person" two times. The Virtual Agent can also help you to resolve many Windows upgrade issues. Also see: [Get help with Windows 10 upgrade and installation errors](https://support.microsoft.com/help/10587/windows-10-get-help-with-upgrade-installation-errors) and [Submit Windows 10 upgrade errors using Feedback Hub](submit-errors.md).
This article contains a brief introduction to Windows 10 installation processes, and provides resolution procedures that IT administrators can use to resolve issues with Windows 10 upgrade.
The article has been divided into subtopics of different technical levels. Basic level provides common procedures that can resolve several types of upgrade errors. Advanced level requires some experience with detailed troubleshooting methods.
The following four levels are assigned:
Level 100: Basic <br>
Level 200: Moderate <br>
Level 300: Moderate advanced <br>
Level 400: Advanced <br>
## In this guide
See the following topics in this article:
- [Quick fixes](/troubleshoot/windows-client/deployment/windows-10-upgrade-quick-fixes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json): \Level 100\ Steps you can take to eliminate many Windows upgrade errors.<br>
- [SetupDiag](setupdiag.md): \Level 300\ SetupDiag is a new tool to help you isolate the root cause of an upgrade failure.
- [Troubleshooting upgrade errors](/troubleshoot/windows-client/deployment/windows-10-upgrade-issues-troubleshooting?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json): \Level 300\ General advice and techniques for troubleshooting Windows 10 upgrade errors, and an explanation of phases used during the upgrade process.<br>
- [Windows Error Reporting](windows-error-reporting.md): \Level 300\ How to use Event Viewer to review details about a Windows 10 upgrade.
- [Upgrade error codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json): \Level 400\ The components of an error code are explained.
- [Result codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#result-codes): Information about result codes.
- [Extend codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#extend-codes): Information about extend codes.
- [Log files](log-files.md): \Level 400\ A list and description of log files useful for troubleshooting.
- [Log entry structure](log-files.md#log-entry-structure): The format of a log entry is described.
- [Analyze log files](log-files.md#analyze-log-files): General procedures for log file analysis, and an example.
- [Resolution procedures](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json): \Level 200\ Causes and mitigation procedures associated with specific error codes.
- [0xC1900101](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#0xc1900101): Information about the 0xC1900101 result code.
- [0x800xxxxx](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#0x800xxxxx): Information about result codes that start with 0x800.
- [Other result codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#other-result-codes): Additional causes and mitigation procedures are provided for some result codes.
- [Other error codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#other-error-codes): Additional causes and mitigation procedures are provided for some error codes.
- [Submit Windows 10 upgrade errors](submit-errors.md): \Level 100\ Submit upgrade errors to Microsoft for analysis.
## Related articles
[Windows 10 FAQ for IT professionals](../planning/windows-10-enterprise-faq-itpro.yml)
<br>[Windows 10 Enterprise system requirements](https://technet.microsoft.com/windows/dn798752.aspx)
<br>[Windows 10 Specifications](https://www.microsoft.com/windows/Windows-10-specifications)
<br>[Windows 10 IT pro forums](https://social.technet.microsoft.com/Forums/en-US/home?category=Windows10ITPro)
<br>[Fix Windows Update errors by using the DISM or System Update Readiness tool](/troubleshoot/windows-server/deployment/fix-windows-update-errors)
<br>

57
windows/deployment/upgrade/resolve-windows-upgrade-errors.md Normal file
View File

@ -0,0 +1,57 @@
---
title: Resolve Windows upgrade errors - Windows IT Pro
manager: aaroncz
ms.author: frankroj
description: Resolve Windows upgrade errors for ITPros. Technical information for IT professionals to help diagnose Windows setup errors.
author: frankroj
ms.localizationpriority: medium
ms.topic: article
ms.prod: windows-client
ms.technology: itpro-deploy
ms.date: 01/18/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Resolve Windows upgrade errors: Technical information for IT Pros
> [!IMPORTANT]
>
> This article contains technical instructions for IT administrators. The article isn't intended for non-IT administrators such as home or consumer users.
This article contains a brief introduction to the Windows installation processes, and provides resolution procedures that IT administrators can use to resolve issues with a Windows upgrade.
The article is divided into subtopics of different technical levels. Basic level provides common procedures that can resolve several types of upgrade errors. Advanced level requires some experience with detailed troubleshooting methods.
The following four levels are assigned:
- Level 100: Basic
- Level 200: Moderate
- Level 300: Moderate advanced
- Level 400: Advanced
## In this guide
See the following articles in this section:
- [Quick fixes](/troubleshoot/windows-client/deployment/windows-10-upgrade-quick-fixes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json): \Level 100\ Steps to take to eliminate many Windows upgrade errors.
- [SetupDiag](setupdiag.md): \Level 300\ SetupDiag is a new tool to help isolate the root cause of an upgrade failure.
- [Troubleshooting upgrade errors](/troubleshoot/windows-client/deployment/windows-upgrade-issues-troubleshooting?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json): \Level 300\ General advice and techniques for troubleshooting Windows upgrade errors, and an explanation of phases used during the upgrade process.
- [Windows Error Reporting](windows-error-reporting.md): \Level 300\ How to use Event Viewer to review details about a Windows upgrade.
- [Upgrade error codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json): \Level 400\ The components of an error code are explained.
- [Result codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#result-codes): Information about result codes.
- [Extend codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-error-codes?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#extend-codes): Information about extend codes.
- [Log files](log-files.md): \Level 400\ A list and description of log files useful for troubleshooting.
- [Log entry structure](log-files.md#log-entry-structure): The format of a log entry is described.
- [Analyze log files](log-files.md#analyze-log-files): General procedures for log file analysis, and an example.
- [Resolution procedures](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json): \Level 200\ Causes and mitigation procedures associated with specific error codes.
- [0xC1900101](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#0xc1900101): Information about the 0xC1900101 result code.
- [0x800xxxxx](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#0x800xxxxx): Information about result codes that start with 0x800.
- [Other result codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#other-result-codes): Additional causes and mitigation procedures are provided for some result codes.
- [Other error codes](/troubleshoot/windows-client/deployment/windows-10-upgrade-resolution-procedures?toc=/windows/deployment/toc.json&bc=/windows/deployment/breadcrumb/toc.json#other-error-codes): Additional causes and mitigation procedures are provided for some error codes.
- [Submit Windows upgrade errors](submit-errors.md): \Level 100\ Submit upgrade errors to Microsoft for analysis.
## Related articles
- [Fix Windows Update errors by using the DISM or System Update Readiness tool](/troubleshoot/windows-server/deployment/fix-windows-update-errors).

589
windows/deployment/upgrade/setupdiag.md
View File

@ -1,6 +1,7 @@
---
title: SetupDiag
description: SetupDiag works by examining Windows Setup log files. This article shows how to use the SetupDiag tool to diagnose Windows Setup errors.
ms.reviewer: shendrix
ms.prod: windows-client
ms.technology: itpro-deploy
author: frankroj
@ -11,34 +12,34 @@ ms.topic: troubleshooting
ms.collection:
- highpri
- tier2
ms.date: 10/28/2022
ms.date: 01/18/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# SetupDiag
**Applies to**
- Windows 10
> [!NOTE]
>
> This article is a 300 level article (moderate advanced). See [Resolve Windows upgrade errors](resolve-windows-upgrade-errors.md) for a full list of articles in this section.
>[!NOTE]
>This is a 300 level topic (moderate advanced).<br>
>See [Resolve Windows 10 upgrade errors](resolve-windows-10-upgrade-errors.md) for a full list of topics in this article.<br>
&nbsp;[![Download SetupDiag.](../images/download.png)](https://go.microsoft.com/fwlink/?linkid=870142)
> [!div class="nextstepaction"]
> [Download the latest version of SetupDiag](https://go.microsoft.com/fwlink/?linkid=870142)
## About SetupDiag
<I>Current downloadable version of SetupDiag: 1.6.2107.27002.</I>
> Always be sure to run the most recent version of SetupDiag, so that can access new functionality and fixes to known issues.
> [!IMPORTANT]
>
> When SetupDiag is run manually, Microsoft recommends running the latest version of SetupDiag. The latest version is available via the following [download link](https://go.microsoft.com/fwlink/?linkid=870142). Running the latest version ensures the latest functionality and fixes known issues.
SetupDiag is a diagnostic tool that can be used to obtain details about why a Windows 10 upgrade was unsuccessful.
SetupDiag is a diagnostic tool that can be used to obtain details about why a Windows upgrade was unsuccessful.
SetupDiag works by examining Windows Setup log files. It attempts to parse these log files to determine the root cause of a failure to update or upgrade the computer to Windows 10. SetupDiag can be run on the computer that failed to update, or you can export logs from the computer to another location and run SetupDiag in offline mode.
SetupDiag works by examining Windows Setup log files. It attempts to parse these log files to determine the root cause of a failure to update or upgrade the computer to Windows. SetupDiag can be run on the computer that failed to update. The logs can also be exported from the computer to another location and then running SetupDiag in offline mode.
## SetupDiag in Windows 10, version 2004 and later
SetupDiag is included with [Windows Setup](/windows-hardware/manufacture/desktop/deployment-troubleshooting-and-log-files#windows-setup-scenario) in all currently supported versions of Windows.
With the release of Windows 10, version 2004, SetupDiag is included with [Windows Setup](/windows-hardware/manufacture/desktop/deployment-troubleshooting-and-log-files#windows-setup-scenario).
During the upgrade process, Windows Setup will extract all its sources files to the **%SystemDrive%\$Windows.~bt\Sources** directory. With Windows 10, version 2004 and later, **setupdiag.exe** is also installed to this directory. If there's an issue with the upgrade, SetupDiag will automatically run to determine the cause of the failure.
During the upgrade process, Windows Setup extracts all its sources files, including **SetupDiag.exe**, to the **%SystemDrive%\$Windows.~bt\Sources** directory. If there's an issue with the upgrade, SetupDiag automatically runs to determine the cause of the failure.
When run by Windows Setup, the following [parameters](#parameters) are used:
@ -47,145 +48,200 @@ When run by Windows Setup, the following [parameters](#parameters) are used:
- /Output:%windir%\logs\SetupDiag\SetupDiagResults.xml
- /RegPath:HKEY_LOCAL_MACHINE\SYSTEM\Setup\SetupDiag\Results
The resulting SetupDiag analysis can be found at **%WinDir%\Logs\SetupDiag\SetupDiagResults.xml** and in the registry under **HKLM\SYSTEM\Setup\SetupDiag\Results**. Note that the registry path isn't the same as the default registry path when SetupDiag is run manually. When SetupDiag is run manually, and the /RegPath parameter isn't specified, data is stored in the registry at HKLM\SYSTEM\Setup\MoSetup\Volatile\SetupDiag.
The resulting SetupDiag analysis can be found at `%WinDir%\Logs\SetupDiag\SetupDiagResults.xml` and in the registry under `HKLM\SYSTEM\Setup\SetupDiag\Results`.
> [!NOTE]
>
> When Windows Setup runs SetupDiag automatically, the registry path isn't the same as the default registry path when SetupDiag is run manually. When SetupDiag is run manually, and the `/RegPath` parameter isn't specified, data is stored in the registry at `HKLM\SYSTEM\Setup\MoSetup\Volatile\SetupDiag`.
> [!IMPORTANT]
>
> When SetupDiag indicates that there were multiple failures, the last failure in the log file is typically the fatal error, not the first one.
If the upgrade process proceeds normally, the **Sources** directory including **setupdiag.exe** is moved under **%SystemDrive%\Windows.Old** for cleanup. If the **Windows.old** directory is deleted later, **setupdiag.exe** will also be removed.
## Using SetupDiag
To quickly use SetupDiag on your current computer:
1. Verify that your system meets the [requirements](#requirements) described below. If needed, install the [.NET framework 4.6](https://www.microsoft.com/download/details.aspx?id=48137).
2. [Download SetupDiag](https://go.microsoft.com/fwlink/?linkid=870142).
3. If your web browser asks what to do with the file, choose **Save**. By default, the file will be saved to your **Downloads** folder. You can also save it to a different location if desired by using **Save As**.
4. When SetupDiag has finished downloading, open the folder where you downloaded the file. By default, this folder is the **Downloads** folder, which is displayed in File Explorer under **Quick access** in the left navigation pane.
5. Double-click the **SetupDiag** file to run it. Select **Yes** if you're asked to approve running the program.
- Double-clicking the file to run it will automatically close the command window when SetupDiag has completed its analysis. If you wish to keep this window open instead, and review the messages that you see, run the program by typing **SetupDiag** at the command prompt instead of double-clicking it. You'll need to change directories to the location of SetupDiag to run it this way.
6. A command window will open while SetupDiag diagnoses your computer. Wait for this process to finish.
7. When SetupDiag finishes, two files will be created in the same folder where you double-clicked SetupDiag. One is a configuration file, the other is a log file.
8. Use Notepad to open the log file: **SetupDiagResults.log**.
9. Review the information that is displayed. If a rule was matched, this information can tell you why the computer failed to upgrade, and potentially how to fix the problem. See the [Text log sample](#text-log-sample) below.
For instructions on how to run the tool in offline mode and with more advanced options, see the [Parameters](#parameters) and [Examples](#examples) sections below.
The [Release notes](#release-notes) section at the bottom of this article has information about recent updates to this tool.
If the upgrade process proceeds normally, the **Sources** directory including **SetupDiag.exe** is moved under **%SystemDrive%\Windows.Old** for cleanup. If the **Windows.old** directory is deleted later, **SetupDiag.exe** is also removed.
## Requirements
1. The destination OS must be Windows 10.
2. [.NET Framework 4.6](https://www.microsoft.com/download/details.aspx?id=48137) must be installed. If you aren't sure what version of .NET is currently installed, see [How to: Determine Which .NET Framework Versions Are Installed](/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed). You can also use the following command-line query to display the installed v4 versions:
1. The destination version of Windows must be a currently supported version of Windows. The originally installed version of Windows can be a version of Windows that's out of support as long as:
- The destination version of Windows is a currently supported version of Windows.
- Upgrade to the destination version of Windows is supported from the original installed version of Windows.
1. [.NET Framework 4.7.2](https://go.microsoft.com/fwlink/?linkid=863265) or newer must be installed. To determine which version of .NET is preinstalled with a specific version of Windows, see [.NET Framework system requirements: Supported client operating systems](/dotnet/framework/get-started/system-requirements#supported-client-operating-systems). To determine which version of .NET is currently installed, see [How to: Determine Which .NET Framework Versions Are Installed](/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed).
The following command-line query can be used to display the currently installed version of .NET:
```cmd
reg.exe query "HKLM\SOFTWARE\Microsoft\Net Framework Setup\NDP\v4" /s
```
reg query "HKLM\SOFTWARE\Microsoft\Net Framework Setup\NDP\v4" /s
```
As long as at least the required version of .NET is installed, no additional action is required, including if a newer version is installed.
## Using SetupDiag
To quickly use SetupDiag on the current computer:
1. Verify that the system meets the [requirements](#requirements).
1. [Download SetupDiag](https://go.microsoft.com/fwlink/?linkid=870142).
1. If the web browser asks what to do with the file, choose **Save**. By default, the file is saved to the **Downloads** folder. If desired, the file can also be saved to a different location by using **Save As**.
1. When SetupDiag finishes downloading, open the folder where the file was downloaded. By default, this folder is the **Downloads** folder, which is displayed in File Explorer under **Quick access** in the left navigation pane.
1. Double-click the **SetupDiag** file to run it. Select **Yes** if asked to approve running the program.
Double-clicking the file to run it automatically closes the command window when SetupDiag completes its analysis. To instead keep the window open to review the messages SetupDiag generates, run the program by typing **SetupDiag** at the command prompt instead of double-clicking it. When running from a command prompt, make sure to change directories to where SetupDiag is located.
1. A command window opens while SetupDiag diagnoses the computer. Wait for this process to finish.
1. When SetupDiag finishes, two files are created in the same folder where SetupDiag was run from. One is a configuration file, the other is a log file.
1. Use Notepad to open the log file **SetupDiagResults.log**.
1. Review the information that is displayed. If a rule was matched, this information can say why the computer failed to upgrade, and potentially how to fix the problem. See the section [Text log sample](#text-log-sample).
For instructions on how to run the tool in offline mode and with more advanced options, see the sections [Parameters](#parameters) and [Examples](#examples).
## Parameters
| Parameter | Description |
| --- | --- |
| /? | <ul><li>Displays interactive help</ul> |
| /Output:\<path to results file\> | <ul><li>This optional parameter enables you to specify the output file for results. This file is where you'll find what SetupDiag was able to determine. Only text format output is supported. UNC paths will work, provided the context under which SetupDiag runs has access to the UNC path. If the path has a space in it, you must enclose the entire path in double quotes (see the example section below). <li>Default: If not specified, SetupDiag will create the file **SetupDiagResults.log** in the same directory where SetupDiag.exe is run.</ul> |
| /LogsPath:\<Path to logs\> | <ul><li>This optional parameter tells SetupDiag.exe where to find the log files for an offline analysis. These log files can be in a flat folder format, or containing multiple subdirectories. SetupDiag will recursively search all child directories.</ul> |
| /ZipLogs:\<True \| False\> | <ul><li>This optional parameter tells SetupDiag.exe to create a zip file containing the results and all the log files it parsed. The zip file is created in the same directory where SetupDiag.exe is run.<li>Default: If not specified, a value of 'true' is used.</ul> |
| /Format:\<xml \| json\> | <ul><li>This optional parameter can be used to output log files in xml or JSON format. If this parameter isn't specified, text format is used by default.</ul> |
| /Scenario:\[Recovery\] | <ul><li>This optional parameter instructs SetupDiag.exe to look for and process reset and recovery logs and ignore setup/upgrade logs.</ul>|
| /Verbose | <ul><li>This optional parameter will output much more data to a log file. By default, SetupDiag will only produce a log file entry for serious errors. Using **/Verbose** will cause SetupDiag to always produce another log file with debugging details. These details can be useful when reporting a problem with SetupDiag.</ul> |
| /NoTel | <ul><li>This optional parameter tells SetupDiag.exe not to send diagnostic telemetry to Microsoft.</ul> |
| /AddReg | <ul><li>This optional parameter instructs SetupDiag.exe to add failure information to the registry in offline mode. By default, SetupDiag will add failure information to the registry in online mode only. Registry data is added to the following location on the system where SetupDiag is run: **HKLM\SYSTEM\Setup\MoSetup\Volatile\SetupDiag**.</ul> |
| /RegPath | <ul><li>This optional parameter instructs SetupDiag.exe to add failure information to the registry using the specified path. If this parameter isn't specified the default path is **HKLM\SYSTEM\Setup\MoSetup\Volatile\SetupDiag**.
</ul> |
| **/?** | Displays interactive help |
| **/Output:\[Full path and file name for output log file\]** | This optional parameter specifies the name and location for the results log file. The output file contains the analysis from SetupDiag. Only text format output is supported. UNC paths work provided the context under which SetupDiag runs has access to the UNC path. If the path has a space in it, the entire path must be enclosed in double quotes (**"**). See the [Examples](#examples) sections for an example. <br><br> Default: If not specified, SetupDiag creates the file **SetupDiagResults.log** in the same directory where **SetupDiag.exe** is run. |
| **/LogsPath:\[Full path to logs\]** | This optional parameter specifies the location of logs to parse and where to find the log files for an offline analysis. These log files can be in a flat folder format, or containing multiple subdirectories. SetupDiag recursively searches all child directories. Defaults to checking the current system for logs. |
| **/ZipLogs:\[True \| False\]** | This optional parameter Tells **SetupDiag.exe** to create a zip file containing the results and all the log files that were parsed. The zip file is created in the same directory where **SetupDiag.exe** is run. <br><br> Default: If not specified, a value of 'true' is used. |
| **/Format:\[xml \| json\]** | This optional parameter specifies the output format for log files to be XML or JSON. If this parameter isn't specified, text format is used by default. |
| **/Scenario:\[Recovery \| Debug\]** | This optional parameter can do one of the following two items based on the argument used: <br><br> <ul><li>Recovery instructs **SetupDiag.exe** to look for and process reset and recovery logs and ignore setup/upgrade logs.</li><li>Debug instructs **SetupDiag.exe** to debug memory dumps if the requisite debug binaries are installed.</li></ul> |
| **/Verbose** | This optional parameter creates a diagnostic log in the current directory, with debugging information, additional data, and details about SetupDiag. By default, SetupDiag only produces a log file entry for major errors. Using **/Verbose** causes SetupDiag to always produce another log file with debugging details. These details can be useful when reporting a problem with SetupDiag. |
| **/NoTel** | This optional parameter tells **SetupDiag.exe** not to send diagnostic telemetry to Microsoft. |
| **/RegPath** | This optional parameter Instructs **SetupDiag.exe** to add failure information to the registry under the given path. Registry paths should start with **HKEY_LOCAL_MACHINE** or **HKEY_CURRENT_USER** and be accessible at the elevation level SetupDiag is executed under. If this parameter isn't specified, the default path is **HKLM\SYSTEM\Setup\MoSetup\Volatile\SetupDiag**. |
| **/AddReg** | This optional parameter Instructs **SetupDiag.exe** to add failure information to the registry on the executing system in offline mode. SetupDiag by default adds failure information to the registry in Online mode only. Registry data goes to **HKEY_LOCAL_MACHINE\SYSTEM\Setup\MoSetup\Volatile\SetupDiag** unless otherwise specified. |
Note: The **/Mode** parameter is deprecated in version 1.4.0.0 of SetupDiag.
- In previous versions, this command was used with the LogsPath parameter to specify that SetupDiag should run in an offline manner to analyze a set of log files that were captured from a different computer. In version 1.4.0.0, when you specify /LogsPath then SetupDiag will automatically run in offline mode, therefore the /Mode parameter isn't needed.
> [!NOTE]
>
> The **/Mode** parameter is deprecated in SetupDiag.
>
> In previous versions, this command was used with the LogsPath parameter to specify that SetupDiag should run in an offline manner to analyze a set of log files that were captured from a different computer. In current versions of SetupDiag, when /LogsPath is specified then SetupDiag automatically runs in offline mode, therefore the /Mode parameter isn't needed.
### Examples:
### Examples
In the following example, SetupDiag is run with default parameters (online mode, results file is SetupDiagResults.log in the same folder where SetupDiag is run).
- In the following example, SetupDiag is run with default parameters in online mode. The results file is **SetupDiagResults.log** in the same folder where SetupDiag is run.
```
SetupDiag.exe
```
```cmd
SetupDiag.exe
```
In the following example, SetupDiag is run in online mode (this mode is the default). It will know where to look for logs on the current (failing) system, so there's no need to gather logs ahead of time. A custom location for results is specified.
- In the following example, SetupDiag is run in online mode (this mode is the default). It knows where to look for logs on the current (failing) system, so there's no need to gather logs ahead of time. A custom location for results is specified.
```
SetupDiag.exe /Output:C:\SetupDiag\Results.log
```
```cmd
SetupDiag.exe /Output:C:\SetupDiag\Results.log
```
The following example uses the /Output parameter to save results to a path name that contains a space:
- The following example uses the **/Output** parameter to save results to a path name that contains a space:
```
SetupDiag /Output:"C:\Tools\SetupDiag\SetupDiag Results\Results.log"
```
```cmd
SetupDiag /Output:"C:\Tools\SetupDiag\SetupDiag Results\Results.log"
```
The following example specifies that SetupDiag is to run in offline mode, and to process the log files found in **D:\Temp\Logs\LogSet1**.
- The following example specifies that SetupDiag is to run in offline mode, and to process the log files found in **D:\Temp\Logs\LogSet1**.
```
SetupDiag.exe /Output:C:\SetupDiag\Results.log /LogsPath:D:\Temp\Logs\LogSet1
```
```cmd
SetupDiag.exe /Output:C:\SetupDiag\Results.log /LogsPath:D:\Temp\Logs\LogSet1
```
The following example sets recovery scenario in offline mode. In the example, SetupDiag will search for reset/recovery logs in the specified LogsPath location and output the results to the directory specified by the /Output parameter.
- The following example sets recovery scenario in offline mode. In the example, SetupDiag searches for reset/recovery logs in the specified LogsPath location and output the results to the directory specified by the **/Output** parameter.
```
SetupDiag.exe /Output:C:\SetupDiag\RecoveryResults.log /LogsPath:D:\Temp\Cabs\PBR_Log /Scenario:Recovery
```
```cmd
SetupDiag.exe /Output:C:\SetupDiag\RecoveryResults.log /LogsPath:D:\Temp\Cabs\PBR_Log /Scenario:Recovery
```
The following example sets recovery scenario in online mode. In the example, SetupDiag will search for reset/recovery logs on the current system and output results in XML format.
- The following example sets recovery scenario in online mode. In the example, SetupDiag searches for reset/recovery logs on the current system and output results in XML format.
```
SetupDiag.exe /Scenario:Recovery /Format:xml
```
```cmd
SetupDiag.exe /Scenario:Recovery /Format:xml
```
- The following example is an example of Offline Mode. SetupDiag is instructed to parse setup/upgrade log files in the LogsPath directory and output the results to `C:\SetupDiag\Results.txt`.
```cmd
SetupDiag.exe /Output:C:\SetupDiag\Results.txt /LogsPath:D:\Temp\Logs\Logs1 /RegPath:HKEY_CURRENT_USER\SYSTEM\SetupDiag
```
- The following example is an example of Online Mode. SetupDiag is instructed to look for setup/upgrade logs on the current system and output its results in XML format to `C:\SetupDiag\Results.xml`.
```cmd
SetupDiag.exe /Output:C:\SetupDiag\Results.xml /Format:xml
```
- The following example is an example of Online Mode where no parameters are needed or used. SetupDiag is instructed to look for setup/upgrade logs on the current system and output the results to the same directory where SetupDiag is located.
```cmd
SetupDiag.exe
```
- The following example is an example of Reset/Recovery Offline Mode. SetupDiag is instructed to look for reset/recovery logs in the specified LogsPath location. It then outputs the results to the directory specified by the **/Output** parameter.
```cmd
SetupDiag.exe /Output:C:\SetupDiag\RecoveryResults.log /LogsPath:D:\Temp\Cabs\PBR_Log /Scenario:Recovery
```
- The following example is an example of Reset/Recovery Online Mode. SetupDiag is instructed to look for reset/recovery logs on the current system and output its results in XML format.
```cmd
SetupDiag.exe /Scenario:Recovery /Format:xml
```
## Log files
[Windows Setup Log Files and Event Logs](/windows-hardware/manufacture/desktop/windows-setup-log-files-and-event-logs) has information about where logs are created during Windows Setup. For offline processing, you should run SetupDiag against the contents of the entire folder. For example, depending on when the upgrade failed, copy one of the following folders to your offline location:
[Windows Setup Log Files and Event Logs](/windows-hardware/manufacture/desktop/windows-setup-log-files-and-event-logs) has information about where logs are created during Windows Setup. For offline processing, SetupDiag should be run against the contents of the entire folder. For example, depending on when the upgrade failed, copy one of the following folders to the offline location:
\\$Windows.~bt\sources\panther
<br>\\$Windows.~bt\Sources\Rollback
<br>\Windows\Panther
<br>\Windows\Panther\NewOS
- `\$Windows.~bt\sources\panther`
- `\$Windows.~bt\Sources\Rollback`
- `\Windows\Panther`
- `\Windows\Panther\NewOS`
If you copy the parent folder and all subfolders, SetupDiag will automatically search for log files in all subdirectories.
If the parent folder and all subfolders are copied, SetupDiag automatically searches for log files in all subdirectories.
## Setup bug check analysis
When Microsoft Windows encounters a condition that compromises safe system operation, the system halts. This condition is called a bug check. It's also commonly referred to as a system crash, a kernel error, a Stop error, or BSOD. Typically a hardware device, hardware driver, or related software causes this error.
When Microsoft Windows encounters a condition that compromises safe system operation, the system halts. This condition is called a bug check. This condition is also commonly referred to as a system crash, a kernel error, a Stop error, or BSOD. Typically a hardware device, hardware driver, or related software causes this error.
If crash dumps [are enabled](/windows-hardware/drivers/debugger/enabling-a-kernel-mode-dump-file) on the system, a crash dump file is created. If the bug check occurs during an upgrade, Windows Setup will extract a minidump (setupmem.dmp) file. SetupDiag can also debug these setup-related minidumps.
If crash dumps [are enabled](/windows-hardware/drivers/debugger/enabling-a-kernel-mode-dump-file) on the system, a crash dump file is created. If the bug check occurs during an upgrade, Windows Setup extracts a minidump (`setupmem.dmp`) file. SetupDiag can also debug these setup-related minidumps.
To debug a setup-related bug check:
- Specify the **/LogsPath** parameter. Memory dumps can't be debugged in online mode.
- Gather the setup memory dump file (`setupmem.dmp) from the failing system.
`Setupmem.dmp` is created in either **%SystemDrive%\$Windows.~bt\Sources\Rollback**, or in **%WinDir%\Panther\NewOS\Rollback** depending on when the bug check occurs.
To debug a setup-related bug check, you must:
- Specify the **/LogsPath** parameter. You can't debug memory dumps in online mode.
- Gather the setup memory dump file (setupmem.dmp) from the failing system.
- Setupmem.dmp will be created in either **%SystemDrive%\$Windows.~bt\Sources\Rollback**, or in **%WinDir%\Panther\NewOS\Rollback** depending on when the bug check occurs.
- Install the [Windows Debugging Tools](/windows-hardware/drivers/debugger/debugger-download-tools) on the computer that runs SetupDiag.
In the following example, the **setupmem.dmp** file is copied to the **D:\Dump** directory and the Windows Debugging Tools are installed prior to running SetupDiag:
In the following example, the `setupmem.dmp` file is copied to the `D:\Dump` directory and the Windows Debugging Tools are installed prior to running SetupDiag:
```
```cmd
SetupDiag.exe /Output:C:\SetupDiag\Dumpdebug.log /LogsPath:D:\Dump
```
## Known issues
1. Some rules can take a long time to process if the log files involved are large.
- Some rules can take a long time to process if the log files involved are large.
## Sample output
The following command is an example where SetupDiag is run in offline mode.
```
```cmd
D:\SetupDiag>SetupDiag.exe /output:c:\setupdiag\result.xml /logspath:D:\Tests\Logs\f55be736-beed-4b9b-aedf-c133536c946e /format:xml
SetupDiag v1.6.0.0
SetupDiag v1.7.0.0
Copyright (c) Microsoft Corporation. All rights reserved.
Searching for setup logs...
Found d:\tests\Logs\f55be736-beed-4b9b-aedf-c133536c946e\setupact_6.log with update date 6/12/2019 2:44:20 PM to be the correct setup log.
Found d:\tests\Logs\f55be736-beed-4b9b-aedf-c133536c946e\setupact_1.log with update date 6/12/2019 2:45:19 PM to be the correct rollback log.
Found d:\tests\Logs\f55be736-beed-4b9b-aedf-c133536c946e\setupact_6.log with update date 6/12/2023 2:44:20 PM to be the correct setup log.
Found d:\tests\Logs\f55be736-beed-4b9b-aedf-c133536c946e\setupact_1.log with update date 6/12/2023 2:45:19 PM to be the correct rollback log.
Gathering baseline information from setup logs...
@ -208,241 +264,108 @@ SetupDiag found 1 matching issue.
SetupDiag results were logged to: c:\setupdiag\results.xml
Logs ZipFile created at: c:\setupdiag\Logs_14.zip
```
## Rules
When searching log files, SetupDiag uses a set of rules to match known issues. These rules are contained in the rules.xml file that is extracted when SetupDiag is run. The rules.xml file might be updated as new versions of SetupDiag are made available. For more information, see the [release notes](#release-notes) section.
When SetupDiag searches log files, it uses a set of rules to match known issues. These rules are contained in an xml file. The xml file might be updated with new and updated rules as new versions of SetupDiag are made available.
Each rule name and its associated unique rule identifier are listed with a description of the known upgrade-blocking issue. In the rule descriptions, the term "down-level" refers to the first phase of the upgrade process, which runs under the starting OS.
Each rule name and its associated unique rule identifier are listed with a description of the known upgrade-blocking issue. In the rule descriptions, the term **down-level** refers to the first phase of the upgrade process, which runs under the original OS.
1. CompatScanOnly - FFDAFD37-DB75-498A-A893-472D49A1311D
- This rule indicates that `setup.exe` was called with a specific command line parameter that indicated setup was to do a compat scan only, not an upgrade.
2. BitLockerHardblock - C30152E2-938E-44B8-915B-D1181BA635AE
- This is an upgrade block when the target OS doesn't support BitLocker, yet the host OS has BitLocker enabled.
3. VHDHardblock - D9ED1B82-4ED8-4DFD-8EC0-BE69048978CC
- This block happens when the host OS is booted to a VHD image. Upgrade isn't supported when the host OS is booted from a VHD image.
4. PortableWorkspaceHardblock - 5B0D3AB4-212A-4CE4-BDB9-37CA404BB280
- This indicates that the host OS is booted from a Windows To-Go device (USB key). Upgrade isn't supported in the Windows To-Go environment.
5. AuditModeHardblock - A03BD71B-487B-4ACA-83A0-735B0F3F1A90
- This block indicates that the host OS is currently booted into Audit Mode, a special mode for modifying the Windows state. Upgrade isn't supported from this state.
6. SafeModeHardblock - 404D9523-B7A8-4203-90AF-5FBB05B6579B
- This block indicates that the host OS is booted to Safe Mode, where upgrade isn't supported.
7. InsufficientSystemPartitionDiskSpaceHardblock - 3789FBF8-E177-437D-B1E3-D38B4C4269D1
- This block is encountered when setup determines the system partition (where the boot loader files are stored) doesn't have enough space to be serviced with the newer boot files required during the upgrade process.
8. CompatBlockedApplicationAutoUninstall - BEBA5BC6-6150-413E-8ACE-5E1EC8D34DD5
- This rule indicates there's an application that needs to be uninstalled before setup can continue.
9. CompatBlockedApplicationDismissable - EA52620B-E6A0-4BBC-882E-0686605736D9
- When running setup in /quiet mode, there are dismissible application messages that turn into blocks unless the command line also specifies "/compat ignorewarning". This rule indicates setup was executed in /quiet mode but there's an application dismissible block message that has prevented setup from continuing.
10. CompatBlockedApplicationManualUninstall - 9E912E5F-25A5-4FC0-BEC1-CA0EA5432FF4
- This rule indicates that an application without an Add/Remove Programs entry, is present on the system and blocking setup from continuing. This typically requires manual removal of the files associated with this application to continue.
11. HardblockDeviceOrDriver - ED3AEFA1-F3E2-4F33-8A21-184ADF215B1B
- This error indicates a device driver that is loaded on the host OS isn't compatible with the newer OS version and needs to be removed prior to the upgrade.
12. HardblockMismatchedLanguage - 60BA8449-CF23-4D92-A108-D6FCEFB95B45
- This rule indicates the host OS and the target OS language editions don't match.
13. HardblockFlightSigning - 598F2802-3E7F-4697-BD18-7A6371C8B2F8
- This rule indicates the target OS is a pre-release, Windows Insider build, and the target machine has Secure Boot enabled. This will block the pre-release signed build from booting if installed on the machine.
14. DiskSpaceBlockInDownLevel - 6080AFAC-892E-4903-94EA-7A17E69E549E
- This failure indicates the system ran out of disk space during the down-level operations of upgrade.
15. DiskSpaceFailure - 981DCBA5-B8D0-4BA7-A8AB-4030F7A10191
- This failure indicates the system drive ran out of available disk space at some point after the first reboot into the upgrade.
16. DeviceInstallHang - 37BB1C3A-4D79-40E8-A556-FDA126D40BC6
- This failure rule indicates the system hung or bug checked during the device installation phase of upgrade.
17. DebugSetupMemoryDump - C7C63D8A-C5F6-4255-8031-74597773C3C6
- This offline only rule indicates a bug check occurred during setup. If the debugger tools are available on the system, SetupDiag will debug the memory dump and provide details.
18. DebugSetupCrash - CEEBA202-6F04-4BC3-84B8-7B99AED924B1
- This offline only rule indicates that setup itself encountered a failure that resulted in a process memory dump. If the debugger tools are installed on the system, SetupDiag will debug the memory dump and give further details.
19. DebugMemoryDump - 505ED489-329A-43F5-B467-FCAAF6A1264C
- This offline only rule is for any memory.dmp file that resulted during the setup/upgrade operation. If the debugger tools are installed on the system, SetupDiag will debug the memory dump and give further details.
20. BootFailureDetected - 4FB446C2-D4EC-40B4-97E2-67EB19D1CFB7
- This rule indicates a boot failure occurred during a specific phase of the update. The rule will indicate the failure code and phase for diagnostic purposes.
21. FindDebugInfoFromRollbackLog - 9600EB68-1120-4A87-9FE9-3A4A70ACFC37
- This rule will determine and give details when a bug check occurs during the setup/upgrade process that resulted in a memory dump, but without the requirement of the debugger package being on the executing machine.
22. AdvancedInstallerFailed - 77D36C96-32BE-42A2-BB9C-AAFFE64FCADC
- Finds fatal advanced installer operations that cause setup failures.
23. FindMigApplyUnitFailure - A4232E11-4043-4A37-9BF4-5901C46FD781
- Detects a migration unit failure that caused the update to fail. This rule will output the name of the migration plug-in and the error code it produced for diagnostic purposes.
24. FindMigGatherUnitFailure - D04C064B-CD77-4E64-96D6-D26F30B4EE29
- Detects a migration gather unit failure that caused the update to fail. This rule will output the name of the gather unit/plug-in and the error code it produced for diagnostic purposes.
25. CriticalSafeOSDUFailure - 73566DF2-CA26-4073-B34C-C9BC70DBF043
- This rule indicates a failure occurred while updating the SafeOS image with a critical dynamic update. It will indicate the phase and error code that occurred while attempting to update the SafeOS image for diagnostic purposes.
26. UserProfileCreationFailureDuringOnlineApply - 678117CE-F6A9-40C5-BC9F-A22575C78B14
- Indicates there was a critical failure while creating or modifying a User Profile during the online apply phase of the update. It will indicate the operation and error code associated with the failure for diagnostic purposes.
27. WimMountFailure - BE6DF2F1-19A6-48C6-AEF8-D3B0CE3D4549
- This rule indicates the update failed to mount a WIM file. It will show the name of the WIM file and the error message and error code associated with the failure for diagnostic purposes.
28. FindSuccessfulUpgrade - 8A0824C8-A56D-4C55-95A0-22751AB62F3E
- Determines if the given setup was a success or not based off the logs.
29. FindSetupHostReportedFailure - 6253C04F-2E4E-4F7A-B88E-95A69702F7EC
- Gives information about failures surfaced early in the upgrade process by setuphost.exe
30. FindDownlevelFailure - 716334B7-F46A-4BAA-94F2-3E31BC9EFA55
- Gives failure information surfaced by SetupPlatform, later in the down-level phase.
31. FindAbruptDownlevelFailure - 55882B1A-DA3E-408A-9076-23B22A0472BD
- Gives last operation failure information when the system fails in the down-level, but the log just ends abruptly.
32. FindSetupPlatformFailedOperationInfo - 307A0133-F06B-4B75-AEA8-116C3B53C2D1
- Gives last phase and error information when SetupPlatform indicates a critical failure. This rule will indicate the operation and error associated with the failure for diagnostic purposes.
33. FindRollbackFailure - 3A43C9B5-05B3-4F7C-A955-88F991BB5A48
- Gives last operation, failure phase and error information when a rollback occurs.
34. AdvancedInstallerGenericFailure - 4019550D-4CAA-45B0-A222-349C48E86F71
- A rule to match AdvancedInstaller read/write failures in a generic sense. Will output the executable being called as well as the error code and exit code reported.
35. OptionalComponentFailedToGetOCsFromPackage - D012E2A2-99D8-4A8C-BBB2-088B92083D78 (NOTE: This rule replaces the OptionalComponentInstallFailure rule present in v1.10.
- This matches a specific Optional Component failure when attempting to enumerate components in a package. Will output the package name and error code.
36. OptionalComponentOpenPackageFailed - 22952520-EC89-4FBD-94E0-B67DF88347F6
- Matches a specific Optional Component failure when attempting to open an OC package. Will output the package name and error code.
37. OptionalComponentInitCBSSessionFailed - 63340812-9252-45F3-A0F2-B2A4CA5E9317
- Matches a specific failure where the advanced installer service or components aren't operating or started on the system. Will output the error code.
38. UserProfileCreationFailureDuringFinalize - C6677BA6-2E53-4A88-B528-336D15ED1A64
- Matches a specific User Profile creation error during the finalize phase of setup. Will output the failure code.
39. WimApplyExtractFailure - 746879E9-C9C5-488C-8D4B-0C811FF3A9A8
- Matches a WIM apply failure during WIM extraction phases of setup. Will output the extension, path and error code.
40. UpdateAgentExpanderFailure - 66E496B3-7D19-47FA-B19B-4040B9FD17E2
- Matches DPX expander failures in the down-level phase of update from Windows Update. Will output the package name, function, expression and error code.
41. FindFatalPluginFailure - E48E3F1C-26F6-4AFB-859B-BF637DA49636
- Matches any plug-in failure that setupplatform decides is fatal to setup. Will output the plugin name, operation and error code.
42. AdvancedInstallerFailed - 77D36C96-32BE-42A2-BB9C-AAFFE64FCADC
- Indicates critical failure in the AdvancedInstaller while running an installer package, includes the .exe being called, the phase, mode, component and error codes.
43. MigrationAbortedDueToPluginFailure - D07A24F6-5B25-474E-B516-A730085940C9
- Indicates a critical failure in a migration plugin that causes setup to abort the migration. Will provide the setup operation, plug-in name, plug-in action and error code.
44. DISMAddPackageFailed - 6196FF5B-E69E-4117-9EC6-9C1EAB20A3B9
- Indicates a critical failure during a DISM add package operation. Will specify the Package Name, DISM error and add package error code.
45. PlugInComplianceBlock - D912150B-1302-4860-91B5-527907D08960
- Detects all compat blocks from Server compliance plug-ins. Outputs the block information and remediation.
46. AdvancedInstallerGenericFailure - 4019550D-4CAA-45B0-A222-349C48E86F71
- Triggers on advanced installer failures in a generic sense, outputting the application called, phase, mode, component and error code.
47. FindMigGatherApplyFailure - A9964E6C-A2A8-45FF-B6B5-25E0BD71428E
- Shows errors when the migration Engine fails out on a gather or apply operation. Indicates the Migration Object (file or registry path), the Migration
48. OptionalComponentFailedToGetOCsFromPackage - D012E2A2-99D8-4A8C-BBB2-088B92083D78
- Indicates the optional component (OC) migration operation failed to enumerate optional components from an OC Package. Outputs the package name and error code.
49. OptionalComponentOpenPackageFailed - 22952520-EC89-4FBD-94E0-B67DF88347F6
- Indicates the optional component migration operation failed to open an optional component Package. Outputs the package name and error code.
50. OptionalComponentInitCBSSessionFailed - 63340812-9252-45F3-A0F2-B2A4CA5E9317
- Indicates corruption in the servicing stack on the down-level system. Outputs the error code encountered while trying to initialize the servicing component on the existing OS.
51. DISMproviderFailure - D76EF86F-B3F8-433F-9EBF-B4411F8141F4
- Triggers when a DISM provider (plug-in) fails in a critical operation. Outputs the file (plug-in name), function called + error code, and error message from the provider.
52. SysPrepLaunchModuleFailure - 7905655C-F295-45F7-8873-81D6F9149BFD
- Indicates a sysPrep plug-in has failed in a critical operation. Indicates the plug-in name, operation name and error code.
53. UserProvidedDriverInjectionFailure - 2247C48A-7EE3-4037-AFAB-95B92DE1D980
- A driver provided to setup (via command line input) has failed in some way. Outputs the driver install function and error code.
54. PlugInComplianceBlock - D912150B-1302-4860-91B5-527907D08960
- These are for server upgrades only, will output the compliance block and remediation required.
55. PreReleaseWimMountDriverFound - 31EC76CC-27EC-4ADC-9869-66AABEDB56F0
- Captures failures due to having an unrecognized wimmount.sys driver registered on the system.
56. WinSetupBootFilterFailure - C073BFC8-5810-4E19-B53B-4280B79E096C
- Detects failures in the kernel mode file operations.
57. WimMountDriverIssue - 565B60DD-5403-4797-AE3E-BC5CB972FBAE
- Detects failures in WimMount.sys registration on the system.
58. DISMImageSessionFailure - 61B7886B-10CD-4C98-A299-B987CB24A11C
- Captures failure information when DISM fails to start an image session successfully.
59. FindEarlyDownlevelError - A4CE4FC9-5E10-4BB1-8ECE-3B29EB9D7C52
- Detects failures in down-level phase before setup platform is invoked.
60. FindSPFatalError - A4028172-1B09-48F8-AD3B-86CDD7D55852
- Captures failure information when setup platform encounters a fatal error.
61. UserProfileSuffixMismatch - B4BBCCCE-F99D-43EB-9090-078213397FD8
- Detects when a file or other object causes the migration or creation of a user profile to fail during the update.
## Release notes
07/27/2021 - SetupDiag v1.6.2107.27002 is released with 61 rules, as a standalone tool available in the Download Center.
- This version contains compliance updates and minor bug fixes.
- With this release and subsequent releases, the version number of the downloadable SetupDiag tool is different from the one included with Windows Setup.
05/06/2021 - SetupDiag v1.6.1.0 is released with 61 rules, as a standalone tool available in the Download Center.
- This version of SetupDiag is included with Windows 10, version 21H1.
- A new rule is added: UserProfileSuffixMismatch.
- All outputs to the command line are now invariant culture for purposes of time/date format
- Fixed an issue with registry output in which the "no match found" result caused a corrupted REG_SZ value.
08/08/2019 - SetupDiag v1.6.0.42 is released with 60 rules, as a standalone tool available from the Download Center.
- Log detection performance is improved. Log detection takes around 10 seconds or less where before it could take up to a minute.
- Added Setup Operation and Setup Phase information to both the results log and the registry information.
- This is the last Operation and Phase that Setup was in when the failure occurred.
- Added detailed Setup Operation and Setup Phase information (and timing) to output log when /verbose is specified.
- Note, if the issue found is a compat block, no Setup Operation or Phase info exists yet and therefore won't be available.
- Added more info to the Registry output.
- Detailed 'FailureData' info where available. Example: "AppName = MyBlockedApplication" or "DiskSpace = 6603" (in MB)
- "Key = Value" data specific to the failure found.
- Added 'UpgradeStartTime', 'UpgradeEndTime' and 'UpgradeElapsedTime'
- Added 'SetupDiagVersion', 'DateTime' (to indicate when SetupDiag was executed on the system), 'TargetOSVersion', 'HostOSVersion' and more…
06/19/2019 - SetupDiag v1.5.0.0 is released with 60 rules, as a standalone tool available from the Download Center.
- All date and time outputs are updated to localized format per user request.
- Added setup Operation and Phase information to /verbose log.
- Added last Setup Operation and last Setup Phase information to most rules where it makes sense (see new output below).
- Performance improvement in searching setupact.logs to determine correct log to parse.
- Added SetupDiag version number to text report (xml and json always had it).
- Added "no match" reports for xml and json per user request.
- Formatted Json output for easy readability.
- Performance improvements when searching for setup logs; this should be much faster now.
- Added seven new rules: PlugInComplianceBlock, PreReleaseWimMountDriverFound, WinSetupBootFilterFailure, WimMountDriverIssue, DISMImageSessionFailure, FindEarlyDownlevelError, and FindSPFatalError. See the [Rules](#rules) section above for more information.
- Diagnostic information is now output to the registry at **HKLM\SYSTEM\Setup\MoSetup\Volatile\SetupDiag**
- The **/AddReg** command was added to toggle registry output. This setting is off by default for offline mode, and on by default for online mode. The command has no effect for online mode and enables registry output for offline mode.
- This registry key is deleted as soon as SetupDiag is run a second time, and replaced with current data, so it's always up to date.
- This registry key also gets deleted when a new update instance is invoked.
- For an example, see [Sample registry key](#sample-registry-key).
05/17/2019 - SetupDiag v1.4.1.0 is released with 53 rules, as a standalone tool available from the Download Center.
- This release dds the ability to find and diagnose reset and recovery failures (Push-Button Reset).
12/18/2018 - SetupDiag v1.4.0.0 is released with 53 rules, as a standalone tool available from the Download Center.
- This release includes major improvements in rule processing performance: ~3x faster rule processing performance!
- The FindDownlevelFailure rule is up to 10 times faster.
- New rules have been added to analyze failures upgrading to Windows 10 version 1809.
- A new help link is available for resolving servicing stack failures on the down-level OS when the rule match indicates this type of failure.
- Removed the need to specify /Mode parameter. Now if you specify /LogsPath, it automatically assumes offline mode.
- Some functional and output improvements were made for several rules.
07/16/2018 - SetupDiag v1.3.1 is released with 44 rules, as a standalone tool available from the Download Center.
- This release fixes a problem that can occur when running SetupDiag in online mode on a computer that produces a setupmem.dmp file, but doesn't have debugger binaries installed.
07/10/2018 - SetupDiag v1.30 is released with 44 rules, as a standalone tool available from the Download Center.
- Bug fix for an over-matched plug-in rule. The rule will now correctly match only critical (setup failure) plug-in issues.
- New feature: Ability to output logs in JSON and XML format.
- Use "/Format:xml" or "/Format:json" command line parameters to specify the new output format. See [sample logs](#sample-logs) at the bottom of this topic.
- If the "/Format:xml" or "/Format:json" parameter is omitted, the log output format will default to text.
- New Feature: Where possible, specific instructions are now provided in rule output to repair the identified error. For example, instructions are provided to remediate known blocking issues such as uninstalling an incompatible app or freeing up space on the system drive.
- Three new rules added: AdvancedInstallerFailed, MigrationAbortedDueToPluginFailure, DISMAddPackageFailed.
05/30/2018 - SetupDiag v1.20 is released with 41 rules, as a standalone tool available from the Download Center.
- Fixed a bug in device install failure detection in online mode.
- Changed SetupDiag to work without an instance of setupact.log. Previously, SetupDiag required at least one setupact.log to operate. This change enables the tool to analyze update failures that occur prior to calling SetupHost.
- Telemetry is refactored to only send the rule name and GUID (or "NoRuleMatched" if no rule is matched) and the Setup360 ReportId. This change assures data privacy during rule processing.
05/02/2018 - SetupDiag v1.10 is released with 34 rules, as a standalone tool available from the Download Center.
- A performance enhancement has been added to result in faster rule processing.
- Rules output now includes links to support articles, if applicable.
- SetupDiag now provides the path and name of files that it's processing.
- You can now run SetupDiag by selecting it and then examining the output log file.
- An output log file is now always created, whether or not a rule was matched.
03/30/2018 - SetupDiag v1.00 is released with 26 rules, as a standalone tool available from the Download Center.
| Rule Name | GUID | Description |
| --- | --- |
| **CompatScanOnly** | FFDAFD37-DB75-498A-A893-472D49A1311D | This rule indicates that `setup.exe` was called with a specific command line parameter that indicated setup was to do a compatibility scan only, not an upgrade. |
| **PlugInComplianceBlock** | D912150B-1302-4860-91B5-527907D08960 | Detects all compatibility blocks from Server compliance plug-ins. This rule is for server upgrades only. It outputs the compliance block and remediation required. |
| **BitLockerHardblock** | C30152E2-938E-44B8-915B-D1181BA635AE | This block is an upgrade block when the target OS doesn't support BitLocker, yet the host OS has BitLocker enabled. |
| **VHDHardblock** | D9ED1B82-4ED8-4DFD-8EC0-BE69048978CC | This block happens when the host OS is booted to a VHD image. Upgrade isn't supported when the host OS is booted from a VHD image. |
| **PortableWorkspaceHardblock** | 5B0D3AB4-212A-4CE4-BDB9-37CA404BB280 | This block indicates that the host OS is booted from a Windows To-Go device (USB key). Upgrade isn't supported in the Windows To-Go environment. |
| **AuditModeHardblock** | A03BD71B-487B-4ACA-83A0-735B0F3F1A90 | This block indicates that the host OS is currently booted into Audit Mode, a special mode for modifying the Windows state. Upgrade isn't supported from this state. |
| **SafeModeHardblock** | 404D9523-B7A8-4203-90AF-5FBB05B6579B | This block indicates that the host OS is booted to Safe Mode, where upgrade isn't supported. |
| **InsufficientSystemPartitionDiskSpaceHardblock** | 3789FBF8-E177-437D-B1E3-D38B4C4269D1 | This block is encountered when setup determines the system partition doesn't have enough space to be serviced with the newer boot files required during the upgrade process. The system partition is where the boot loader files are stored |
| **CompatBlockedApplicationAutoUninstall** | BEBA5BC6-6150-413E-8ACE-5E1EC8D34DD5 | This rule indicates there's an application that needs to be uninstalled before setup can continue. |
| **CompatBlockedApplicationDismissable** | EA52620B-E6A0-4BBC-882E-0686605736D9 | When setup is run in **/quiet** mode, there are dismissible application messages that turn into blocks unless the command line also specifies **/compat ignorewarning**. This rule indicates setup was executed in **/quiet** mode but there's an application dismissible block message that prevented setup from continuing. |
| **CompatBlockedFODDismissable** | 7B693C42-793E-4E9E-A10B-ED0F33D45E2A | When setup is run in **/quiet** mode, there are dismissible Feature On Demand messages that turn into blocks unless the command line also specifies **/compat ignorewarning**. This rule indicates setup was executed in **/quiet** mode but there's a Feature On Demand dismissible block message that prevented setup from continuing, usually that the target OS image is missing a Feature On Demand that is installed in the current OS. Removal of the Feature On Demand in the current OS should also resolve the issue.
| **CompatBlockedApplicationManualUninstall** | 9E912E5F-25A5-4FC0-BEC1-CA0EA5432FF4 | This rule indicates that an application without an Add/Remove Programs entry, is present on the system and blocking setup from continuing. This block typically requires manual removal of the files associated with this application to continue. |
| **GenericCompatBlock** | 511B9D95-C945-4F9B-BD63-98F1465E1CF6 | The rule indicates that system doesn't meet a hardware requirement for running Windows. For example, the device is missing a requirement for TPM 2.0. This issue can occur even when an attempt is made to bypass the hardware requirements. |
| **GatedCompatBlock** | 34A9F145-3842-4A68-987F-4622EE0FC162 | This rule indicates that the upgrade failed due to a temporary block. A temporary block is put in place when an issue is found with a specific piece of software or hardware driver and the issue has a fix pending. The block is lifted once the fix is widely available. |
| **HardblockDeviceOrDriver** | ED3AEFA1-F3E2-4F33-8A21-184ADF215B1B | This error indicates a device driver that is loaded on the host OS isn't compatible with the newer OS version. The device driver needs to be removed prior to the upgrade. |
| **HardblockMismatchedLanguage** | 60BA8449-CF23-4D92-A108-D6FCEFB95B45 | This rule indicates the host OS and the target OS language editions don't match. |
| **HardblockFlightSigning** | 598F2802-3E7F-4697-BD18-7A6371C8B2F8 | This rule indicates the target OS is a pre-release, Windows Insider build, and the target machine has Secure Boot enabled. This rule blocks the pre-release signed build from booting if installed on the machine. |
| **DiskSpaceBlockInDownLevel** | 6080AFAC-892E-4903-94EA-7A17E69E549E | This failure indicates the system ran out of disk space during the down-level operations of upgrade. |
| **DiskSpaceFailure** | 981DCBA5-B8D0-4BA7-A8AB-4030F7A10191 | This failure indicates the system drive ran out of available disk space at some point after the first reboot into the upgrade. |
| **PreReleaseWimMountDriverFound** | 31EC76CC-27EC-4ADC-9869-66AABEDB56F0 | Captures failures due to having an unrecognized `wimmount.sys` driver registered on the system. |
| **DebugSetupMemoryDump** | C7C63D8A-C5F6-4255-8031-74597773C3C6 | This offline only rule indicates a bug check occurred during setup. If the debugger tools are available on the system, SetupDiag debugs the memory dump and provide details. |
| **DebugSetupCrash** | CEEBA202-6F04-4BC3-84B8-7B99AED924B1 | This offline only rule indicates that setup itself encountered a failure that resulted in a process memory dump. If the debugger tools are installed on the system, SetupDiag debugs the memory dump and give further details. |
| **DebugMemoryDump** | 505ED489-329A-43F5-B467-FCAAF6A1264C | This offline only rule is for any memory.dmp file that resulted during the setup/upgrade operation. If the debugger tools are installed on the system, SetupDiag debugs the memory dump and give further details. |
| **DeviceInstallHang** | 37BB1C3A-4D79-40E8-A556-FDA126D40BC6 | This failure rule indicates the system hung or bug checked during the device installation phase of upgrade. |
| **DriverPackageMissingFileFailure** | 37BB1C3A-4D79-40E8-A556-FDA126D40BC6 | This rule indicates that a driver package had a missing file during device install. Updating the driver package might help resolve the issue. |
| **UnsignedDriverBootFailure** | CD270AA4-C044-4A22-886A-F34EF2E79469 | This rule indicates that an unsigned driver caused a boot failure. |
| **BootFailureDetected** | 4FB446C2-D4EC-40B4-97E2-67EB19D1CFB7 | This rule indicates a boot failure occurred during a specific phase of the update. The rule indicates the failure code and phase for diagnostic purposes. |
| **WinSetupBootFilterFailure** | C073BFC8-5810-4E19-B53B-4280B79E096C | Detects failures in the kernel mode file operations. |
| **FindDebugInfoFromRollbackLog** | 9600EB68-1120-4A87-9FE9-3A4A70ACFC37 | This rule determines and gives details when a bug check occurs during the setup/upgrade process that resulted in a memory dump. However, a debugger package isn't required on the executing machine. |
| **AdvancedInstallerFailed** | 77D36C96-32BE-42A2-BB9C-AAFFE64FCADC | Finds fatal advanced installer operations that cause setup failures. Indicates critical failure in the AdvancedInstaller while running an installer package, includes the .exe being called, the phase, mode, component and error codes. |
| **AdvancedInstallerPluginInstallFailed** | 2F784A0E-CEB1-47C5-8072-F1294C7CB4AE | This rule indicates some component that was being installed via an advanced installer (FeatureOnDemand, Language Packs, .NET packages, etc.) failed to install. The rule calls out what was being installed. If the failed component is a FeatureOnDemand, remove the Windows Feature, reboot, and try the upgrade again. If the failed component is a Language Pack, remove the additional language pack, reboot, and try the upgrade again. |
| **AdvancedInstallerGenericFailure** | 4019550D-4CAA-45B0-A222-349C48E86F71 | A rule to match AdvancedInstaller read/write failures in a generic sense. Triggers on advanced installer failures in a generic sense. It outputs the application called, phase, mode, component and error code. |
| **FindMigApplyUnitFailure** | A4232E11-4043-4A37-9BF4-5901C46FD781 | Detects a migration unit failure that caused the update to fail. This rule outputs the name of the migration plug-in and the error code it produced for diagnostic purposes. |
| **FindMigGatherUnitFailure** | D04C064B-CD77-4E64-96D6-D26F30B4EE29 | Detects a migration gather unit failure that caused the update to fail. This rule outputs the name of the gather unit/plug-in and the error code it produced for diagnostic purposes. |
| **FindMigGatherApplyFailure** | A9964E6C-A2A8-45FF-B6B5-25E0BD71428E | Shows errors when the migration Engine fails out on a gather or apply operation. Indicates the Migration Object (file or registry path), the Migration |
| **OptionalComponentFailedToGetOCsFromPackage** | D012E2A2-99D8-4A8C-BBB2-088B92083D78 | This rule matches a specific Optional Component failure when attempting to enumerate components in a package. Indicates the optional component (OC) migration operation failed to enumerate optional components from an OC Package. It outputs the package name and error code. This rule replaces the OptionalComponentInstallFailure rule present. |
| **OptionalComponentOpenPackageFailed** | 22952520-EC89-4FBD-94E0-B67DF88347F6 | Matches a specific Optional Component failure when attempting to open an OC package. It outputs the package name and error code. Indicates the optional component migration operation failed to open an optional component Package. Outputs the package name and error code. |
| **OptionalComponentInitCBSSessionFailed** | 63340812-9252-45F3-A0F2-B2A4CA5E9317 | Matches a specific failure where the advanced installer service or components aren't operating or started on the system. Indicates corruption in the servicing stack on the down-level system. Outputs the error code encountered while trying to initialize the servicing component on the existing OS. |
| **CriticalSafeOSDUFailure** | 73566DF2-CA26-4073-B34C-C9BC70DBF043 | This rule indicates a failure occurred while updating the SafeOS image with a critical dynamic update. It indicates the phase and error code that occurred while attempting to update the SafeOS image for diagnostic purposes. |
| **UserProfileCreationFailureDuringOnlineApply** | 678117CE-F6A9-40C5-BC9F-A22575C78B14 | Indicates there was a critical failure while creating or modifying a User Profile during the online apply phase of the update. It indicates the operation and error code associated with the failure for diagnostic purposes. |
| **UserProfileCreationFailureDuringFinalize** | C6677BA6-2E53-4A88-B528-336D15ED1A64 | Matches a specific User Profile creation error during the finalize phase of setup. It outputs the failure code. |
| **UserProfileSuffixMismatch** | B4BBCCCE-F99D-43EB-9090-078213397FD8 | Detects when a file or other object causes the migration or creation of a user profile to fail during the update. |
| **DuplicateUserProfileFailure** | BD7B3109-80F1-4421-8F0A-B34CD25F4B51 | This rule indicates a fatal error while migrating user profiles, usually with multiple SIDs associated with a single user profile. This error usually occurs when software creates local user accounts that aren't ever used or signed in with. The rule indicates the SID and UserName of the account that is causing the failure. To attempt to resolve the issue, first back up all the user's files for the affected user account. After the user's files are backed up, delete the account in a supported manner. Make sure that the account isn't one that is needed or is currently used to sign into the device. After deleting the account, reboot, and try the upgrade again. |
| **WimMountFailure** | BE6DF2F1-19A6-48C6-AEF8-D3B0CE3D4549 | This rule indicates the update failed to mount a WIM file. It shows the name of the WIM file and the error message and error code associated with the failure for diagnostic purposes. |
| **WimMountDriverIssue** | 565B60DD-5403-4797-AE3E-BC5CB972FBAE | Detects failures in `WimMount.sys` registration on the system. |
| **WimApplyExtractFailure** | 746879E9-C9C5-488C-8D4B-0C811FF3A9A8 | Matches a WIM apply failure during WIM extraction phases of setup. It outputs the extension, path and error code. |
| **UpdateAgentExpanderFailure** | 66E496B3-7D19-47FA-B19B-4040B9FD17E2 | Matches DPX expander failures in the down-level phase of update from Windows Update. It outputs the package name, function, expression and error code. |
| **FindFatalPluginFailure** | E48E3F1C-26F6-4AFB-859B-BF637DA49636 | Matches any plug-in failure that setupplatform decides is fatal to setup. It outputs the plugin name, operation and error code. |
| **MigrationAbortedDueToPluginFailure** | D07A24F6-5B25-474E-B516-A730085940C9 | Indicates a critical failure in a migration plugin that causes setup to abort the migration. Provides the setup operation, plug-in name, plug-in action and error code. |
| **DISMAddPackageFailed** | 6196FF5B-E69E-4117-9EC6-9C1EAB20A3B9 | Indicates a critical failure during a DISM add package operation. Specifies the Package Name, DISM error and add package error code. |
| **DISMImageSessionFailure** | 61B7886B-10CD-4C98-A299-B987CB24A11C | Captures failure information when DISM fails to start an image session successfully. |
| **DISMproviderFailure** | D76EF86F-B3F8-433F-9EBF-B4411F8141F4 | Triggers when a DISM provider (plug-in) fails in a critical operation. Outputs the file (plug-in name), function called + error code, and error message from the provider. |
| **SysPrepLaunchModuleFailure** | 7905655C-F295-45F7-8873-81D6F9149BFD | Indicates a sysPrep plug-in failed in a critical operation. Indicates the plug-in name, operation name and error code. |
| **UserProvidedDriverInjectionFailure** | 2247C48A-7EE3-4037-AFAB-95B92DE1D980 | A driver provided to setup (via command line input) failed in some way. Outputs the driver install function and error code. |
| **DriverMigrationFailure** | 9378D9E2-256E-448C-B02F-137F611F5CE3 | This rule indicates a fatal failure when migrating drivers. |
| **UnknownDriverMigrationFailure** | D7541B80-5071-42CE-AD14-FBE8C0C4F7FD | This rule indicates a bad driver package resides on the system. The driver package causes the upgrade to fail when the driver package is attempted to migrate to the new OS. The rule usually indicates the driver package name that caused the issue. The remediation is to remove the bad driver package, reboot, and try the upgrade again. If an update to this driver is available from the OEM, updating the driver package is recommended. |
| | |
| **FindSuccessfulUpgrade** | 8A0824C8-A56D-4C55-95A0-22751AB62F3E | Determines if the given setup was a success or not based off the logs. |
| **FindSetupHostReportedFailure** | 6253C04F-2E4E-4F7A-B88E-95A69702F7EC | Gives information about failures surfaced early in the upgrade process by `setuphost.exe` |
| **FindDownlevelFailure** | 716334B7-F46A-4BAA-94F2-3E31BC9EFA55 | Gives failure information surfaced by SetupPlatform, later in the down-level phase. |
| **FindAbruptDownlevelFailure** | 55882B1A-DA3E-408A-9076-23B22A0472BD | Gives last operation failure information when the system fails in the down-level, but the log just ends abruptly. |
| **FindEarlyDownlevelError** | A4CE4FC9-5E10-4BB1-8ECE-3B29EB9D7C52 | Detects failures in down-level phase before setup platform is invoked. |
| **FindSPFatalError** | A4028172-1B09-48F8-AD3B-86CDD7D55852 | Captures failure information when setup platform encounters a fatal error. |
| **FindSetupPlatformFailedOperationInfo** | 307A0133-F06B-4B75-AEA8-116C3B53C2D1 | Gives last phase and error information when SetupPlatform indicates a critical failure. This rule indicates the operation and error associated with the failure for diagnostic purposes. |
| **FindRollbackFailure** | 3A43C9B5-05B3-4F7C-A955-88F991BB5A48 | Gives last operation, failure phase and error information when a rollback occurs. |
## Sample logs
### Text log sample
```
```txt
Matching Profile found: OptionalComponentOpenPackageFailed - 22952520-EC89-4FBD-94E0-B67DF88347F6
System Information:
Machine Name = Offline
Manufacturer = MSI
Model = MS-7998
HostOSArchitecture = x64
FirmwareType = PCAT
BiosReleaseDate = 20160727000000.000000+000
BiosVendor = BIOS Date: 07/27/16 10:01:46 Ver: V1.70
BiosVersion = 1.70
HostOSVersion = 10.0.15063
HostOSBuildString = 15063.0.amd64fre.rs2_release.170317-1834
TargetOSBuildString = 10.0.16299.15 (rs3_release.170928-1534)
HostOSLanguageId = 2057
HostOSEdition = Core
RegisteredAV = Windows Defender,
FilterDrivers = WdFilter,wcifs,WIMMount,luafv,Wof,FileInfo,
UpgradeStartTime = 3/21/2018 9:47:16 PM
UpgradeEndTime = 3/21/2018 10:02:40 PM
UpgradeElapsedTime = 00:15:24
ReportId = dd4db176-4e3f-4451-aef6-22cf46de8bde
Machine Name = Offline
Manufacturer = MSI
Model = MS-7998
HostOSArchitecture = x64
FirmwareType = PCAT
BiosReleaseDate = 20160727000000.000000+000
BiosVendor = BIOS Date: 07/27/16 10:01:46 Ver: V1.70
BiosVersion = 1.70
HostOSVersion = 10.0.15063
HostOSBuildString = 15063.0.amd64fre.rs2_release.170317-1834
TargetOSBuildString = 10.0.16299.15 (rs3_release.170928-1534)
HostOSLanguageId = 2057
HostOSEdition = Core
RegisteredAV = Windows Defender,
FilterDrivers = WdFilter,wcifs,WIMMount,luafv,Wof,FileInfo,
UpgradeStartTime = 3/21/2023 9:47:16 PM
UpgradeEndTime = 3/21/2023 10:02:40 PM
UpgradeElapsedTime = 00:15:24
ReportId = dd4db176-4e3f-4451-aef6-22cf46de8bde
Error: SetupDiag reports Optional Component installation failed to open OC Package. Package Name: Foundation, Error: 0x8007001F
Recommend you check the "Windows Modules Installer" service (Trusted Installer) is started on the system and set to automatic start, reboot and try the update again. Optionally, you can check the status of optional components on the system (search for Windows Features), uninstall any unneeded optional components, reboot and try the update again.
@ -455,7 +378,7 @@ Refer to https://learn.microsoft.com/windows/deployment/upgrade/upgrade-error-co
```xml
<?xml version="1.0" encoding="utf-16"?>
<SetupDiag xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://learn.microsoft.com/windows/deployment/upgrade/setupdiag">
<Version>1.6.0.0</Version>
<Version>1.7.0.0</Version>
<ProfileName>FindSPFatalError</ProfileName>
<ProfileGuid>A4028172-1B09-48F8-AD3B-86CDD7D55852</ProfileGuid>
<SystemInfo>
@ -474,9 +397,9 @@ Refer to https://learn.microsoft.com/windows/deployment/upgrade/upgrade-error-co
<HostOSEdition>Professional</HostOSEdition>
<RegisteredAV>Windows Defender</RegisteredAV>
<FilterDrivers />
<UpgradeStartTime>2019-06-06T21:19:10</UpgradeStartTime>
<UpgradeStartTime>2023-06-06T21:19:10</UpgradeStartTime>
<UpgradeElapsedTime />
<UpgradeEndTime>2019-06-06T22:21:49</UpgradeEndTime>
<UpgradeEndTime>2023-06-06T22:21:49</UpgradeEndTime>
<RollbackStartTime>0001-01-01T00:00:00</RollbackStartTime>
<RollbackEndTime>0001-01-01T00:00:00</RollbackEndTime>
<RollbackElapsedTime />
@ -488,14 +411,14 @@ Refer to https://learn.microsoft.com/windows/deployment/upgrade/upgrade-error-co
<SetupReportId>F21F8FB6-00FD-4349-84FB-2AC75F389E73</SetupReportId>
<ReportId>F21F8FB6-00FD-4349-84FB-2AC75F389E73</ReportId>
</SystemInfo>
<LogErrorLine>2019-06-06 21:47:11, Error SP Error converting install time 5/2/2019 to structure[gle=0x00000057]</LogErrorLine>
<LogErrorLine>2023-06-06 21:47:11, Error SP Error converting install time 5/2/2023 to structure[gle=0x00000057]</LogErrorLine>
<FailureData>
Error: SetupDiag reports Fatal Error.
Last Setup Phase = Downlevel
Last Setup Operation: Gather data, scope: EVERYTHING
Error: 0x00000057</FailureData>
<FailureData>LogEntry: 2019-06-06 21:47:11, Error SP Error converting install time 5/2/2019 to structure[gle=0x00000057]</FailureData>
<FailureData>LogEntry: 2019-06-06 21:47:11, Error SP Error converting install time 5/2/2019 to structure[gle=0x00000057]</FailureData>
<FailureData>LogEntry: 2023-06-06 21:47:11, Error SP Error converting install time 5/2/2023 to structure[gle=0x00000057]</FailureData>
<FailureData>LogEntry: 2023-06-06 21:47:11, Error SP Error converting install time 5/2/2023 to structure[gle=0x00000057]</FailureData>
<FailureData>
Refer to "https://learn.microsoft.com/windows/desktop/Debug/system-error-codes" for error information.</FailureData>
<FailureDetails>Err = 0x00000057, LastOperation = Gather data, scope: EVERYTHING, LastPhase = Downlevel</FailureDetails>
@ -504,7 +427,7 @@ Refer to "https://learn.microsoft.com/windows/desktop/Debug/system-error-codes"
### JSON log sample
```
```json
{
"Version":"1.6.0.0",
"ProfileName":"FindSPFatalError",
@ -540,15 +463,15 @@ Refer to "https://learn.microsoft.com/windows/desktop/Debug/system-error-codes"
"UpgradeEndTime":"\/Date(1559884909000-0700)\/",
"UpgradeStartTime":"\/Date(1559881150000-0700)\/"
},
"LogErrorLine":"2019-06-06 21:47:11, Error SP Error converting install time 5\/2\/2019 to structure[
"LogErrorLine":"2023-06-06 21:47:11, Error SP Error converting install time 5\/2\/2023 to structure[
gle=0x00000057
]",
"FailureData":[
"\u000aError: SetupDiag reports Fatal Error.\u000aLast Setup Phase = Downlevel\u000aLast Setup Operation: Gather data, scope: EVERYTHING\u000aError: 0x00000057",
"LogEntry: 2019-06-06 21:47:11, Error SP Error converting install time 5\/2\/2019 to structure[
"LogEntry: 2023-06-06 21:47:11, Error SP Error converting install time 5\/2\/2023 to structure[
gle=0x00000057
]",
"LogEntry: 2019-06-06 21:47:11, Error SP Error converting install time 5\/2\/2019 to structure[
"LogEntry: 2023-06-06 21:47:11, Error SP Error converting install time 5\/2\/2023 to structure[
gle=0x00000057
]",
"\u000aRefer to \"https:\/\/learn.microsoft.com\/windows\/desktop\/Debug\/system-error-codes\" for error information."
@ -563,10 +486,10 @@ Refer to "https://learn.microsoft.com/windows/desktop/Debug/system-error-codes"
}
```
## Sample registry key
## Example registry key
![Example of Addreg.](./../images/addreg.png)
:::image type="content" alt-text="Example of Addreg registry key." source="../images/addreg.png":::
## Related articles
[Resolve Windows 10 upgrade errors: Technical information for IT Pros](./resolve-windows-10-upgrade-errors.md)
- [Resolve Windows upgrade errors: Technical information for IT Pros](./resolve-windows-upgrade-errors.md).

85
windows/deployment/upgrade/submit-errors.md
View File

@ -1,72 +1,75 @@
---
title: Submit Windows 10 upgrade errors using Feedback Hub
title: Submit Windows upgrade errors using Feedback Hub
manager: aaroncz
ms.author: frankroj
description: Download the Feedback Hub app, and then submit Windows 10 upgrade errors for diagnosis using feedback hub.
description: Download the Feedback Hub app, and then submit Windows upgrade errors for diagnosis using feedback hub.
ms.prod: windows-client
author: frankroj
ms.localizationpriority: medium
ms.topic: article
ms.technology: itpro-deploy
ms.date: 10/28/2022
ms.date: 01/18/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Submit Windows 10 upgrade errors using Feedback Hub
# Submit Windows upgrade errors using Feedback Hub
**Applies to**
- Windows 10
> [!NOTE]
>
> This article is a 100 level article (basic).
>
> See [Resolve Windows upgrade errors](resolve-windows-upgrade-errors.md) for a full list of articles in this section.
>[!NOTE]
>This is a 100 level topic (basic).<br>
>See [Resolve Windows 10 upgrade errors](resolve-windows-10-upgrade-errors.md) for a full list of topics in this article.
## In this topic
This topic describes how to submit problems with a Windows 10 upgrade to Microsoft using the Windows 10 Feedback Hub.
This article describes how to submit problems with a Windows upgrade to Microsoft using the Windows Feedback Hub.
## About the Feedback Hub
The Feedback Hub app lets you tell Microsoft about any problems you run in to while using Windows 10 and send suggestions to help us improve your Windows experience. Previously, you could only use the Feedback Hub if you were in the Windows Insider Program. Now anyone can use this tool. You can download the Feedback Hub app from the Microsoft Store [here](https://www.microsoft.com/store/p/feedback-hub/9nblggh4r32n?SilentAuth=1&wa=wsignin1.0).
The Feedback Hub app allows reporting to Microsoft of any problems encountered while using Windows. It also allows sending suggestions to Microsoft on how to improve the Windows experience. Previously, the Feedback Hub could only be used through the Windows Insider Program. Now anyone can use this tool. The Feedback Hub app can be downloaded from the [Microsoft Store](https://www.microsoft.com/store/p/feedback-hub/9nblggh4r32n?SilentAuth=1&wa=wsignin1.0).
The Feedback Hub requires Windows 10. If you're having problems upgrading from an older version of Windows to Windows 10, you can use the Feedback Hub to submit this information. However, you must collect the log files from the legacy operating system and then attach these files to your feedback using a device that is running Windows 10. If you're upgrading to Windows 10 from a previous version of Windows 10, the Feedback Hub will collect log files automatically.
The Feedback Hub requires a currently supported version of Windows. The Feedback Hub can be used to submit information to Microsoft if problems are encountered while upgrading Windows. If upgrading to a currently supported version of Windows from a previous version that's Windows 10 or newer, the Feedback Hub automatically collects log files. For operating systems prior to Windows 10 that don't support the Feedback Hub, the log files must be manually collected. The log files can then be attached to the feedback item using a device that is running a currently supported version of Windows that supports the Feedback Hub.
## Submit feedback
To submit feedback about a failed Windows 10 upgrade, select the following link: [Feedback Hub](feedback-hub://?referrer=resolveUpgradeErrorsPage&tabid=2&contextid=81&newFeedback=true&feedbackType=2&topic=submit-errors.md)
To submit feedback about a failed Windows upgrade, open the [Feedback Hub](feedback-hub://?referrer=resolveUpgradeErrorsPage&tabid=2&contextid=81&newFeedback=true&feedbackType=2&topic=submit-errors.md).
The Feedback Hub will open.
In the Feedback Hub, fill out all four sections with as much detail as possible:
- Under **Tell us about it**, and then under **Summarize your issue**, type **Upgrade failing**.
- Under **Give us more detail**, provide additional information about the failed upgrade, such as:
- When did the failure occur?
- Were there any reboots?
- How many times did the system reboot?
- How did the upgrade fail?
- Were any error codes visible?
- Did the computer fail to a blue screen?
- Did the computer automatically rollback or did it hang, requiring you to power cycle it before it rolled back?
- Additional details
- What type of security software is installed?
- Is the computer up to date with latest drivers and firmware?
- Are there any external devices connected?
- If you used the link above, the category and subcategory will be automatically selected. If it isn't selected, choose **Install and Update** and **Windows Installation**.
1. **Enter your feedback**
1. **Choose a category**
1. **Find similar feedback**
1. **Add more details**
You can attach a screenshot or file if desired. This is optional, but can be helpful when diagnosing your upgrade issue. The location of these files is described here: [Windows Setup log files and event logs](/windows-hardware/manufacture/desktop/windows-setup-log-files-and-event-logs).
Recommended information that can be included under the **Add more details** section include:
Select **Submit** to send your feedback.
- When did the failure occur?
- Were there any reboots?
- How many times did the system reboot?
- How did the upgrade fail?
- Were any error codes visible?
- Did the computer fail to a blue screen?
- Did the computer automatically rollback or did it hang, requiring the computer to be power cycled before it rolled back?
- What type of security software is installed?
- Is the computer up to date with latest drivers and firmware?
- Are there any external devices connected?
See the following example:
Using the **Attach a screenshot** and **Attach a file** options allows screenshots or files to be included as part of the feedback item. Attachments and screenshots are optional, but can be helpful when diagnosing the upgrade issue. For example, log files can be included as attachments to the feedback item. The location of the Windows upgrade log files is described in the article [Windows Setup log files and event logs](/windows-hardware/manufacture/desktop/windows-setup-log-files-and-event-logs).
![feedback example.](../images/feedback.png)
Finally the **Recreate my problem** option can be used to potentially send additional data and logs for Microsoft to evaluate.
After you select Submit, that's all you need to do. Microsoft will receive your feedback and begin analyzing the issue. You can check on your feedback periodically to see what solutions have been provided.
Once all the feedback items are completed, select the **Submit** button to send the feedback. Microsoft receives the feedback and begins analyzing the issue. The submitted feedback can be checked on periodically to see what solutions are provided.
## Link to your feedback
## Link to the feedback
After your feedback is submitted, you can email or post links to it by opening the Feedback Hub, clicking My feedback at the top, clicking the feedback item you submitted, clicking **Share**, then copying the short link that is displayed.
After the feedback is submitted, additional information and items can be added to the feedback item. To do so:
![share.](../images/share.jpg)
1. Open the [Feedback Hub](feedback-hub:).
1. At the top of the Feedback Hub, select **My feedback**.
1. Select the feedback item that was submitted.
1. Select **Share**.
1. Copy and then use the short link that is displayed.
:::image type="content" alt-text="Share example." source="../images/share.jpg":::
## Related articles
[Windows 10 release information](https://technet.microsoft.com/windows/release-info.aspx)

62
windows/deployment/upgrade/windows-error-reporting.md
View File

@ -8,25 +8,27 @@ author: frankroj
ms.localizationpriority: medium
ms.topic: article
ms.technology: itpro-deploy
ms.date: 10/28/2022
ms.date: 01/18/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Windows Error Reporting
**Applies to**
- Windows 10
> [!NOTE]
> This is a 300 level topic (moderately advanced).
> See [Resolve Windows 10 upgrade errors](resolve-windows-10-upgrade-errors.md) for a full list of topics in this article.
>
> This article is a 300 level article (moderately advanced).
>
> See [Resolve Windows upgrade errors](resolve-windows-upgrade-errors.md) for a full list of articles in this section.
When Windows Setup fails, the result and extend code are recorded as an informational event in the Application log by Windows Error Reporting as event 1001. The event name is **WinSetupDiag02**. You can use Event Viewer to review this event, or you can use Windows PowerShell.
When Windows Setup fails, the result and extend code are recorded as an informational event in the Application log by Windows Error Reporting as event 1001. The event name is **WinSetupDiag02**. Event Viewer or Windows PowerShell can be used to review this event.
To use Windows PowerShell, type the following commands from an elevated Windows PowerShell prompt:
> [!IMPORTANT]
> The following source will be available only if you have updated from a previous version of Windows 10 to a new version. If you installed the current version and have not updated, the source named **WinSetupDiag02** will be unavailable.
>
> The following Event logs are only available if Windows was updated from a previous version of Windows to a new version of Windows.
```powershell
$events = Get-WinEvent -FilterHashtable @{LogName="Application";ID="1001";Data="WinSetupDiag02"}
@ -34,37 +36,35 @@ $event = [xml]$events[0].ToXml()
$event.Event.EventData.Data
```
To use Event Viewer:
To use Event Viewer:
1. Open Event Viewer and navigate to **Windows Logs\Application**.
2. Select **Find**, and then search for **winsetupdiag02**.
3. Double-click the event that is highlighted.
1. Select **Find**, and then search for **winsetupdiag02**.
1. Double-click the event that is highlighted.
> [!NOTE]
> For legacy operating systems, the Event Name was WinSetupDiag01.
>
> For legacy operating systems, the Event Name was WinSetupDiag01.
Ten parameters are listed in the event:
| Parameters |
| ------------- |
|P1: The Setup Scenario (1=Media,5=WindowsUpdate,7=Media Creation Tool) |
|P2: Setup Mode (x=default,1=Downlevel,5=Rollback) |
|P3: New OS Architecture (x=default,0=X86,9=AMD64) |
|P4: Install Result (x=default,0=Success,1=Failure,2=Cancel,3=Blocked) |
|**P5: Result Error Code** (Ex: 0xc1900101) |
|**P6: Extend Error Code** (Ex: 0x20017) |
|P7: Source OS build (Ex: 9600) |
|P8: Source OS branch (not typically available) |
|P9: New OS build (Ex: 16299} |
|P10: New OS branch (Ex: rs3_release} |
| Parameters |
| ------------- |
| P1: The Setup Scenario (1=Media,5=WindowsUpdate,7=Media Creation Tool) |
| P2: Setup Mode (x=default,1=Downlevel,5=Rollback) |
| P3: New OS Architecture (x=default,0=X86,9=AMD64) |
| P4: Install Result (x=default,0=Success,1=Failure,2=Cancel,3=Blocked) |
| **P5: Result Error Code** (Ex: 0xc1900101) |
| **P6: Extend Error Code** (Ex: 0x20017) |
| P7: Source OS build (Ex: 9600) |
| P8: Source OS branch (not typically available) |
| P9: New OS build (Ex: 16299) |
| P10: New OS branch (Ex: rs3_release) |
The event will also contain links to log files that can be used to perform a detailed diagnosis of the error. An example of this event from a successful upgrade is shown below.
The event also contains links to log files that can be used to perform a detailed diagnosis of the error. The following example is an example of this event from a successful upgrade:
:::image type="content" alt-text="Windows Error Reporting." source="../images/event.png" lightbox="../images/event.png":::
## Related articles
[Windows 10 FAQ for IT professionals](../planning/windows-10-enterprise-faq-itpro.yml)
[Windows 10 Enterprise system requirements](https://technet.microsoft.com/windows/dn798752.aspx)
[Windows 10 Specifications](https://www.microsoft.com/windows/Windows-10-specifications)
[Windows 10 IT pro forums](https://social.technet.microsoft.com/Forums/en-US/home?category=Windows10ITPro)
[Fix Windows Update errors by using the DISM or System Update Readiness tool](/troubleshoot/windows-server/deployment/fix-windows-update-errors)
- [Fix Windows Update errors by using the DISM or System Update Readiness tool](/troubleshoot/windows-server/deployment/fix-windows-update-errors).

73
windows/deployment/usmt/getting-started-with-the-user-state-migration-tool.md
View File

@ -1,83 +1,99 @@
---
title: User State Migration Tool (USMT) - Getting Started (Windows 10)
description: Plan, collect, and prepare your source computer for migration using the User State Migration Tool (USMT).
title: User State Migration Tool (USMT) - Getting Started
description: Plan, collect, and prepare the source computer for migration using the User State Migration Tool (USMT).
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.topic: article
ms.technology: itpro-deploy
ms.date: 11/01/2022
ms.date: 01/09/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Getting started with the User State Migration Tool (USMT)
This article outlines the general process that you should follow to migrate files and settings.
This article outlines the general process to follow to migrate files and settings.
## Step 1: Plan your migration
## Step 1: Plan the migration
1. [Plan Your Migration](usmt-plan-your-migration.md). Depending on whether your migration scenario is refreshing or replacing computers, you can choose an online migration or an offline migration using Windows Preinstallation Environment (WinPE) or the files in the Windows.old directory. For more information, see [Common Migration Scenarios](usmt-common-migration-scenarios.md).
1. [Plan The Migration](usmt-plan-your-migration.md). Depending on whether the migration scenario is refreshing or replacing computers, an online migration or an offline migration can be chosen. Offline migrations can use either Windows Preinstallation Environment (WinPE) or the files in the **Windows.old** directory. For more information, see [Common Migration Scenarios](usmt-common-migration-scenarios.md).
1. [Determine What to Migrate](usmt-determine-what-to-migrate.md). Data you might consider migrating includes end-user information, applications settings, operating-system settings, files, folders, and registry keys.
1. [Determine What to Migrate](usmt-determine-what-to-migrate.md). Data to consider migrating includes end-user information, applications settings, operating-system settings, files, folders, and registry keys.
1. Determine where to store data. Depending on the size of your migration store, you can store the data remotely, locally in a hard-link migration store or on a local external storage device, or directly on the destination computer. For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md).
1. Determine where to store data. Depending on the size of the migration store, data can be stored in one of the following locations:
1. Use the `/GenMigXML` command-line option to determine which files will be included in your migration, and to determine whether any modifications are necessary. For more information, see [ScanState Syntax](usmt-scanstate-syntax.md)
- Remotely.
- Locally in a hard-link migration store or on a local external storage device.
- Directly on the destination computer.
1. Modify copies of the `Migration.xml` and `MigDocs.xml` files and create custom .xml files, if it's required. To modify the migration behavior, such as migrating the **Documents** folder but not the **Music** folder, you can create a custom .xml file or modify the rules in the existing migration .xml files. The document finder, or `MigXmlHelper.GenerateDocPatterns` helper function, can be used to automatically find user documents on a computer without creating extensive custom migration .xml files.
For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md).
1. Use the `/GenMigXML` command-line option to determine which files are included in the migration, and to determine whether any modifications are necessary. For more information, see [ScanState Syntax](usmt-scanstate-syntax.md)
1. If necessary, modify copies of the `Migration.xml` and `MigDocs.xml` files and create custom **.xml** files. To modify the migration behavior, such as migrating the **Documents** folder but not the **Music** folder, custom **.xml** file can be created or modify the rules in the existing migration **.xml** files. The document finder, or `MigXmlHelper.GenerateDocPatterns` helper function, can be used to automatically find user documents on a computer without creating extensive custom migration **.xml** files.
> [!IMPORTANT]
> We recommend that you always make and modify copies of the .xml files included in User State Migration Tool (USMT) 10.0. Never modify the original .xml files.
>
> Microsoft recommends to always make copies of the **.xml** files included in User State Migration Tool (USMT) and then modify the copies. Never modify the original **.xml** files.
You can use the `MigXML.xsd` file to help you write and validate the .xml files. For more information about how to modify these files, see [USMT XML Reference](usmt-xml-reference.md).
The `MigXML.xsd` file can be used to help write and validate the **.xml** files. For more information about how to modify these files, see [USMT XML Reference](usmt-xml-reference.md).
1. Create a [Config.xml File](usmt-configxml-file.md) if to exclude any components from the migration. To create this file, run the `ScanState.exe` command with the following options:
1. Create a [Config.xml File](usmt-configxml-file.md) if you want to exclude any components from the migration. To create this file, run the `ScanState.exe` command with the following options:
- [/genconfig](usmt-scanstate-syntax.md#migration-rule-options).
- [/i](usmt-scanstate-syntax.md#migration-rule-options) - as arguments specify the .xml files that you plan to use with `ScanState.exe`.
- [/i](usmt-scanstate-syntax.md#migration-rule-options) - as arguments specify the **.xml** files that are being used with `ScanState.exe`.
For example, the following command creates a `Config.xml` file by using the `MigDocs.xml` and `MigApp.xml` files:
```cmd
ScanState.exe /genconfig:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log
```
1. Open the `Config.xml` that was generated in the previous step. Review the migration state of each of the components listed in the `Config.xml` file. If necessary, edit the `Config.xml` file and specify `migrate=no` for any components that you don't want to migrate.
1. Open the `Config.xml` that was generated in the previous step. Review the migration state of each of the components listed in the `Config.xml` file. If necessary, edit the `Config.xml` file and specify `migrate=no` for any components that don't need to be migrated.
## Step 2: Collect files and settings from the source computer
1. Back up the source computer.
1. Close all applications. If some applications are running when you run the `ScanState.exe` command, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files.
1. Close all applications. If some applications are running when the `ScanState.exe` command is run, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files.
> [!NOTE]
> USMT will fail if it cannot migrate a file or setting unless you specify the `/C` option. When you specify the `/C` option, USMT will ignore the errors, and log an error every time that it encounters a file that is being used that USMT did not migrate. You can use the `<ErrorControl>` section in the `Config.xml` file to specify which errors should be ignored, and which should cause the migration to fail.
>
> USMT fails if it can't migrate a file or setting unless the `/c` option is specified. When the `/c` option is specified, USMT ignores the errors, and logs an error every time that it encounters a file that is being used that USMT didn't migrate. The `<ErrorControl>` section in the `Config.xml` file can be used to specify which errors should be ignored, and which should cause the migration to fail.
1. Run the `ScanState.exe` command on the source computer to collect files and settings. You should specify all of the .xml files that you want the `ScanState.exe` command to use. For example,
1. Run the `ScanState.exe` command on the source computer to collect files and settings. All of the **.xml** files that the `ScanState.exe` command needs to use should be specified. For example,
```cmd
ScanState.exe \\server\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log
```
> [!NOTE]
> If the source computer is running Windows 7, or Windows 8, you must run the `ScanState.exe` command in **Administrator** mode. To run in **Administrator** mode, right-click **Command Prompt**, and then select **Run As Administrator**. For more information about the how the `ScanState.exe` command processes and stores the data, see [How USMT Works](usmt-how-it-works.md).
>
> The `ScanState.exe` command must be run in **Administrator** mode on the source computer. To run in **Administrator** mode, right-click **Command Prompt**, and then select **Run As Administrator**. For more information about how the `ScanState.exe` command processes and stores the data, see [How USMT Works](usmt-how-it-works.md).
1. Run the `UsmtUtils.exe` command with the `/Verify` option to ensure that the store you created isn't corrupted.
1. Run the `UsmtUtils.exe` command with the `/Verify` option to ensure that the created store isn't corrupted.
## Step 3: Prepare the destination computer and restore files and settings
1. Install the operating system on the destination computer.
1. Install all applications that were on the source computer. Although it isn't always required, we recommend installing all applications on the destination computer before you restore the user state. This makes sure that migrated settings are preserved.
1. Install all applications that were on the source computer. Although it isn't always required, Microsoft recommends installing all applications on the destination computer before restoring the user state. Installing all applications before restoring user state makes sure that migrated settings are preserved.
> [!NOTE]
> The application version that is installed on the destination computer should be the same version as the one on the source computer. USMT does not support migrating the settings for an older version of an application to a newer version. The exception to this is Microsoft Office, which USMT can migrate from an older version to a newer version.
>
> The application version that is installed on the destination computer should be the same version as the one on the source computer. USMT doesn't support migrating the settings for an older version of an application to a newer version. The exception for this rule is Microsoft Office. USMT can migrate from an older version of Microsoft Office to a newer version of Microsoft Office.
1. Close all applications. If some applications are running when you run the `LoadState.exe ` command, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files.
1. Close all applications. If some applications are running when the `LoadState.exe` command runs, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files.
> [!NOTE]
> Use `/C` to continue your migration if errors are encountered, and use the `<ErrorControl>` section in the `Config.xml` file to specify which errors should be ignored, and which errors should cause the migration to fail.
>
> Use `/c` to continue the migration if errors are encountered. Use the `<ErrorControl>` section in the `Config.xml` file to specify which errors should be ignored, and which errors should cause the migration to fail.
1. Run the `LoadState.exe ` command on the destination computer. Specify the same set of .xml files that you specified when you used the `ScanState.exe` command. However, you don't have to specify the `Config.xml` file, unless you want to exclude some of the files and settings that you migrated to the store. For example, you might want to migrate the My Documents folder to the store, but not to the destination computer. To do this, modify the `Config.xml` file and specify the updated file by using the `LoadState.exe ` command. Then, the `LoadState.exe ` command will migrate only the files and settings that you want to migrate. For more information about how the `LoadState.exe ` command processes and migrates data, see [How USMT Works](usmt-how-it-works.md).
1. Run the `LoadState.exe` command on the destination computer. Specify the same set of **.xml** files that were specified when the `ScanState.exe` command was used. However, the `Config.xml` file doesn't always need to be specified. The `Config.xml` file only needs to be specified to exclude some of the files and settings that were migrated to the store. For example, the **Documents** folder was migrated to the store, but doesn't need to be migrated to the destination computer. For example, modify the `Config.xml` file and specify the updated file by using the `LoadState.exe` command. Then, the `LoadState.exe` command migrates only the files and settings that need to be migrated. For more information about how the `LoadState.exe` command processes and migrates data, see [How USMT Works](usmt-how-it-works.md).
For example, the following command migrates the files and settings:
@ -86,6 +102,7 @@ This article outlines the general process that you should follow to migrate file
```
> [!NOTE]
> Run the `LoadState.exe ` command in administrator mode. To do this, right-click **Command Prompt**, and then click **Run As Administrator**.
>
> Run the `LoadState.exe` command in administrator mode. To do this, right-click **Command Prompt**, and then select **Run As Administrator**.
5. Sign out after you run the `LoadState.exe ` command. Some settings, such as fonts, wallpaper, and screen saver settings, won't take effect until the next time that the user logs on.
1. Sign out after running the `LoadState.exe` command. Some settings, such as fonts, wallpaper, and screen saver settings, won't take effect until the next time that the user logs on.

125
windows/deployment/usmt/migrate-application-settings.md
View File

@ -1,36 +1,40 @@
---
title: Migrate Application Settings (Windows 10)
title: Migrate Application Settings
description: Learn how to author a custom migration .xml file that migrates the settings of an application that isn't migrated by default using MigApp.xml.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Migrate Application Settings
You can create a custom .xml file to migrate specific line-of-business application settings or to change the default migration behavior of the User State Migration Tool (USMT) 10.0. For ScanState and LoadState to use this file, you must specify the custom .xml file on both command lines.
A custom **.xml** file can be created to migrate specific line-of-business application settings or to change the default migration behavior of the User State Migration Tool (USMT). For **ScanState** and **LoadState** to use this file, the custom **.xml** file must be specified on both command lines.
This article defines how to author a custom migration .xml file that migrates the settings of an application that isn't migrated by default using `MigApp.xml`. You should migrate the settings after you install the application, but before the user runs the application for the first time.
This article defines how to author a custom migration **.xml** file that migrates the settings of an application that isn't migrated by default using `MigApp.xml`. The settings should be migrated after the application is installed, but before the user runs the application for the first time.
This article doesn't contain information about how to migrate applications that store settings in an application-specific store, only the applications that store the information in files or in the registry. It also doesn't contain information about how to migrate the data that users create using the application. For example, if the application creates .doc files using a specific template, this article doesn't discuss how to migrate the .doc files and templates themselves.
This article doesn't contain information about how to migrate applications that store settings in an application-specific store, only the applications that store the information in files or in the registry. It also doesn't contain information about how to migrate the data that users create using the application. For example, if the application creates **.doc** files using a specific template, this article doesn't discuss how to migrate the **.doc** files and templates themselves.
## Before you begin
## Before beginning
You should identify a test computer that contains the operating system of your source computers, and the application whose settings you want to migrate. For example, if you're planning on migrating from Windows 7 to Windows 10, install Windows 7 on your test computer and then install the application.
A test computer that contains the operating system of the source computers should be identified. The test computer should also have the applications whose settings need to be migrated. For example, if migrating from Windows 10 to Windows 11, install Windows 10 on the test computer and then install the applications.
## Step 1: Verify that the application is installed on the source computer, and that it's the same version as the version to be installed on the destination computer
Before USMT migrates the settings, you need it to check whether the application is installed on the source computer, and that it's the correct version. If the application isn't installed on the source computer, you probably don't want USMT to spend time searching for the application's settings. More importantly, if USMT collects settings for an application that isn't installed, it may migrate settings that will cause the destination computer to function incorrectly. You should also investigate whether there's more than one version of the application because the new version may not store the settings in the same place. Mismatched application versions may lead to unexpected results on the destination computer.
Before USMT migrates the settings, check whether the application is installed on the source computer, and that it's the correct version. If the application isn't installed on the source computer, USMT still spends time searching for the application's settings. More importantly, if USMT collects settings for an application that isn't installed, it could migrate settings that cause the destination computer to function incorrectly. Also determine whether there's more than one version of the application because the new version could store the settings in a different location. Mismatched application versions could lead to unexpected results on the destination computer.
There are many ways to detect if an application is installed. The best practice is to check for an application uninstall key in the registry, and then search the computer for the executable file that installed the application. It's important that you check for both of these items, because sometimes different versions of the same application share the same uninstall key. So even if the key is there, it may not correspond to the version of the application that you want.
There are many ways to detect if an application is installed. The best practice is to check for an application uninstall key in the registry, and then search the computer for the executable file that installed the application. It's important to check for both of these items, because sometimes different versions of the same application share the same uninstall key. Even if the key is there, it could correspond to a different version of the application that is wanted.
### Check the registry for an application uninstall key
When many applications are installed (especially those installed using the Microsoft® Windows® Installer technology), an application uninstall key is created under:
When many applications are installed (especially those installed using the Microsoft Windows Installer technology), an application uninstall key is created under:
`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall`
@ -38,110 +42,123 @@ For example, when Adobe Acrobat Reader 7 is installed, it creates a key named:
`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall \{AC76BA86-7AD7-1033-7B44-A70000000000}`
Therefore, if a computer contains this key, then Adobe Acrobat Reader 7 is installed on the computer. You can check for the existence of a registry key using the `DoesObjectExist` helper function.
Therefore, if a computer contains this key, then Adobe Acrobat Reader 7 is installed on the computer. The existence of a registry key can be checked using the `DoesObjectExist` helper function.
Usually, you can find this key by searching under
Usually, this key can be found by searching under:
`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall`
for the name of the application, the name of the application executable file, or for the name of the company that makes the application. You can use the Registry Editor, `Regedit.exe` located in the `%SystemRoot%`, to search the registry.
for the name of the application, the name of the application executable file, or for the name of the company that makes the application. The Registry Editor, `Regedit.exe` located in the `%SystemRoot%`, can be used to search the registry.
### Check the file system for the application executable file
You should also check the application binaries for the executable that installed the application. To check for application binaries, you'll first need to determine where the application is installed and what the name of the executable is. Most applications store the installation location of the application binaries in the registry. You should search the registry for the name of the application, the name of the application executable, or for the name of the company that makes the application, until you find the registry value that contains the installation path. Once you've determined the path to the application executable, you can use the `DoesFileVersionMatch` helper function to check for the correct version of the application executable. For an example of how to use the `DoesFileVersionMatch` helper function, see the Windows Live™ Messenger section of the `MigApp.xml` file.
The application binaries for the executable that installed the application should also be checked. To check for application binaries, determine where the application is installed and what the name of the executable is. Most applications store the installation location of the application binaries in the registry. The registry should be searched on one of the following items until the registry value that contains the installation path is found:
- The name of the application.
- The name of the application executable.
- The name of the company that makes the application.
Once the path to the application executable is determined, the `DoesFileVersionMatch` helper function can be used to check for the correct version of the application executable. For an example of how to use the `DoesFileVersionMatch` helper function, see the Windows Live™ Messenger section of the `MigApp.xml` file.
## Step 2: Identify settings to collect and determine where each setting is stored on the computer
Next, you should go through the user interface and make a list of all of the available settings. You can reduce the list if there are settings that you don't want to migrate. To determine where each setting is stored, you'll need to change each setting and monitor the activity on the registry and the file system. You don't need to migrate the binary files and registry settings that are made when the application is installed because you'll need to reinstall the application onto the destination computer. You only need to migrate those settings that are customizable.
Next, go through the user interface and make a list of all of the available settings. The list can be reduced if there are settings that don't need to be migrated. To determine where each setting is stored, change the setting. As the setting is changed, monitor the activity on the registry and the file system through a tool such as [Process Monitor](/sysinternals/downloads/procmon). The binary files and registry settings that are created when the application is installed don't need to be migrated. When the application is reinstalled onto the destination computer, it recreates those settings. Only the customized settings need to be migrated.
### How to determine where each setting is stored
1. Download a file and registry monitoring tool, such as the Regmon and Filemon tools, from the [Windows Sysinternals Web site](/sysinternals/).
1. Download a file and registry monitoring tool, such as [Process Monitor (Procmon)](/sysinternals/downloads/procmon), from the [Sysinternals Web site](/sysinternals/).
2. Shut down as many applications as possible to limit the registry and file system activity on the computer.
1. Shut down as many applications as possible to limit the registry and file system activity on the computer.
3. Filter the output of the tools so it only displays changes being made by the application.
1. Filter the output of the tools so it only displays changes being made by the application.
> [!NOTE]
> Most applications store their settings under the user profile. That is, the settings stored in the file system are under the `%UserProfile%` directory, and the settings stored in the registry are under the `HKEY_CURRENT_USER` hive. For these applications you can filter the output of the file and registry monitoring tools to show activity only under these locations. This will considerably reduce the amount of output that you will need to examine.
>
> Most applications store their settings under the user profile. That is, the settings stored in the file system are under the `%UserProfile%` directory, and the settings stored in the registry are under the `HKEY_CURRENT_USER` hive. For these applications, the output of the file and registry monitoring tools can be filtered to show activity only under these locations. This filtering considerably reduces the amount of output that needs to be examined.
4. Start the monitoring tool(s), change a setting, and look for registry and file system writes that occurred when you changed the setting. Make sure the changes you make actually take effect. For example, if you're changing a setting in Microsoft Word by selecting a check box in the **Options** dialog box, the change typically won't take effect until you close the dialog box by clicking **OK**.
1. Start the monitoring tool(s), change a setting, and look for registry and file system writes that occurred when the setting was changed. Make sure the changes made actually take effect. For example, if changing a setting in Microsoft Word by selecting a check box in the **Options** dialog box, the change typically doesn't take effect until the dialog box is closed by selecting **OK**.
5. When the setting is changed, note the changes to the file system and registry. There may be more than one file or registry values for each setting. You should identify the minimal set of file and registry changes that are required to change this setting. This set of files and registry keys is what you will need to migrate in order to migrate the setting.
1. When the setting is changed, note the changes to the file system and registry. There could be more than one file or registry values for each setting. The minimal set of file and registry changes that are required to change this setting should be identified. This set of files and registry keys is what needs to be migrated in order to migrate the setting.
> [!NOTE]
>
> Changing an application setting invariably leads to writing to registry keys. If possible, filter the output of the file and registry monitor tool to display only writes to files and registry keys/values.
## Step 3: Identify how to apply the gathered settings
If the version of the application on the source computer is the same as the one on the destination computer, then you don't have to modify the collected files and registry keys. By default, USMT migrates the files and registry keys from the source location to the corresponding location on the destination computer. For example, if a file was collected from the `C:\Documents and Settings\User1\My Documents` folder and the profile directory on the destination computer is located at `D:\Users\User1`, then USMT will automatically migrate the file to `D:\Users\User1\My Documents`. However, you may need to modify the location of some settings in the following three cases:
If the version of the application on the source computer is the same as the one on the destination computer, then the collected files and registry keys don't need to be modified. By default, USMT migrates the files and registry keys from the source location to the corresponding location on the destination computer. For example, if a file was collected from the `C:\Users\User1\Documents` folder and the profile directory on the destination computer is located at `D:\Users\User1`, then USMT automatically migrates the file to `D:\Users\User1\Documents`. However, the location of some settings might need to be modified in the following three cases:
### Case 1: The version of the application on the destination computer is newer than the one on the source computer
In this case, the newer version of the application may be able to read the settings from the source computer without modification. That is, the data collected from an older version of the application is sometimes compatible with the newer version of the application. However, you may need to modify the setting location if either of the following conditions is true:
In this case, the newer version of the application might be able to read the settings from the source computer without modification. That is, the data collected from an older version of the application is sometimes compatible with the newer version of the application. However, the setting location might need to be modified if either of the following conditions is true:
- **The newer version of the application has the ability to import settings from an older version.** This mapping usually happens the first time a user runs the newer version after the settings have been migrated. Some applications import settings automatically after settings are migrated. However, other applications will only do import settings if the application was upgraded from the older version. When the application is upgraded, a set of files and/or registry keys is installed that indicates the older version of the application was previously installed. If you perform a clean installation of the newer version (which is the case in most migrations), the computer doesn't contain this set of files and registry keys so the mapping doesn't occur. In order to trick the newer version of the application into initiating this import process, your migration script may need to create these files and/or registry keys on the destination computer.
- **The newer version of the application has the ability to import settings from an older version.** This mapping usually happens the first time a user runs the newer version after the settings are migrated. Some applications import settings automatically after settings are migrated. However, other applications only import settings if the application was upgraded from the older version. When the application is upgraded, a set of files and/or registry keys is installed that indicates the older version of the application was previously installed. If a clean installation of the newer version is performed, the computer doesn't contain these files and registry keys. If the files and registry keys aren't present, the mapping doesn't occur. In order to trick the newer version of the application into initiating this import process, the migration script might need to create these files and/or registry keys on the destination computer.
To identify which files and/or registry keys/values need to be created to cause the import, you should upgrade the older version of the application to the newer one and monitor the changes made to the file system and registry by using the same process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). Once you know the set of files that the computer needs, you can use the **&lt;addObjects&gt;** element to add them to the destination computer.
To identify which files and/or registry keys/values need to be created so that the import works:
- **The newer version of the application can't read settings from the source computer and it's also unable to import the settings into the new format.** In this case, you'll need to create a mapping for each setting from the old locations to the new locations. To create the mapping, determine where the newer version stores each setting using the process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). After you've created the mapping, apply the settings to the new location on the destination computer using the **&lt;locationModify&gt;** element, and the `RelativeMove` and `ExactMove` helper functions.
1. Upgrade the older version of the application to the newer one.
1. Monitor the changes made to the file system and registry by using the same process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored).
Once the set of files that the computer needs is known, the **\<addObjects\>** element can be used to add them to the destination computer.
- **The newer version of the application can't read settings from the source computer and it's also unable to import the settings into the new format.** In this case, create a mapping for each setting from the old locations to the new locations. To create the mapping, determine where the newer version stores each setting using the process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). After creating the mapping, apply the settings to the new location on the destination computer using the **\<locationModify\>** element, and the `RelativeMove` and `ExactMove` helper functions.
### Case 2: The destination computer already contains settings for the application
We recommend that you migrate the settings after you install the application, but before the user runs the application for the first time. We recommend this process because this process ensures that there are no settings on the destination computer when you migrate the settings. If you must install the application before the migration, you should delete any existing settings using the **&lt;destinationCleanup&gt;** element. If for any reason you want to preserve the settings that are on the destination computer, you can use the **&lt;merge&gt;** element and `DestinationPriority` helper function.
Microsoft recommends migrating the settings after the application is installed, but before the user runs the application for the first time. Microsoft recommends this process because this process ensures that there are no settings on the destination computer when the settings are migrated. If the application must be installed before the migration, any existing settings should be deleted using the **\<destinationCleanup\>** element. If for any reason the settings need to be preserved that are on the destination computer, the **\<merge\>** element and `DestinationPriority` helper function can be used.
### Case 3: The application overwrites settings when it's installed
### Case 3: The application overwrites settings when installed
We recommend that you migrate the settings after you install the application, but before the user runs the application for the first time. We recommend this process because this process ensures that there are no settings on the destination computer when you migrate the settings. Also, when some applications are installed, they overwrite any existing settings that are on the computer. In this scenario, if you migrated the data before you installed the application, your customized settings would be overwritten. This scenario is common for applications that store settings in locations that are outside of the user profile (typically these settings are settings that apply to all users). These universal settings are sometimes overwritten when an application is installed, and they're replaced by default values. To avoid this problem, you must install these applications before migrating the files and settings to the destination computer. By default with USMT, data from the source computer overwrites data that already exists in the same location on the destination computer.
Microsoft recommends migrating the settings after the application is installed, but before the user runs the application for the first time. Microsoft recommends this process because this process ensures that there are no settings on the destination computer when the settings are migrated. Also, when some applications are installed, they overwrite any existing settings that are on the computer. In this scenario, if the data was migrated before the application was installed, the customized settings would be overwritten. This scenario is common for applications that store settings in locations that are outside of the user profile (typically these settings are settings that apply to all users). These universal settings are sometimes overwritten when an application is installed, and they're replaced by default values. To avoid this problem, these applications must be installed before migrating the files and settings to the destination computer. By default with USMT, data from the source computer overwrites data that already exists in the same location on the destination computer.
## Step 4: Create the migration XML component for the application
After you have completed steps 1 through 3, you'll need to create a custom migration .xml file that migrates the application based on the information that you now have. You can use the `MigApp.xml` file as a model because it contains examples of many of the concepts discussed in this article. You can also see [Custom XML Examples](usmt-custom-xml-examples.md) for another sample .xml file.
After completing steps 1 through 3, create a custom migration **.xml** file that migrates the application based on the updated information. The `MigApp.xml` file can be used as a model because it contains examples of many of the concepts discussed in this article. Also see [Custom XML Examples](usmt-custom-xml-examples.md) for another sample **.xml** file.
> [!NOTE]
> We recommend that you create a separate .xml file instead of adding your script to the `MigApp.xml` file. This is because the `MigApp.xml` file is a very large file and it will be difficult to read and edit. In addition, if you reinstall USMT for some reason, the `MigApp.xml` file will be overwritten by the default version of the file and you will lose your customized version.
> [!NOTE]
>
> Microsoft recommends creating a separate **.xml** file instead of adding a script to the `MigApp.xml` file. A separate **.xml** file is recommended because the `MigApp.xml` file is a large file and it's difficult to read and edit. In addition, if USMT is reinstalled, the `MigApp.xml` file is overwritten with the default version of the file and the customized version is lost.
> [!IMPORTANT]
> Some applications store information in the user profile, such as application installation paths, the computer name, etc., should not be migrated. You should make sure to exclude these files and registry keys from the migration.
>
> Some applications store information in the user profile, such as application installation paths, the computer name, etc. Application information stored in the user profile shouldn't be migrated and should be excluded from the migration.
Your script should do the following actions:
The script should do the following actions:
1. Check whether the application and correct version is installed by:
1. Check if the correct version of the application is installed:
- Searching for the installation uninstall key under `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` using the `DoesObjectExist` helper function.
- Search for the installation uninstall key under `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` using the `DoesObjectExist` helper function.
- Checking for the correct version of the application executable file using the `DoesFileVersionMatch` helper function.
- Check for the correct version of the application executable file using the `DoesFileVersionMatch` helper function.
2. If the correct version of the application is installed, then ensure that each setting is migrated to the appropriate location on the destination computer.
1. If the correct version of the application is installed, then ensure that each setting is migrated to the appropriate location on the destination computer.
- If the versions of the applications are the same on both the source and destination computers, migrate each setting using the **&lt;include&gt;** and **&lt;exclude&gt;** elements.
- If the versions of the applications are the same on both the source and destination computers, migrate each setting using the **\<include\>** and **\<exclude\>** elements.
- If the version of the application on the destination computer is newer than the one on the source computer, and the application can't import the settings, your script should either:
1. Add the set of files that trigger the import using the **&lt;addObjects&gt;** element
2. Create a mapping that applies the old settings to the correct location on the destination computer using the **&lt;locationModify&gt;** element, and the `RelativeMove` and `ExactMove` helper functions.
- If the version of the application on the destination computer is newer than the one on the source computer, and the application can't import the settings, the script should either:
- If you must install the application before migrating the settings, delete any settings that are already on the destination computer using the **&lt;destinationCleanup&gt;** element.
1. Add the set of files that trigger the import using the **\<addObjects\>** element.
1. Create a mapping that applies the old settings to the correct location on the destination computer using the **\<locationModify\>** element, and the `RelativeMove` and `ExactMove` helper functions.
For information about the .xml elements and helper functions, see [XML Elements Library](usmt-xml-elements-library.md).
- If the application must be installed before migrating the settings, delete any settings that are already on the destination computer using the **\<destinationCleanup\>** element.
For information about the **.xml** elements and helper functions, see [XML Elements Library](usmt-xml-elements-library.md).
## Step 5: Test the application settings migration
On a test computer, install the operating system that will be installed on the destination computers. For example, if you're planning on migrating from Windows 7 to Windows 10, install Windows 10 and the application. Next, run LoadState on the test computer and verify that all settings migrate. Make corrections if necessary and repeat the process until all the necessary settings are migrated correctly.
On a test computer, install the operating system that will be installed on the destination computers. For example, if planning on migrating from Windows 10 to Windows 11, install Windows 11, and then install the application in Windows 11. Next, run **LoadState** on the test computer and verify that all settings migrate. Make corrections if necessary and repeat the process until all the necessary settings are migrated correctly.
To speed up the time it takes to collect and migrate the data, you can migrate only one user at a time, and you can exclude all other components from the migration except the application that you're testing. To specify only **User1** in the migration, enter:
To speed up the time it takes to collect and migrate the data, only one user can be migrated at a time. All other components can be excluded from the migration except the application that is being tested. To specify only **User1** in the migration, enter:
```cmd
/ue:*\* /ui:user1
```
For more information, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article and the [User options](usmt-scanstate-syntax.md#user-options) section in the [ScanState syntax](usmt-scanstate-syntax.md) article. To troubleshoot a problem, check the progress log, and the ScanState and LoadState logs, which contain warnings and errors that may point to problems with the migration.
For more information, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article and the [User options](usmt-scanstate-syntax.md#user-options) section in the [ScanState syntax](usmt-scanstate-syntax.md) article. To troubleshoot a problem, check the progress log, the **ScanState** log, and the **LoadState** log. The logs contain warnings and errors that could point to problems with the migration.
## Related articles
[USMT XML reference](usmt-xml-reference.md)
[Conflicts and precedence](usmt-conflicts-and-precedence.md)
[XML elements library](usmt-xml-elements-library.md)
[Log files](usmt-log-files.md)
- [USMT XML reference](usmt-xml-reference.md).
- [Conflicts and precedence](usmt-conflicts-and-precedence.md).
- [XML elements library](usmt-xml-elements-library.md).
- [Log files](usmt-log-files.md).

45
windows/deployment/usmt/migration-store-types-overview.md
View File

@ -1,18 +1,22 @@
---
title: Migration Store Types Overview (Windows 10)
description: Learn about the migration store types and how to determine which migration store type best suits your needs.
title: Migration Store Types Overview
description: Learn about the migration store types and how to determine which migration store type best suits the organization's needs.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Migration Store Types Overview
When planning your migration, you should determine which migration store type best meets your needs. As part of these considerations, determine how much space is required to run the User State Migration Tool (USMT) 10.0 components on your source and destination computers. You should also determine the space needed to create and host the migration store, whether you're using a local share, network share, or storage device.
When a migration is being planned, which migration store type best meets the organization's needs should be determined. As part of these considerations, determine how much space is required to run the User State Migration Tool (USMT) components on the source and destination computers. The space needed to create and host the migration store should also be determined, whether using a local share, network share, or storage device.
## Migration store types
@ -20,7 +24,7 @@ This section describes the three migration store types available in USMT.
### Uncompressed (UNC)
The uncompressed (UNC) migration store is an uncompressed directory with a mirror image of the folder hierarchy being migrated. Each directory and file retains the same access permissions that it has on the local file system. You can use Windows Explorer to view this migration store type. Settings are stored in a catalog file that also describes how to restore files on the destination computer.
The uncompressed (UNC) migration store is an uncompressed directory with a mirror image of the folder hierarchy being migrated. Each directory and file retains the same access permissions that it has on the local file system. Windows Explorer can be used to view this migration store type. Settings are stored in a catalog file that also describes how to restore files on the destination computer.
### Compressed
@ -28,9 +32,9 @@ The compressed migration store is a single image file that contains all files be
### Hard-Link
A hard-link migration store functions as a map that defines how a collection of bits on the hard disk are "wired" into the file system. You use the new USMT hard-link migration store in the PC Refresh scenario only. You only use hard-link migration stores in Refresh scenarios because the hard-link migration store is maintained on the local computer while the old operating system is removed and the new operating system is installed. Using a hard-link migration store saves network bandwidth and minimizes the server use needed to accomplish the migration.
A hard-link migration store functions as a map that defines how a collection of bits on the hard disk are "wired" into the file system. The USMT hard-link migration store is only used in the PC Refresh scenario. Hard-link migration stores are only used in Refresh scenarios because the hard-link migration store is maintained on the local computer. The hard-link store is maintained on the computer while the old operating system is removed and the new operating system is installed. Using a hard-link migration store saves network bandwidth and minimizes the server use needed to accomplish the migration.
You use the command-line option `/hardlink` to create a hard-link migration store, which functions the same as an uncompressed migration store. Files aren't duplicated on the local computer when user state is captured, nor are they duplicated when user state is restored. For more information, see [Hard-Link Migration Store](usmt-hard-link-migration-store.md).
The command-line option `/hardlink` is used to create a hard-link migration store, which functions the same as an uncompressed migration store. Files aren't duplicated on the local computer when user state is captured. They also aren't duplicated when user state is restored. For more information, see [Hard-Link Migration Store](usmt-hard-link-migration-store.md).
The following flowchart illustrates the procedural differences between a local migration store and a remote migration store. In this example, a hard-link migration store is used for the local store.
@ -38,23 +42,32 @@ The following flowchart illustrates the procedural differences between a local m
## Local store vs. remote store
If you have enough space and you're migrating the user state back to the same computer, storing data on a local device is normally the best option to reduce server storage costs and network performance issues. You can store the data locally either on a different partition or on a removable device such as a USB flash drive (UFD). Also, depending on the imaging technology that you're using, you might be able to store the data on the partition that is being re-imaged, if the data will be protected from deletion during the process. To increase performance, store the data on high-speed drives that use a high-speed network connection. It's also good practice to ensure that the migration is the only task the server is performing.
If there's enough space and the user state is being migrated back to the same computer, storing data on a local device is normally the best option to reduce server storage costs and network performance issues. The data can also be stored locally either on a different partition or on a removable device such as a USB flash drive (UFD). Also, the data might be able to be stored on the partition that is being re-imaged if the data can be protected from deletion during the imaging process. One example of an imaging technology that is capable of storing the data on the partition that is being reimaged is Microsoft Configuration Manager. To increase performance, store the data on high-speed drives that use a high-speed network connection. It's also good practice to ensure that the migration is the only task the server is performing.
If there isn't enough local disk space, or if you're moving the user state to another computer, then you must store the data remotely such as on a shared folder, on removable media, or you can store it directly on the destination computer. For example:
If there isn't enough local disk space, or if moving the user state to another computer, then the data must be stored remotely such as in one of the following destinations:
1. Create and share `C:\store` on the destination computer
2. Run the `ScanState.exe` command on the source computer and save the files and settings to `\\<DestinationComputerName>\store`
3. Run the `LoadState.exe ` command on the destination computer and specify `C:\Store` as the store location.
- Shared folder.
- Removable media.
- Directly on the destination computer.
By doing this process, you don't need to save the files to a server.
For example:
1. Create and share `C:\store` on the destination computer.
1. Run the `ScanState.exe` command on the source computer and save the files and settings to `\\<DestinationComputerName>\store`.
1. Run the `LoadState.exe` command on the destination computer and specify `C:\Store` as the store location.
By doing this process, files don't need to be stored to a server.
> [!IMPORTANT]
> If possible, have users store their data within their `%UserProfile%\My Documents` and `%UserProfile%\Application Data` folders. This will reduce the chance of USMT missing critical user data that is located in a directory that USMT is not configured to check.
>
> If possible, have users store their data within their `%UserProfile%\Documents` and `%UserProfile%\Application Data` folders. Having users store their data at these locations reduces the chance of USMT missing critical user data that is located in a directory that USMT isn't configured to check.
### The /localonly command-line option
You should use this option to exclude the data from removable drives and network drives mapped on the source computer. For more information about what is excluded when you specify `/LocalOnly`, see [ScanState Syntax](usmt-scanstate-syntax.md).
This option should be used to exclude the data from removable drives and network drives mapped on the source computer. For more information about what is excluded when `/LocalOnly` is specified, see [ScanState Syntax](usmt-scanstate-syntax.md).
## Related articles
[Plan your migration](usmt-plan-your-migration.md)
- [Plan the migration](usmt-plan-your-migration.md).

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

@ -1,64 +1,71 @@
---
title: Offline Migration Reference (Windows 10)
title: Offline Migration Reference
description: Offline migration enables the ScanState tool to run inside a different Windows OS than the Windows OS from which ScanState is gathering files and settings.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Offline Migration Reference
Offline migration enables the ScanState tool to run inside a different Windows operating system than the Windows operating system from which ScanState is gathering files and settings. There are two primary offline scenarios:
Offline migration enables the **ScanState** tool to run inside a different Windows operating system than the Windows operating system from which **ScanState** is gathering files and settings. There are two primary offline scenarios:
- **Windows PE.** The ScanState tool can be run from within Windows PE, gathering files and settings from the offline Windows operating system on that machine.
- **Windows PE.** The **ScanState** tool can be run from within Windows PE, gathering files and settings from the offline Windows operating system on that machine.
- **Windows.old.** The ScanState tool can now gather files and settings from the Windows.old directory that is created during Windows installation on a partition that contains a previous installation of Windows. For example, the ScanState tool can run in Windows 10, gathering files from a previous Windows 7or Windows 8 installation contained in the Windows.old directory.
- **Windows.old.** The **ScanState** tool can gather files and settings from the **Windows.old** directory. The **Windows.old** directory is created during Windows installation on a partition that contains a previous installation of Windows. For example, the **ScanState** tool can run in Windows, gathering files from a previous Windows installation contained in the **Windows.old** directory.
When you use User State Migration Tool (USMT) 10.0 to gather and restore user state, offline migration reduces the cost of deployment by:
When using the User State Migration Tool (USMT) to gather and restore user state, offline migration reduces the cost of deployment by:
- **Reducing complexity.** In computer-refresh scenarios, migrations from the Windows.old directory reduce complexity by eliminating the need for the ScanState tool to be run before the operating system is deployed. Also, migrations from the Windows.old directory enable ScanState and LoadState to be run successively.
- **Reducing complexity.** In computer-refresh scenarios, migrations from the **Windows.old** directory reduce complexity by eliminating the need for the **ScanState** tool to be run before the operating system is deployed. Also, migrations from the **Windows.old** directory enable **ScanState** and **LoadState** to be run successively.
- **Improving performance.** When USMT runs in an offline Windows Preinstallation Environment (WinPE) environment, it has better access to the hardware resources. Running USMT in WinPE may increase performance on older machines with limited hardware resources and numerous installed software applications.
- **Improving performance.** When USMT runs in an offline Windows Preinstallation Environment (WinPE) environment, it has better access to the hardware resources. Running USMT in WinPE can increase performance on older machines with limited hardware resources and numerous installed software applications.
- **New recovery scenario.** In scenarios where a machine no longer restarts properly, it might be possible to gather user state with the ScanState tool from within WinPE.
- **New recovery scenario.** In scenarios where a machine no longer restarts properly, it might be possible to gather user state with the **ScanState** tool from within WinPE.
## What will migrate offline?
## What migrates offline?
The following user data and settings migrate offline, similar to an online migration:
- Data and registry keys specified in MigXML
- Data and registry keys specified in MigXML.
- User accounts
- User accounts.
- Application settings
- Application settings.
- Limited set of operating-system settings
- Limited set of operating-system settings.
- EFS files
- EFS files.
- Internet Explorer Favorites
- Favorites.
For exceptions to what you can migrate offline, see [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md)
For exceptions to what can be migrated offline, see [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md)
## What offline environments are supported?
All currently supported
The following table defines the supported combination of online and offline operating systems in USMT.
|Running Operating System|Offline Operating System|
|--- |--- |
|WinPE 5.0 or greater, with the MSXML library|Windows 7, Windows 8, Windows 10|
|Windows 7, Windows 8, Windows 10|Windows.old directory|
|---|---|
|Currently supported version of WinPE, with the MSXML library|Windows 7, Windows 8, Windows 10, Windows 11|
|Windows 10, Windows 11|**Windows.old** directory|
> [!NOTE]
> It is possible to run the ScanState tool while the drive remains encrypted by suspending Windows BitLocker Drive Encryption before booting into WinPE. For more information, see [this Microsoft site](/previous-versions/windows/it-pro/windows-7/ee424315(v=ws.10)).
>
> It is possible to run the **ScanState** tool while the drive remains encrypted by suspending Windows BitLocker Drive Encryption before booting into WinPE. For more information, see [BitLocker operations guide: Suspend and resume](/windows/security/operating-system-security/data-protection/bitlocker/operations-guide#suspend-and-resume). If using a Microsoft Configuration Manager task sequence, see [Task sequence steps: Disable BitLocker](/mem/configmgr/osd/understand/task-sequence-steps#BKMK_DisableBitLocker).
## User-group membership and profile control
User-group membership isn't preserved during offline migrations. You must configure a **&lt;ProfileControl&gt;** section in the `Config.xml` file to specify the groups that the migrated users should be made members of. The following example places all migrated users into the Users group:
User-group membership isn't preserved during offline migrations. A **\<ProfileControl\>** section must be configured in the `Config.xml` file to specify the groups that the migrated users should be made members of. The following example places all migrated users into the Users group:
```xml
<Configuration>
@ -84,62 +91,90 @@ An offline migration can either be enabled by using a configuration file on the
|Component|Option|Description|
|--- |--- |--- |
|*ScanState.exe*|**/offline:***&lt;path to Offline.xml&gt;*|This command-line option enables the offline-migration mode and requires a path to an Offline.xml configuration file.|
|*ScanState.exe*|**/offlineWinDir:***&lt;Windows directory&gt;*|This command-line option enables the offline-migration mode and starts the migration from the location specified. It's only for use in WinPE offline scenarios where the migration is occurring from a Windows directory.|
|*ScanState.exe*|**/OfflineWinOld:***&lt;Windows.old directory&gt;*|This command-line option enables the offline migration mode and starts the migration from the location specified. It's only intended to be used in Windows.old migration scenarios, where the migration is occurring from a Windows.old directory.|
|*ScanState.exe*|**/offline:***\<path to Offline.xml\>*|This command-line option enables the offline-migration mode and requires a path to an Offline.xml configuration file.|
|*ScanState.exe*|**/offlineWinDir:***\<Windows directory\>*|This command-line option enables the offline-migration mode and starts the migration from the location specified. It's only for use in WinPE offline scenarios where the migration is occurring from a Windows directory.|
|*ScanState.exe*|**/OfflineWinOld:***\<Windows.old directory\>*|This command-line option enables the offline migration mode and starts the migration from the location specified. Only use in **Windows.old** migration scenarios, where the migration is occurring from a **Windows.old** directory.|
You can use only one of the `/offline`, `/offlineWinDir`, or `/OfflineWinOld` command-line options at a time. USMT doesn't support using more than one together.
Only one of the `/offline`, `/offlineWinDir`, or `/OfflineWinOld` command-line options can be used at a time. USMT doesn't support using more than one together.
## Environment variables
The following system environment variables are necessary in the scenarios outlined below.
System environment variables are necessary in the scenarios outlined in the following table:
|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/><pre class="syntax"><code>Set USMT_WORKING_DIR=[path to working directory]</code></pre>|
*|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/><pre class="syntax"><code>Set MIG_OFFLINE_PLATFORM_ARCH=32</code></pre>|
|**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
Use an `Offline.xml` file when running the ScanState tool on a computer that has multiple Windows directories. The `Offline.xml` file specifies which directories to scan for windows files. An `Offline.xml` file can be used with the `/offline` option as an alternative to specifying a single Windows directory path with the `/offlineDir` option.
Use an `Offline.xml` file when running the **ScanState** tool on a computer that has multiple Windows directories. The `Offline.xml` file specifies which directories to scan for windows files. An `Offline.xml` file can be used with the `/offline` option as an alternative to specifying a single Windows directory path with the `/offlineDir` option.
### &lt;offline&gt;
### \<offline\>
This element contains other elements that define how an offline migration is to be performed.
Syntax: `<offline>` `</offline>`
Syntax:
### &lt;winDir&gt;
```xml
<offline> </offline>
```
This element is a required child of **&lt;offline&gt;** and contains information about how the offline volume can be selected. The migration will be performed from the first element of **&lt;winDir&gt;** that contains a valid Windows system volume.
### \<winDir\>
Syntax: `<winDir>` `</winDir>`
This element is a required child of **\<offline\>** and contains information about how the offline volume can be selected. The migration is performed from the first element of **\<winDir\>** that contains a valid Windows system volume.
### &lt;path&gt;
Syntax:
This element is a required child of **&lt;winDir&gt;** and contains a file path pointing to a valid Windows directory. Relative paths are interpreted from the ScanState tool's working directory.
```xml
<winDir> </winDir>
```
Syntax: `<path> C:\Windows </path>`
### \<path\>
-or-
This element is a required child of **\<winDir\>** and contains a file path pointing to a valid Windows directory. Relative paths are interpreted from the **ScanState** tool's working directory.
Syntax, when used with the **&lt;mappings&gt;** element: `<path> C:\, D:\ </path>`
Syntax:
### &lt;mappings&gt;
```xml
<path> C:\Windows </path>
```
This element is an optional child of **&lt;offline&gt;**. When specified, the **&lt;mappings&gt;** element will override the automatically detected WinPE drive mappings. Each child **&lt;path&gt;** element will provide a mapping from one system volume to another. Additionally, mappings between folders can be provided, since an entire volume can be mounted to a specific folder.
or when used with the **\<mappings\>** element:
Syntax: `<mappings>` `</mappings>`
Syntax:
### &lt;failOnMultipleWinDir&gt;
```xml
<path> C:\, D:\ </path>
```
This element is an optional child of **&lt;offline&gt;**. The **&lt;failOnMultipleWinDir&gt;** element allows the user to specify that the migration should fail when USMT detects that there are multiple instances of Windows installed on the source machine. When the **&lt;failOnMultipleWinDir&gt;** element isn't present, the default behavior is that the migration doesn't fail.
### \<mappings\>
Syntax: `<failOnMultipleWinDir>1</failOnMultipleWinDir>`
This element is an optional child of **\<offline\>**. When specified, the **\<mappings\>** element overrides the automatically detected WinPE drive mappings. Each child **\<path\>** element provides a mapping from one system volume to another. Additionally, mappings between folders can be provided, since an entire volume can be mounted to a specific folder.
-or-
Syntax:
Syntax: `<failOnMultipleWinDir>0</failOnMultipleWinDir>`
```xml
<mappings> </mappings>
```
### \<failOnMultipleWinDir\>
This element is an optional child of **\<offline\>**. The **\<failOnMultipleWinDir\>** element allows the user to specify that the migration should fail when USMT detects that there are multiple instances of Windows installed on the source machine. When the **\<failOnMultipleWinDir\>** element isn't present, the default behavior is that the migration doesn't fail.
Syntax:
```xml
<failOnMultipleWinDir>1</failOnMultipleWinDir>
```
or
Syntax:
```xml
<failOnMultipleWinDir>0</failOnMultipleWinDir>
```
### Offline .xml Example
@ -158,4 +193,4 @@ The following XML example illustrates some of the elements discussed earlier in
## Related articles
[Plan your migration](usmt-plan-your-migration.md)
- [Plan the migration](usmt-plan-your-migration.md).

133
windows/deployment/usmt/understanding-migration-xml-files.md
View File

@ -1,52 +1,58 @@
---
title: Understanding Migration XML Files (Windows 10)
description: Learn how to modify the behavior of a basic User State Migration Tool (USMT) 10.0 migration by using XML files.
title: Understanding Migration XML Files
description: Learn how to modify the behavior of a basic User State Migration Tool (USMT) migration by using XML files.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/23/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Understanding migration XML files
You can modify the behavior of a basic User State Migration Tool (USMT) 10.0 migration by using XML files; these files provide instructions on where and how the USMT tools should gather and apply files and settings. USMT includes three XML files that you can use to customize a basic migration: the `MigDocs.xml` and `MigUser.xml` files, which modify how files are discovered on the source computer, and the MigApps.xml file, which is required in order to migrate supported application settings. You can also create and edit custom XML files and a `Config.xml` file to further customize your migration.
The behavior of a basic User State Migration Tool (USMT) migration can be modified by using XML files. These files provide instructions on where and how the USMT tools should gather and apply files and settings. USMT includes three XML files that can be used to customize a basic migration: the `MigDocs.xml` and `MigUser.xml` files, which modify how files are discovered on the source computer, and the MigApps.xml file, which is required in order to migrate supported application settings. Custom XML files and a `Config.xml` file can be created and edited to further customize the migration.
This article provides an overview of the default and custom migration XML files and includes guidelines for creating and editing a customized version of the `MigDocs.xml` file. The `MigDocs.xml` file uses the new `GenerateDocPatterns` function available in USMT to automatically find user documents on a source computer.
## Overview of the Config.xml file
The `Config.xml` file is the configuration file created by the `/genconfig` option of the ScanState tool; it can be used to modify which operating-system components are migrated by USMT. The `Config.xml` file can be used with other XML files, such as in the following example:
The `Config.xml` file is the configuration file created by the `/genconfig` option of the **ScanState** tool. It can be used to modify which operating-system components USMT migrates. The `Config.xml` file can be used with other XML files, such as in the following example:
`ScanState.exe /i:migapps.xml /i:MigDocs.xml /genconfig:c:\myFolder\Config.xml`
When used this way, the `Config.xml` file tightly controls aspects of the migration, including user profiles, data, and settings, without modifying or creating other XML files. For more information about the `Config.xml` file, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [Config.xml File](usmt-configxml-file.md).
> [!NOTE]
> When modifying the XML elements in the `Config.xml` file, you should edit an element and set the **migrate** property to **no**, rather than deleting the element from the file. If you delete the element instead of setting the property, the component may still be migrated by rules in other XML files.
>
> When modifying the XML elements in the `Config.xml` file, set the **migrate** property on an element to **no** instead of deleting the element from the file. If the element is deleted instead of setting the property, rules in other XML files can still migrate the component.
## Overview of the MigApp.xml file
The `MigApp.xml` file installed with USMT includes instructions to migrate the settings for the applications listed in [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md). You must include the `MigApp.xml` file when using the ScanState and LoadState tools, by using the `/i` option in order to migrate application settings. The `MigDocs.xml` and `MigUser.xml` files don't migrate application settings. You can create a custom XML file to include additional applications. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md).
The `MigApp.xml` file installed with USMT includes instructions to migrate the settings for the applications listed in [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md). In order to migrate application settings, the `MigApp.xml` file must be included when using the **ScanState** and **LoadState** tools by using the `/i` option. The `MigDocs.xml` and `MigUser.xml` files don't migrate application settings. A custom XML file can be created to include additional applications. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md).
> [!IMPORTANT]
> The MigApps.xml file will only detect and migrate .pst files that are linked to Microsoft Office Outlook. For more information about migrating .pst files that are not linked to Outlook, see [Sample migration rules for customized versions of XML files](#sample-migration-rules-for-customized-versions-of-xml-files).
>
> The `MigApps.xml` file only detects and migrates **.pst** files that are linked to Microsoft Office Outlook. For more information about migrating **.pst** files that aren't linked to Outlook, see [Sample migration rules for customized versions of XML files](#sample-migration-rules-for-customized-versions-of-xml-files).
## Overview of the MigDocs.xml file
The `MigDocs.xml` file uses the new `GenerateDocPatterns` helper function to create instructions for USMT to migrate files from the source computer, based on the location of the files. You can use the `MigDocs.xml` file with the ScanState and LoadState tools to perform a more targeted migration than using USMT without XML instructions.
The `MigDocs.xml` file uses the new `GenerateDocPatterns` helper function to create instructions for USMT to migrate files from the source computer, based on the location of the files. The `MigDocs.xml` file can be used with the **ScanState** and **LoadState** tools to perform a more targeted migration than using USMT without XML instructions.
The default `MigDocs.xml` file migrates the following data:
- All files on the root of the drive except `%WINDIR%`, `%PROGRAMFILES%`, `%PROGRAMDATA%`, or `%USERS%`.
- All folders in the root directory of all fixed drives. For example: `c:\data_mail\*[*]`
- All folders in the root directory of all fixed drives. For example: `c:\data_mail\*[*]`.
- All files from the root of the Profiles folder, except for files in the system profile. For example: `c:\users\name[mail.pst]`
- All files from the root of the Profiles folder, except for files in the system profile. For example: `c:\users\name[mail.pst]`.
- All folders from the root of the Profiles folder, except for the system-profile folders. For example: `c:\users\name\new folder\*[*]`
- All folders from the root of the Profiles folder, except for the system-profile folders. For example: `c:\users\name\new folder\*[*]`.
- Standard shared folders:
@ -92,7 +98,7 @@ The default `MigDocs.xml` file migrates the following data:
- FOLDERID_RecordedTV
The default `MigDocs.xml` file won't migrate the following data:
The default `MigDocs.xml` file doesn't migrate the following data:
- Files tagged with both the **hidden** and **system** attributes.
@ -102,11 +108,11 @@ The default `MigDocs.xml` file won't migrate the following data:
- Folders that contain installed applications.
You can also use the `/genmigxml` option with the ScanState tool to review and modify what files will be migrated.
The `/genmigxml` option can be used with the **ScanState** tool to review and modify what files are migrated.
## Overview of the MigUser.xml file
The `MigUser.xml` file includes instructions for USMT to migrate user files based on file name extensions. You can use the `MigUser.xml` file with the ScanState and LoadState tools to perform a more targeted migration than using USMT without XML instructions. The `MigUser.xml` file will gather all files from the standard user-profile folders, and any files on the computer with the specified file name extensions.
The `MigUser.xml` file includes instructions for USMT to migrate user files based on file name extensions. The `MigUser.xml` file can be used with the **ScanState** and **LoadState** tools to perform a more targeted migration than using USMT without XML instructions. The `MigUser.xml` file gathers all files from the standard user-profile folders, and any files on the computer with the specified file name extensions.
The default `MigUser.xml` file migrates the following data:
@ -133,38 +139,41 @@ The default `MigUser.xml` file migrates the following data:
`.accdb`, `.ch3`, `.csv`, `.dif`, `.doc*`, `.dot*`, `.dqy`, `.iqy`, `.mcw`, `.mdb*`, `.mpp`, `.one*`, `.oqy`, `.or6`, `.pot*`, `.ppa`, `.pps*`, `.ppt*`, `.pre`, `.pst`, `.pub`, `.qdf`, `.qel`, `.qph`, `.qsd`, `.rqy`, `.rtf`, `.scd`, `.sh3`, `.slk`, `.txt`, `.vl*`, `.vsd`, `.wk*`, `.wpd`, `.wps`, `.wq1`, `.wri`, `.xl*`, `.xla`, `.xlb`, `.xls*`
> [!NOTE]
>
> The asterisk (`*`) stands for zero or more characters.
> [!NOTE]
>
> The OpenDocument extensions (`*.odt`, `*.odp`, `*.ods`) that Microsoft Office applications can use aren't migrated by default.
The default `MigUser.xml` file doesn't migrate the following data:
- Files tagged with both the **Hidden** and **System** attributes.
- Files and folders on removable drives,
- Files and folders on removable drives.
- Data from the `%WINDIR%`, `%PROGRAMFILES%`, `%PROGRAMDATA%` folders.
- ACLS for files in folders outside the user profile.
You can make a copy of the `MigUser.xml` file and modify it to include or exclude standard user-profile folders and file name extensions. If you know all of the extensions for the files you want to migrate from the source computer, use the `MigUser.xml` file to move all of your relevant data, regardless of the location of the files. However, this provision may result in a migration that contains more files than intended. For example, if you choose to migrate all .jpg files, you may migrate image files such as thumbnails and logos from legacy applications that are installed on the source computer.
The `MigUser.xml` file can be copied and then the copy modified to include or exclude standard user-profile folders and file name extensions. If all of the extensions for the files that need to be migrated from the source computer are known, use the `MigUser.xml` file to move all of the relevant data, regardless of the location of the files. However, adding in all file extensions that need to be migrated to the `MigUser.xml` file can result in a migration that contains more files than intended. For example, if all **.jpg** files are migrated, it can also migrate image files such as thumbnails and logos from legacy applications that are installed on the source computer.
> [!NOTE]
> Each file name extension you include in the rules within the `MigUser.xml` file increases the amount of time needed for the ScanState tool to gather the files for the migration. If you are migrating more than 300 file types, you may experience a slow migration. For more information about other ways to organize the migration of your data, see the [Using multiple XML files](#using-multiple-xml-files) section of this article.
>
> Each file name extension included in the rules within the `MigUser.xml` file increases the amount of time needed for the **ScanState** tool to gather the files for the migration. If more than 300 file types are being migrated, the migration experience can be slow. For more information about other ways to organize the migration of the data, see the [Using multiple XML files](#using-multiple-xml-files) section of this article.
## Using multiple XML files
You can use multiple XML files with the ScanState and LoadState tools. Each of the default XML files included with or generated by USMT is configured for a specific component of the migration. You can also use custom XML files to supplement these default files with more migration rules.
Multiple XML files can be used with the **ScanState** and **LoadState** tools. Each of the default XML files included with or generated by USMT is configured for a specific component of the migration. Custom XML files can also be used to supplement these default files with more migration rules.
|XML migration file|Modifies the following components:|
|--- |--- |
|*Config.xml file*|Operating-system components such as desktop wallpaper and background theme.<br/> You can also overload `Config.xml` to include some application and document settings by generating the `Config.xml` file with the other default XML files. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [Config.xml File](usmt-configxml-file.md).|
|*MigApps.xml file*|Applications settings.|
|*MigUser.xml* or *MigDocs.xml* files|User files and profile settings.|
|*Custom XML files*|Application settings, user profile settings, or user files, beyond the rules contained in the other XML files.|
|**Config.xml file**|Operating-system components such as desktop wallpaper and background theme.<br> The `Config.xml` can also be extended to include some application and document settings by generating the `Config.xml` file with the other default XML files. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [Config.xml File](usmt-configxml-file.md).|
|**MigApps.xml file**|Applications settings.|
|**MigUser.xml** or **MigDocs.xml** files|User files and profile settings.|
|**Custom XML files**|Application settings, user profile settings, or user files, beyond the rules contained in the other XML files.|
For example, you can use all of the XML migration file types for a single migration, as in the following example:
For example, all of the XML migration file types can be used for a single migration, as in the following example:
```cmd
ScanState.exe <store> /config:c:\myFolder\Config.xml /i:migapps.xml /i:MigDocs.xml /i:CustomRules.xml
@ -173,54 +182,61 @@ ScanState.exe <store> /config:c:\myFolder\Config.xml /i:migapps.xml /i:MigDocs.x
### XML rules for migrating user files
> [!IMPORTANT]
> You should not use the `MigUser.xml` and `MigDocs.xml` files together in the same command. Using both XML files can result in duplication of some migrated files. This occurs when conflicting target-location instructions are given in each XML file. The target file will be stored once during the migration, but will be applied by each XML file to a different location on the destination computer.
>
> The `MigUser.xml` and `MigDocs.xml` files shouldn't be used together in the same command. Using both XML files can result in duplication of some migrated files. Duplication of some migrated files can occur when conflicting target-location instructions are given in each XML file. The target file is stored once during the migration, but each XML file applies the file to a different location on the destination computer.
If your data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file will gather a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location. The `MigUser.xml` file migrates only the files with the specified file name extensions.
If the data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file gathers a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location. The `MigUser.xml` file migrates only the files with the specified file name extensions.
If you want more control over the migration, you can create custom XML files. See [Creating and editing a custom XML file](#creating-and-editing-a-custom-xml-file) for more information.
For more control over the migration, create custom XML files. For more information on creating custom XML files, see [Creating and editing a custom XML file](#creating-and-editing-a-custom-xml-file).
## Creating and editing a custom XML file
You can use the `/genmigxml` command-line option to determine which files will be included in your migration. The `/genmigxml` option creates a file in a location you specify, so that you can review the XML rules and make modifications as necessary.
The `/genmigxml` command-line option can be used to determine which files are included in the migration. The `/genmigxml` option creates a file in a specified location. The XML rules in the file can then be reviewed and if necessary, modifications made.
> [!NOTE]
> If you reinstall USMT, the default migration XML files will be overwritten and any customizations you make directly to these files will be lost. Consider creating separate XML files for your custom migration rules and saving them in a secure location.
>
> If USMT is reinstalled, the default migration XML files are overwritten and any customizations made to these files are lost. Consider creating separate XML files for the custom migration rules and saving them in a secure location.
To generate the XML migration rules file for a source computer:
1. Select **Start** > **All Programs** > **Accessories**
2. Right-click **Command Prompt**, and then select **Run as**.
1. Right-click **Command Prompt**, and then select **Run as**.
3. Select an account with administrator privileges, supply a password, and then select **OK**.
1. Select an account with administrator privileges, supply a password, and then select **OK**.
4. At the command prompt, enter:
1. At the command prompt, enter:
```cmd
cd /d <USMTpath>
ScanState.exe /genmigxml: <filepath.xml>
```
Where *&lt;USMTpath&gt;* is the location on your source computer where you've saved the USMT files and tools, and *&lt;filepath.xml&gt;* is the full path to a file where you can save the report. For example, enter:
where:
- **\<USMTpath\>** - location on the source computer of the saved USMT files and tools.
- **\<filepath.xml\>** - full path to a file where the report can be saved.
For example, enter:
```cmd
cd /d c:\USMT
ScanState.exe /genmigxml:"C:\Documents and Settings\USMT Tester\Desktop\genMig.xml"
ScanState.exe /genmigxml:"C:\Users\USMT Tester\Desktop\genMig.xml"
```
### The GenerateDocPatterns function
The `MigDocs.xml` file calls the `GenerateDocPatterns` function, which takes three Boolean values. You can change the settings to modify the way the `MigDocs.xml` file generates the XML rules for migration.
The `MigDocs.xml` file calls the `GenerateDocPatterns` function, which takes three Boolean values. The settings can be changed to modify the way the `MigDocs.xml` file generates the XML rules for migration.
- `ScanProgramFiles`: This argument is valid only when the `GenerateDocPatterns` function is called in a system context. This argument determines whether or not to scan the Program Files directory to gather registered file name extensions for known applications.
**Default value**: False
For example, when set to **TRUE**, the function discovers and migrates .doc files under the Microsoft Office directory, because .doc is a file name extension registered to a Microsoft Office application. The `GenerateDocPatterns` function generates this inclusion pattern for `.doc` files:
For example, when set to **TRUE**, the function discovers and migrates **.doc** files under the Microsoft Office directory, because **.doc** is a file name extension registered to a Microsoft Office application. The `GenerateDocPatterns` function generates this inclusion pattern for `.doc` files:
`<pattern type="File">C:\Program Files\Microsoft Office[.doc]</pattern>`
If a child folder of an included folder contains an installed application, ScanProgramFiles will also create an exclusion rule for the child folder. All folders under the application folder will be scanned recursively for registered file name extensions.
If a child folder of an included folder contains an installed application, `ScanProgramFiles` also creates an exclusion rule for the child folder. All folders under the application folder are scanned recursively for registered file name extensions.
- `IncludePatterns`: This argument determines whether to generate exclude or include patterns in the XML. When this argument is set to **TRUE**, the `GenerateDocPatterns` function generates include patterns, and the function must be added under the `<include>` element. Changing this argument to **FALSE** generates exclude patterns and the function must be added under the `<exclude>` element.
@ -268,7 +284,10 @@ To create exclude data patterns:
### Understanding the system and user context
The migration XML files contain two &lt;component&gt; elements with different **context** settings. The system context applies to files on the computer that aren't stored in the User Profiles directory, while the user context applies to files that are particular to an individual user.
The migration XML files contain two \<component\> elements with different **context** settings:
- The system context applies to files on the computer that aren't stored in the User Profiles directory.
- The user context applies to files that are particular to an individual user.
#### System context
@ -319,27 +338,29 @@ The user context includes rules for data in the User Profiles directory. When ca
- FOLDERID_RecordedTV
> [!NOTE]
> Rules contained in a component that is assigned the user context will be run for each user profile on the computer. Files that are scanned multiple times by the `MigDocs.xml` files will only be copied to the migration store once; however, a large number of rules in the user context can slow down the migration. Use the system context when it is applicable.
>
> Rules contained in a component that is assigned the user context runs for each user profile on the computer. Files that are scanned multiple times by the `MigDocs.xml` files are only copied to the migration store once. However, a large number of rules in the user context can slow down the migration. Use the system context when it's applicable.
### Sample migration rules for customized versions of XML files
> [!NOTE]
> [!TIP]
>
> For best practices and requirements for customized XML files in USMT, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [General Conventions](usmt-general-conventions.md).
### Exclude rules usage examples
In the examples below, the source computer has a .txt file called "new text document" in a directory called "new folder". The default `MigDocs.xml` behavior migrates the new text document.txt file and all files contained in the "new folder" directory. The rules generated by the function are:
In the following examples, the source computer has a **.txt** file called `new text document` in a directory called `new folder`. The default `MigDocs.xml` behavior migrates the new text `document.txt` file and all files contained in the `new folder` directory. The rules generated by the function are:
| Rule | Syntax |
|--- |--- |
|Rule 1|`<pattern type="File">d:\new folder[new text document.txt]</pattern>`|
|Rule 2|`<pattern type="File">d:\new folder[]</pattern>`|
To exclude the new text document.txt file and any .txt files in "new folder", you can do the following modification:
To exclude the new text `document.txt` file and any **.txt** files in `new folder`, the following modifications can be made:
#### Example 1: Exclude all .txt files in a folder
To exclude Rule 1, there needs to be an exact match of the file name. However, for Rule 2, you can create a pattern to exclude files by using the file name extension.
To exclude Rule 1, there needs to be an exact match of the file name. However, for Rule 2, a pattern can be created to exclude files by using the file name extension.
```xml
<exclude>
@ -352,7 +373,7 @@ To exclude Rule 1, there needs to be an exact match of the file name. However, f
#### Example 2: Use the UnconditionalExclude element to give a rule precedence over include rules
If you don't know the file name or location of the file, but you do know the file name extension, you can use the `GenerateDrivePatterns` function. However, the rule will be less specific than the default include rule generated by the `MigDocs.xml` file, so it will not have precedence. You must use the &lt;UnconditionalExclude&gt; element to give this rule precedence over the default include rule. For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md).
If the file name or location of the file isn't known, but the file name extension is known, the `GenerateDrivePatterns` function can be used. However, the rule is less specific than the default include rule generated by the `MigDocs.xml` file, so it doesn't have precedence. The \<UnconditionalExclude\> element must be used to give this rule precedence over the default include rule. For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md).
```xml
<unconditionalExclude>
@ -364,7 +385,7 @@ If you don't know the file name or location of the file, but you do know the fil
#### Example 3: Use a UserandSystem context component to run rules in both contexts
If you want the **&lt;UnconditionalExclude&gt;** element to apply to both the system and user context, you can create a third component using the **UserandSystem** context. Rules in this component will be run in both contexts.
To apply the **\<UnconditionalExclude\>** element to both the system and user context, a third component can be created using the **UserandSystem** context. Rules in this component run in both contexts.
```xml
<component type="Documents" context="UserandSystem">
@ -381,15 +402,15 @@ If you want the **&lt;UnconditionalExclude&gt;** element to apply to both the sy
</component>
```
For more examples of exclude rules that you can use in custom migration XML files, see [Exclude Files and Settings](usmt-exclude-files-and-settings.md).
For more examples of exclude rules that can be used in custom migration XML files, see [Exclude Files and Settings](usmt-exclude-files-and-settings.md).
### Include rules usage examples
The application data directory is the most common location that you would need to add an include rule for. The `GenerateDocPatterns` function excludes this location by default. If your company uses an application that saves important data to this location, you can create include rules to migrate the data. For example, the default location for .pst files is: `%CSIDL_LOCAL_APPDATA%\Microsoft\Outlook`. The `MigApp.xml` file contains migration rules to move only those .pst files that are linked to Microsoft Outlook. To include .pst files that aren't linked, you can do the following modification:
The application data directory is the most common location that an include rule would need to be added for. The `GenerateDocPatterns` function excludes this location by default. If the organization uses an application that saves important data to this location, include rules can be created to migrate the data. For example, the default location for **.pst** files is: `%CSIDL_LOCAL_APPDATA%\Microsoft\Outlook`. The `MigApp.xml` file contains migration rules to move only those **.pst** files that are linked to Microsoft Outlook. To include **.pst** files that aren't linked, the following modification can be made:
#### Example 1: Include a file name extension in a known user folder
This rule will include .pst files that are located in the default location, but aren't linked to Microsoft Outlook. Use the user context to run this rule for each user on the computer.
This rule includes **.pst** files that are located in the default location, but aren't linked to Microsoft Outlook. Use the user context to run this rule for each user on the computer.
```xml
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
@ -401,7 +422,7 @@ This rule will include .pst files that are located in the default location, but
#### Example 2: Include a file name extension in Program Files
For locations outside the user profile, such as the Program Files folder, you can add the rule to the system context component.
For locations outside the user profile, such as the Program Files folder, the rule can be added to the system context component.
```xml
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
@ -411,19 +432,19 @@ For locations outside the user profile, such as the Program Files folder, you ca
</include>
```
For more examples of include rules that you can use in custom migration XML files, see [Include Files and Settings](usmt-include-files-and-settings.md).
For more examples of include rules that can be used in custom migration XML files, see [Include Files and Settings](usmt-include-files-and-settings.md).
> [!NOTE]
> [!TIP]
>
> For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md).
## Next steps
You can include additional rules for the migration in the `MigDocs.xml` file or other XML migration files. For example, you can use the `<locationModify>` element to move files from the folder where they were gathered to a different folder, when they're applied to the destination computer.
Additional rules for the migration can be included in the `MigDocs.xml` file or other XML migration files. For example, the `<locationModify>` element can be used to move files from the folder where they were gathered to a different folder, when they're applied to the destination computer.
You can use an XML schema (MigXML.xsd) file to validate the syntax of your customized XML files. For more information, see [USMT Resources](usmt-resources.md).
An XML schema (`MigXML.xsd`) file can be used to validate the syntax of the customized XML files. For more information, see [USMT Resources](usmt-resources.md).
## Related articles
[Exclude files and settings](usmt-exclude-files-and-settings.md)
[Include files and settings](usmt-include-files-and-settings.md)
- [Exclude files and settings](usmt-exclude-files-and-settings.md).
- [Include files and settings](usmt-include-files-and-settings.md).

136
windows/deployment/usmt/usmt-best-practices.md
View File

@ -1,135 +1,141 @@
---
title: USMT Best Practices (Windows 10)
description: This article discusses general and security-related best practices when using User State Migration Tool (USMT) 10.0.
title: USMT Best Practices
description: This article discusses general and security-related best practices when using User State Migration Tool (USMT).
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# USMT best practices
This article discusses general and security-related best practices when using User State Migration Tool (USMT) 10.0.
This article discusses general and security-related best practices when using User State Migration Tool (USMT).
## General best practices
- **Install applications before running the LoadState tool**
- **Install applications before running the LoadState tool.**
Though it isn't always essential, it's best practice to install all applications on the destination computer before restoring the user state. Installing applications before restoring user state helps ensure that migrated settings are preserved.
Though it isn't always essential, it's best practice to install all applications on the destination computer before restoring the user state. Installing applications before restoring user state helps ensure that migrated settings are preserved.
- **Don't use MigUser.xml and MigDocs.xml together**
- **Don't use MigUser.xml and MigDocs.xml together.**
If you use both .xml files, some migrated files may be duplicated if conflicting instructions are given about target locations. You can use the `/genmigxml` command-line option to determine which files will be included in your migration, and to determine if any modifications are necessary. For more information, see [Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md).
If both `MigUser.xml` and `MigDocs.xml` are used together, some migrated files can be duplicated if conflicting instructions are given about target locations. The `/genmigxml` command-line option can be used to determine which files are included in the migration, and to determine if any modifications are necessary. For more information, see [Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md).
- **Use MigDocs.xml for a better migration experience**
- **Use MigDocs.xml for a better migration experience.**
If your data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` file is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file will gather a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location, and on registered file type by querying the registry for registered application extensions. The `MigUser.xml` file migrates only the files with the specified file extensions.
If the data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` file is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file gathers a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location, and on registered file type by querying the registry for registered application extensions. The `MigUser.xml` file migrates only the files with the specified file extensions.
- **Close all applications before running either the ScanState or LoadState tools**
- **Close all applications before running either the ScanState or LoadState tools.**
Although using the `/vsc` switch can allow the migration of many files that are open with another application, it's a best practice to close all applications in order to ensure all files and settings migrate. Without the `/vsc` or `/c` switch USMT will fail when it can't migrate a file or setting. When you use the `/c` option, USMT will ignore any files or settings that it can't migrate and log an error each time.
Although using the `/vsc` switch can allow the migration of many files that are open with another application, it's a best practice to close all applications in order to ensure all files and settings migrate. Without the `/vsc` or `/c` switch, USMT fails when it can't migrate a file or setting. When the `/c` option is used, USMT ignores any files or settings that it can't migrate and log an error each time.
- **Log off after you run the LoadState**
- **Log off after running the LoadState.**
Some settings, such as fonts, wallpaper, and screensaver settings, won't take effect until the next time the user logs on. For this reason, you should sign out after you run the LoadState tool.
Some settings, such as fonts, wallpaper, and screensaver settings, won't take effect until the next time the user logs on. For this reason, sign out after running the **LoadState** tool.
- **Managed environment**
- **Managed environment.**
To create a managed environment, you can move all of the end user's documents into My Documents (%CSIDL\_PERSONAL%). We recommend that you migrate files into the smallest-possible number of folders on the destination computer. Minimizing folders will help you to clean up files on the destination computer, if the `LoadState.exe` command fails before completion.
To create a managed environment, all of the end user's documents can be moved into the **Documents** folder (%CSIDL\_PERSONAL%). Microsoft recommends migrating files into the smallest-possible number of folders on the destination computer. Minimizing folders helps to clean up files on the destination computer if the `LoadState.exe` command fails before completion.
- **Chkdsk.exe**
- **Chkdsk.exe.**
We recommend that you run **Chkdsk.exe** before running the ScanState and LoadState tools. **Chkdsk.exe** creates a status report for a hard disk drive and lists and corrects common errors. For more information about the **Chkdsk.exe** tool, see [Chkdsk](/previous-versions/windows/it-pro/windows-xp/bb490876(v=technet.10)).
Microsoft recommends running **Chkdsk.exe** before running the **ScanState** and **LoadState** tools. **Chkdsk.exe** creates a status report for a hard disk drive and lists and corrects common errors. For more information about the **Chkdsk.exe** tool, see [Chkdsk](/previous-versions/windows/it-pro/windows-xp/bb490876(v=technet.10)).
- **Migrate in groups**
- **Migrate in groups.**
If you decide to perform the migration while users are using the network, it's best to migrate user accounts in groups. To minimize the impact on network performance, determine the size of the groups based on the size of each user account. Migrating in phases also allows you to make sure each phase is successful before starting the next phase. Using this method, you can make any necessary modifications to your plan between groups.
If the migration is performed while users are using the network, it's best to migrate user accounts in groups. To minimize the effect on network performance, determine the size of the groups based on the size of each user account. Migrating in phases also allows making sure each phase is successful before starting the next phase. When this method is, any necessary modifications can be made to the plan between groups.
## Security best practices
As the authorized administrator, it is your responsibility to protect the privacy of the users and maintain security during and after the migration. In particular, you must consider the following issues:
As the authorized administrator, it's the responsibility to protect the privacy of the users and maintain security during and after the migration. In particular, the following issues must be considered:
- **Encrypting File System (EFS)**
- **Encrypting File System (EFS).**
Take extreme caution when migrating encrypted files, because the end user doesn't need to be logged on to capture the user state. By default, USMT fails if an encrypted file is found. For specific instructions about EFS best practices, see [Migrate EFS Files and Certificates](usmt-migrate-efs-files-and-certificates.md).
Take extreme caution when migrating encrypted files, because the end user doesn't need to be logged on to capture the user state. By default, USMT fails if an encrypted file is found. For specific instructions about EFS best practices, see [Migrate EFS Files and Certificates](usmt-migrate-efs-files-and-certificates.md).
> [!NOTE]
> If you migrate an encrypted file without also migrating the certificate, end users will not be able to access the file after the migration.
> [!NOTE]
>
> If an encrypted file is migrated without also migrating the certificate, end users won't be able to access the file after the migration.
- **Encrypt the store**
- **Encrypt the store.**
Consider using the `/encrypt` option with the `ScanState.exe` command and the `/decrypt` option with the `LoadState.exe` command. However, use extreme caution with this set of options, because anyone who has access to the `ScanState.exe` command-line script also has access to the encryption key.
Consider using the `/encrypt` option with the `ScanState.exe` command and the `/decrypt` option with the `LoadState.exe` command. However, use extreme caution with this set of options, because anyone who has access to the `ScanState.exe` command-line script also has access to the encryption key.
- **Virus Scan**
- **Virus Scan.**
We recommend that you scan both the source and destination computers for viruses before running USMT. In addition, you should scan the destination computer image. To help protect data from viruses, we strongly recommend running an antivirus utility before migration.
Microsoft recommends to scan both the source and destination computers for viruses before running USMT. In addition, the destination computer image should be scanned. To help protect data from viruses, Microsoft strongly recommends running an antivirus utility before migration.
- **Maintain security of the file server and the deployment server**
- **Maintain security of the file server and the deployment server.**
We recommend that you manage the security of the file and deployment servers. It's important to make sure that the file server where you save the store is secure. You must also secure the deployment server, to ensure that the user data that is in the log files isn't exposed. We also recommend that you only transmit data over a secure Internet connection, such as a virtual private network. For more information about network security, see [Microsoft Security Compliance Manager](https://www.microsoft.com/download/details.aspx?id=53353).
Microsoft recommends managing the security of the file and deployment servers. It's important to make sure that the file server where the store is saved is secure. The deployment server must also be secured to ensure that the user data that is in the log files isn't exposed. Microsoft also recommends to only transmit data over a secure network connection, such as a virtual private network. For more information about network security, see [Microsoft Security Compliance Manager](https://www.microsoft.com/download/details.aspx?id=53353).
- **Password Migration**
- **Password Migration.**
To ensure the privacy of the end users, USMT doesn't migrate passwords, including passwords for applications such as Windows Live™ Mail, Microsoft Internet Explorer®, and Remote Access Service (RAS) connections and mapped network drives. It's important to make sure that end users know their passwords.
To ensure the privacy of the end users, USMT doesn't migrate passwords, including passwords for applications or mapped network drives. It's important to make sure that end users know their passwords.
- **Local Account Creation**
- **Local Account Creation.**
Before you migrate local accounts, see the Migrating Local Accounts section in the [Identify Users](usmt-identify-users.md) article.
Before local accounts are migrated, see the Migrating Local Accounts section in the [Identify Users](usmt-identify-users.md) article.
## XML file best practices
- **Specify the same set of mig\*.xml files in both the ScanState and the LoadState tools**
- **Specify the same set of mig\*.xml files in both the ScanState and the LoadState tools.**
If you used a particular set of mig\*.xml files in the ScanState tool, either called through the `/auto` option, or individually through the `/i` option, then you should use same option to call the exact same mig\*.xml files in the LoadState tool.
If a particular set of mig\*.xml files are used with the **ScanState** tool, either called through the `/auto` option, or individually through the `/i` option, then the same option should be used to call the exact same mig\*.xml files in the **LoadState** tool.
- **The &lt;CustomFileName&gt; in the migration urlid should match the name of the file**
- **The \<CustomFileName\> in the migration urlid should match the name of the file.**
Although it isn't a requirement, it's good practice for **&lt;CustomFileName&gt;** to match the name of the file. For example, the following example is from the `MigApp.xml` file:
Although it isn't a requirement, it's good practice for **\<CustomFileName\>** to match the name of the file. For example, the following example is from the `MigApp.xml` file:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/migapp">
```
```xml
<?xml version="1.0" encoding="UTF-8"?>
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/migapp">
```
- **Use the XML Schema (MigXML.xsd) when authoring .xml files to validate syntax**
- **Use the XML Schema (MigXML.xsd) when authoring .xml files to validate syntax.**
The `MigXML.xsd` schema file shouldn't be included on the command line or in any of the .xml files.
The `MigXML.xsd` schema file shouldn't be included on the command line or in any of the **.xml** files.
- **Use the default migration XML files as models**
- **Use the default migration XML files as models.**
To create a custom .xml file, you can use the migration .xml files as models to create your own. If you need to migrate user data files, model your custom .xml file on `MigUser.xml`. To migrate application settings, model your custom .xml file on the `MigApp.xml` file.
To create a custom **.xml** file, migration **.xml** files can be used as models to create customized versions. If user data files need to be migrated, model the custom **.xml** file on `MigUser.xml`. To migrate application settings, model the custom **.xml** file on the `MigApp.xml` file.
- **Consider the impact on performance when using the &lt;context&gt; parameter**
- **Consider the impact on performance when using the \<context\> parameter.**
Your migration performance can be affected when you use the **&lt;context&gt;** element with the **&lt;component&gt;** element; for example, as in when you want to encapsulate logical units of file- or path-based **&lt;include&gt;** and **&lt;exclude&gt;** rules.
The migration performance can be affected when the **\<context\>** element is used with the **\<component\>** element. For example, when encapsulating logical units of file- or path-based **\<include\>** and **\<exclude\>** rules.
In the **User** context, a rule is processed one time for each user on the system.
In the **User** context, a rule is processed one time for each user on the system.
In the **System** context, a rule is processed one time for the system.
In the **System** context, a rule is processed one time for the system.
In the **UserAndSystem** context, a rule is processed one time for each user on the system and one time for the system.
In the **UserAndSystem** context, a rule is processed one time for each user on the system and one time for the system.
> [!NOTE]
>
> The number of times a rule is processed doesn't affect the number of times a file is migrated. The USMT migration engine ensures that each file migrates only once.
> [!NOTE]
> The number of times a rule is processed does not affect the number of times a file is migrated. The USMT migration engine ensures that each file migrates only once.
- **Microsoft recommends to create a separate .xml file instead of adding .xml code to one of the existing migration .xml files.**
- **We recommend that you create a separate .xml file instead of adding your .xml code to one of the existing migration .xml files**
For example, for code that migrates the settings for an application, the code shouldn't just be added to the `MigApp.xml` file.
For example, if you have code that migrates the settings for an application, you shouldn't just add the code to the `MigApp.xml` file.
- **Custom .xml files shouldn't be created to alter the operating system settings that are migrated.**
- **You should not create custom .xml files to alter the operating system settings that are migrated**
Manifest files determine what settings are migrated. Manifest files can't be modified. Since manifest files can't be modified, to exclude certain operating system settings from the migration, create and modify a `Config.xml` file instead.
These settings are migrated by manifests and you can't modify those files. If you want to exclude certain operating system settings from the migration, you should create and modify a `Config.xml` file.
- **The asterisk (\*) wildcard character can be used in any migration XML file that is created.**
- **You can use the asterisk (\*) wildcard character in any migration XML file that you create**
> [!NOTE]
> The question mark is not valid as a wildcard character in USMT .xml files.
> [!NOTE]
>
> The question mark isn't valid as a wildcard character in USMT **.xml** files.
## Related articles
[Migration store encryption](usmt-migration-store-encryption.md)
[Plan your migration](usmt-plan-your-migration.md)
- [Migration store encryption](usmt-migration-store-encryption.md).
- [Plan the migration](usmt-plan-your-migration.md).

26
windows/deployment/usmt/usmt-choose-migration-store-type.md
View File

@ -1,30 +1,38 @@
---
title: Choose a Migration Store Type (Windows 10)
description: Learn how to choose a migration store type and estimate the amount of disk space needed for computers in your organization.
title: Choose a Migration Store Type
description: Learn how to choose a migration store type and estimate the amount of disk space needed for computers in the organization.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Choose a migration store type
One of the main considerations for planning your migration is to determine which migration store type best meets your needs. As part of these considerations, determine how much space is required to run the User State Migration Tool (USMT) 10.0 components on your source and destination computers, and how much space is needed to create and host the migration store, whether you're using a local share, network share, or storage device. The final consideration is ensuring that user date integrity is maintained by encrypting the migration store.
One of the main considerations for planning the migration is to determine which migration store type best meets the organization's needs. As part of these considerations, determine the following items:
- How much space is required to run the User State Migration Tool (USMT) components on the source and destination computers.
- How much space is needed to create and host the migration store.
- Whether a local share, network share, or storage device should be used.
- Ensure that user date integrity is maintained by encrypting the migration store.
## In this section
| Link | Description |
|--- |--- |
|[Migration store types overview](migration-store-types-overview.md)|Choose the migration store type that works best for your needs and migration scenario.|
|[Estimate migration store size](usmt-estimate-migration-store-size.md)|Estimate the amount of disk space needed for computers in your organization based on information about your organization's infrastructure.|
|[Migration store types overview](migration-store-types-overview.md)|Choose the migration store type that works best for the organization's needs and migration scenario.|
|[Estimate migration store size](usmt-estimate-migration-store-size.md)|Estimate the amount of disk space needed for computers in the organization based on information about the organization's infrastructure.|
|[Hard-link migration store](usmt-hard-link-migration-store.md)|Learn about hard-link migration stores and the scenarios in which they're used.|
|[Migration store encryption](usmt-migration-store-encryption.md)|Learn about the using migration store encryption to protect user data integrity during a migration.|
## Related articles
[Plan your migration](usmt-plan-your-migration.md)
[User State Migration Tool (USMT) how-to topics](usmt-how-to.md)
- [Plan the migration](usmt-plan-your-migration.md)
- [User State Migration Tool (USMT) how-articles](usmt-how-to.md)

16
windows/deployment/usmt/usmt-command-line-syntax.md
View File

@ -1,23 +1,27 @@
---
title: User State Migration Tool (USMT) Command-line Syntax (Windows 10)
description: Learn about the User State Migration Tool (USMT) command-line syntax for using the ScanState tool, LoadState tool, and UsmtUtils tool.
title: User State Migration Tool (USMT) Command-line Syntax
description: Learn about the User State Migration Tool (USMT) command-line syntax for using the **ScanState** tool, **LoadState** tool, and UsmtUtils tool.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# User State Migration Tool (USMT) command-line syntax
The User State Migration Tool (USMT) 10.0 migrates user files and settings during large deployments of Windows. To improve and simplify the migration process, USMT captures desktop, network, and application settings in addition to a user's files. USMT then migrates these items to a new Windows installation.
The User State Migration Tool (USMT) migrates user files and settings during large deployments of Windows. To improve and simplify the migration process, USMT captures desktop, network, and application settings in addition to a user's files. USMT then migrates these items to a new Windows installation.
## In this Section
| Link | Description |
|--- |--- |
|[ScanState syntax](usmt-scanstate-syntax.md)|Lists the command-line options for using the ScanState tool.|
|[LoadState syntax](usmt-loadstate-syntax.md)|Lists the command-line options for using the LoadState tool.|
|[**ScanState** syntax](usmt-scanstate-syntax.md)|Lists the command-line options for using the **ScanState** tool.|
|[LoadState syntax](usmt-loadstate-syntax.md)|Lists the command-line options for using the **LoadState** tool.|
|[UsmtUtils syntax](usmt-utilities.md)|Lists the command-line options for using the UsmtUtils tool.|

81
windows/deployment/usmt/usmt-common-migration-scenarios.md
View File

@ -1,109 +1,120 @@
---
title: Common Migration Scenarios (Windows 10)
description: See how the User State Migration Tool (USMT) 10.0 is used when planning hardware and/or operating system upgrades.
title: Common Migration Scenarios
description: See how the User State Migration Tool (USMT) is used when planning hardware and/or operating system upgrades.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Common Migration Scenarios
You use the User State Migration Tool (USMT) 10.0 when hardware and/or operating system upgrades are planned for a large number of computers. USMT manages the migration of an end-user's digital identity by capturing the user's operating-system settings, application settings, and personal files from a source computer and reinstalling them on a destination computer after the upgrade has occurred.
The User State Migration Tool (USMT) can be used when hardware and/or operating system upgrades are planned for a large number of computers. USMT manages the migration of an end-user's digital identity by capturing from a source computer the following user's items:
One common scenario is when the operating system is upgraded on existing hardware without the hardware being replaced. This scenario is referred to as *PC-refresh*. A second common scenario is known as *PC replacement*, where one piece of hardware is being replaced, typically by newer hardware and a newer operating system.
- Operating-system settings.
- Application settings.
- Personal files.
Once these items are capture, they're reinstalled on a destination computer after the upgrade completes.
One common scenario is when the operating system is upgraded on existing hardware without the hardware being replaced. This scenario is referred to as **PC-refresh**. A second common scenario is known as **PC replacement**, where one piece of hardware is being replaced, typically by newer hardware and a newer operating system.
## PC-refresh
The following diagram shows a PC-refresh migration, also known as a computer refresh migration. First, the administrator migrates the user state from a source computer to an intermediate store. After installing the operating system, the administrator migrates the user state back to the source computer.
The following diagram shows a PC-refresh migration, also known as a computer refresh migration. First, the administrator migrates the user state from a source computer to an intermediate store. After the administrator installs the operating system, they migrate the user state back to the source computer.
![usmt pc refresh scenario.](images/dep-win8-l-usmt-pcrefresh.jpg)
### Scenario One: PC-refresh offline using Windows PE and a hard-link migration store
A company has received funds to update the operating system on all of its computers in the accounting department to Windows 10. Each employee will keep the same computer, but the operating system on each computer will be updated. In this scenario, the update is being handled offline, without a network connection. An administrator uses Windows Preinstallation Environment (WinPE) and a hard-link migration store to save each user state to their respective computer.
An organization receives funds to update the operating system on all of its computers in the accounting department to the latest supported version of Windows. Each employee keeps the same computer, but the operating system on each computer will be updated. In this scenario, the update is being handled offline, without a network connection. An administrator uses Windows Preinstallation Environment (WinPE) and a hard-link migration store to save each user state to their respective computer.
1. On each computer, the administrator boots the machine into WinPE and runs the **ScanState** command-line tool, specifying the `/hardlink /nocompress` command-line options. **ScanState** saves the user state to a hard-link migration store on each computer, improving performance by minimizing network traffic and minimizing migration failures on computers with limited space available on the hard drive.
2. On each computer, the administrator installs the company's standard operating environment (SOE) which includes Windows 10 and other company applications.
1. On each computer, the administrator installs the organization's standard operating environment (SOE) which includes the latest supported version of Windows and other organization applications.
3. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back to each computer.
1. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back to each computer.
### Scenario Two: PC-refresh using a compressed migration store
A company has received funds to update the operating system on all of its computers to Windows 10. Each employee will keep the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses a compressed migration store to save the user states to a server.
An organization receives funds to update the operating system on all of its computers to the latest supported version of Windows. Each employee keeps the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses a compressed migration store to save the user states to a server.
1. The administrator runs the **ScanState** command-line tool on each computer. **ScanState** saves each user state to a server.
2. On each computer, the administrator installs the company's standard SOE that includes Windows 10 and other company applications.
1. On each computer, the administrator installs the organization's standard SOE that includes the latest supported version of Windows and other organization applications.
3. The administrator runs the **LoadState** command-line tool on each source computer, and **LoadState** restores each user state back to the computer.
1. The administrator runs the **LoadState** command-line tool on each source computer, and **LoadState** restores each user state back to the computer.
### Scenario Three: PC-refresh using a hard-link migration store
A company has received funds to update the operating system on all of its computers to Windows 10. Each employee will keep the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses a hard-link migration store to save each user state to their respective computer.
An organization receives funds to update the operating system on all of its computers to the latest supported version of Windows. Each employee keeps the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses a hard-link migration store to save each user state to their respective computer.
1. The administrator runs the **ScanState** command-line tool on each computer, specifying the `/hardlink /nocompress` command-line options. **ScanState** saves the user state to a hard-link migration store on each computer, improving performance by minimizing network traffic and minimizing migration failures on computers with limited space available on the hard drive.
2. On each computer, the administrator installs the company's SOE that includes Windows 10 and other company applications.
1. On each computer, the administrator installs the organization's SOE that includes the latest supported version of Windows and other organization applications.
3. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back on each computer.
1. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back on each computer.
### Scenario Four: PC-refresh using Windows.old folder and a hard-link migration store
A company has decided to update the operating system on all of its computers to Windows 10. Each employee will keep the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses Windows.old and a hard-link migration store to save each user state to their respective computer.
An organization decides to update the operating system on all of its computers to the latest supported version of Windows. Each employee keeps the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses **Windows.old** and a hard-link migration store to save each user state to their respective computer.
1. The administrator clean installs Windows 10 on each computer, making sure that the Windows.old directory is created by installing Windows 10 without formatting or repartitioning and by selecting a partition that contains the previous version of Windows.
1. The administrator clean installs the latest supported version of Windows on each computer. During the install, they make sure that the **Windows.old** directory is created by taking the following actions:
2. On each computer, the administrator installs the company's SOE that includes company applications.
- Performing the install without formatting or repartitioning the disk.
- Selecting a partition that contains the previous version of Windows.
3. The administrator runs the **ScanState** and **LoadState** command-line tools successively on each computer while specifying the `/hardlink /nocompress` command-line options.
1. On each computer, the administrator installs the organization's SOE that includes organization applications.
1. The administrator runs the **ScanState** and **LoadState** command-line tools successively on each computer while specifying the `/hardlink /nocompress` command-line options.
## PC-replacement
The following diagram shows a PC-replacement migration. First, the administrator migrates the user state from the source computer to an intermediate store. After installing the operating system on the destination computer, the administrator migrates the user state from the store to the destination computer.
The following diagram shows a PC-replacement migration. First, the administrator migrates the user state from the source computer to an intermediate store. After the administrator installs the operating system on the destination computer, they migrate the user state from the store to the destination computer.
![usmt pc replace scenario.](images/dep-win8-l-usmt-pcreplace.jpg)
### Scenario One: Offline migration using Windows PE and an external migration store
A company is allocating 20 new computers to users in the accounting department. The users each have a source computer with their files and settings. In this scenario, migration is being handled offline, without a network connection.
An organization is allocating 20 new computers to users in the accounting department. The users each have a source computer with their files and settings. In this scenario, migration is being handled offline, without a network connection.
1. On each source computer, an administrator boots the machine into WinPE and runs **ScanState** to collect the user state to either a server or an external hard disk.
2. On each new computer, the administrator installs the company's SOE that includes Windows 10 and other company applications.
1. On each new computer, the administrator installs the organization's SOE that includes the latest supported version of Windows and other organization applications.
3. On each of the new computers, the administrator runs the **LoadState** tool, restoring each user state from the migration store to one of the new computers.
1. On each of the new computers, the administrator runs the **LoadState** tool, restoring each user state from the migration store to one of the new computers.
### Scenario Two: Manual network migration
A company receives 50 new laptops for their managers and needs to reallocate 50 older laptops to new employees. In this scenario, an administrator runs the **ScanState** tool from the cmd prompt on each computer to collect the user states and save them to a server in a compressed migration store.
An organization receives 50 new laptops for their managers and needs to reallocate 50 older laptops to new employees. In this scenario, an administrator runs the **ScanState** tool from the cmd prompt on each computer to collect the user states and save them to a server in a compressed migration store.
1. The administrator runs the **ScanState** tool on each of the manager's old laptops, and saves each user state to a server.
2. On the new laptops, the administrator installs the company's SOE, which includes Windows 10 and other company applications.
1. On the new laptops, the administrator installs the organization's SOE, which includes the latest supported version of Windows and other organization applications.
3. The administrator runs the **LoadState** tool on the new laptops to migrate the managers' user states to the appropriate computer. The new laptops are now ready for the managers to use.
1. The administrator runs the **LoadState** tool on the new laptops to migrate the managers' user states to the appropriate computer. The new laptops are now ready for the managers to use.
4. On the old computers, the administrator installs the company's SOE, which includes Windows 10, Microsoft Office, and other company applications. The old computers are now ready for the new employees to use.
1. On the old computers, the administrator installs the organization's SOE, which includes the latest supported version of Windows, Microsoft Office, and other organization applications. The old computers are now ready for the new employees to use.
### Scenario Three: Managed network migration
A company is allocating 20 new computers to users in the accounting department. The users each have a source computer that contains their files and settings. An administrator uses a management technology such as a sign-in script or a batch file to run **ScanState** on each source computer to collect the user states and save them to a server in a compressed migration store.
An organization is allocating 20 new computers to users in the accounting department. The users each have a source computer that contains their files and settings. An administrator uses a management technology such as a sign-in script or a batch file to run **ScanState** on each source computer to collect the user states and save them to a server in a compressed migration store.
1. On each source computer, the administrator runs the **ScanState** tool using Microsoft Configuration Manager, Microsoft Deployment Toolkit (MDT), a sign-in script, a batch file, or a non-Microsoft management technology. **ScanState** collects the user state from each source computer and then saves it to a server.
2. On each new computer, the administrator installs the company's SOE, which includes Windows 10 and other company applications.
1. On each new computer, the administrator installs the organization's SOE, which includes the latest supported version of Windows and other organization applications.
3. On each of the new computers, the administrator runs the **LoadState** tool using Microsoft Configuration Manager, a sign-in script, a batch file, or a non-Microsoft management technology. **LoadState** migrates each user state from the migration store to one of the new computers.
1. On each of the new computers, the administrator runs the **LoadState** tool using Microsoft Configuration Manager, a sign-in script, a batch file, or a non-Microsoft management technology. **LoadState** migrates each user state from the migration store to one of the new computers.
## Related articles
[Plan your migration](usmt-plan-your-migration.md)
[Choose a migration store type](usmt-choose-migration-store-type.md)
[Offline migration reference](offline-migration-reference.md)
- [Plan the migration](usmt-plan-your-migration.md).
- [Choose a migration store type](usmt-choose-migration-store-type.md).
- [Offline migration reference](offline-migration-reference.md).

236
windows/deployment/usmt/usmt-configxml-file.md
View File

@ -1,53 +1,66 @@
---
title: Config.xml File (Windows 10)
description: Learn how the Config.xml file is an optional User State Migration Tool (USMT) 10.0 file that you can create using the /genconfig option with the ScanState.exe tool.
title: Config.xml File
description: Learn how the Config.xml file is an optional User State Migration Tool (USMT) file that can be created using the /genconfig option with the ScanState.exe tool.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Config.xml File
The `Config.xml` file is an optional User State Migration Tool (USMT) 10.0 file that you can create using the `/genconfig` option with the ScanState tool. If you want to include all of the default components, and don't want to change the default store-creation or profile-migration behavior, you don't need to create a `Config.xml` file.
The `Config.xml` file is an optional User State Migration Tool (USMT) file that can be created using the `/genconfig` option with the **ScanState** tool. If all of the default components should be included and no changes need to be made to the default store-creation or profile-migration behavior, a `Config.xml` file doesn't need to be created.
However, if you're satisfied with the default migration behavior defined in the `MigApp.xml`, `MigUser.xml` and `MigDocs.xml` files, but you want to exclude certain components, you can create and modify a `Config.xml` file and leave the other .xml files unchanged. For example, you must create and modify the `Config.xml` file if you want to exclude any of the operating-system settings that are migrated. It's necessary to create and modify this file if you want to change any of the default store-creation or profile-migration behavior.
However, if the default migration behavior defined in the `MigApp.xml`, `MigUser.xml` and `MigDocs.xml` files is satisfactory, but certain components need to be excluded, a `Config.xml` file can be created and modified while leaving the other **.xml** files unchanged. For example, a `Config.xml` file must be created to exclude any of the operating-system settings that are migrated. It's necessary to create and modify the `Config.xml` file to change any of the default store-creation or profile-migration behavior.
The `Config.xml` file has a different format than the other migration .xml files, because it doesn't contain any migration rules. It contains only a list of the operating-system components, applications, user documents that can be migrated, and user-profile policy and error-control policy. For this reason, excluding components using the `Config.xml` file is easier than modifying the migration .xml files, because you don't need to be familiar with the migration rules and syntax. However, you can't use wildcard characters in this file.
The `Config.xml` file has a different format than the other migration **.xml** files, because it doesn't contain any migration rules. It contains only a list of the operating-system components, applications, user documents that can be migrated, and user-profile policy and error-control policy. For this reason, excluding components using the `Config.xml` file is easier than modifying the migration **.xml** files, because familiarization with the migration rules and syntax isn't needed. However, wildcard characters can't be used in this file.
For more information about using the `Config.xml` file with other migration files, such as the `MigDocs.xml` and `MigApps.xml` files, see [Understanding Migration XML Files](understanding-migration-xml-files.md).
> [!NOTE]
> To exclude a component from the `Config.xml` file, set the **migrate** value to **no**. Deleting the XML tag for the component from the `Config.xml` file will not exclude the component from your migration.
>
> To exclude a component from the `Config.xml` file, set the **migrate** value to **no**. Deleting the XML tag for the component from the `Config.xml` file doesn't exclude the component from the migration.
## Migration Policies
In USMT there are new migration policies that can be configured in the `Config.xml` file. For example, you can configure additional **&lt;ErrorControl&gt;**, **&lt;ProfileControl&gt;**, and **&lt;HardLinkStoreControl&gt;** options. The following elements and parameters are for use in the `Config.xml` file only.
In USMT, there are migration policies that can be configured in the `Config.xml` file. For example, **\<ErrorControl\>**, **\<ProfileControl\>**, and **\<HardLinkStoreControl\>** options can be configured. The following elements and parameters are for use in the `Config.xml` file only.
### &lt;Policies&gt;
### \<Policies\>
The **&lt;Policies&gt;** element contains elements that describe the policies that USMT follows while creating a migration store. Valid children of the **&lt;Policies&gt;** element are **&lt;ErrorControl&gt;** and **&lt;HardLinkStoreControl&gt;**. The **&lt;Policies&gt;** element is a child of **&lt;Configuration&gt;**.
The **\<Policies\>** element contains elements that describe the policies that USMT follows while creating a migration store. Valid children of the **\<Policies\>** element are **\<ErrorControl\>** and **\<HardLinkStoreControl\>**. The **\<Policies\>** element is a child of **\<Configuration\>**.
Syntax: `<Policies>` `</Policies>`
Syntax:
### &lt;ErrorControl&gt;
```xml
<Policies> </Policies>
```
The **&lt;ErrorControl&gt;** element is an optional element you can configure in the `Config.xml` file. The configurable **&lt;ErrorControl&gt;** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, you can specify a path using the (\*) wildcard character.
### \<ErrorControl\>
The **\<ErrorControl\>** element is an optional element that can be configured in the `Config.xml` file. The configurable **\<ErrorControl\>** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, a path can be specified using the (\*) wildcard character.
- **Number of occurrences**: Once for each component
- **Parent elements**: The **&lt;Policies&gt;** element
- **Parent elements**: The **\<Policies\>** element
- **Child elements**: The **&lt;fileError&gt;** and **&lt;registryError&gt;** element
- **Child elements**: The **\<fileError\>** and **\<registryError\>** element
Syntax: `<ErrorControl>` `</ErrorControl>`
Syntax:
The following example specifies that all locked files, regardless of their location (including files in C:\\Users), should be ignored. However, the migration fails if any file in C:\\Users can't be accessed because of any other reason. In the example below, the **&lt;ErrorControl&gt;** element ignores any problems in migrating registry keys that match the supplied pattern, and it resolves them to an **Access denied** error.
```xml
<ErrorControl> </ErrorControl>
```
Additionally, the order in the **&lt;ErrorControl&gt;** section implies priority. In this example, the first **&lt;nonFatal&gt;** tag takes precedence over the second **&lt;fatal&gt;** tag. This precedence is applied, regardless of how many tags are listed.
The following example specifies that all locked files, regardless of their location (including files in C:\\Users), should be ignored. However, the migration fails if any file in C:\\Users can't be accessed because of any other reason. In the following example, the **\<ErrorControl\>** element ignores any problems in migrating registry keys that match the supplied pattern, and it resolves them to an **Access denied** error.
Additionally, the order in the **\<ErrorControl\>** section implies priority. In this example, the first **\<nonFatal\>** tag takes precedence over the second **\<fatal\>** tag. This precedence is applied, regardless of how many tags are listed.
```xml
<ErrorControl>
@ -62,94 +75,120 @@ Additionally, the order in the **&lt;ErrorControl&gt;** section implies priority
```
> [!IMPORTANT]
> The configurable **&lt;ErrorControl&gt;** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, you can specify a path using the (\*) wildcard character.
>
> The configurable **\<ErrorControl\>** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, a path using the (\*) wildcard character can be specified.
### &lt;fatal&gt;
### \<fatal\>
The **&lt;fatal&gt;** element isn't required.
The **\<fatal\>** element isn't required.
- **Number of occurrences**: Once for each component
- **Parent elements**: **&lt;fileError&gt;** and **&lt;registryError&gt;**
- **Parent elements**: **\<fileError\>** and **\<registryError\>**
- **Child elements**: None.
Syntax: `<fatal errorCode="any">` *&lt;pattern&gt;* `</fatal>`
Syntax:
```xml
<fatal errorCode="any"> <specify pattern here> </fatal>
```
|Parameter|Required|Value|
|--- |--- |--- |
|errorCode|No|"any" or "*specify system error message here*"|
You use the **&lt;fatal&gt;** element to specify that errors matching a specific pattern should cause USMT to halt the migration.
The **\<fatal\>** element can be used to specify that errors matching a specific pattern should cause USMT to halt the migration.
### &lt;fileError&gt;
### \<fileError\>
The **&lt;fileError&gt;** element isn't required.
The **\<fileError\>** element isn't required.
- **Number of occurrences**: Once for each component
- **Parent elements**: **&lt;ErrorControl&gt;**
- **Parent elements**: **\<ErrorControl\>**
- **Child elements**: **&lt;nonFatal&gt;** and **&lt;fatal&gt;**
- **Child elements**: **\<nonFatal\>** and **\<fatal\>**
Syntax: `<fileError>` `</fileError>`
Syntax:
You use the **&lt;fileError&gt;** element to represent the behavior associated with file errors.
```xml
<fileError> </fileError>
```
### &lt;nonFatal&gt;
The **\<fileError\>** element can be used to represent the behavior associated with file errors.
The **&lt;nonFatal&gt;** element isn't required.
### \<nonFatal\>
The **\<nonFatal\>** element isn't required.
- **Number of occurrences**: Once for each component
- **Parent elements**: The **&lt;fileError&gt;** and **&lt;registryError&gt;** elements.
- **Parent elements**: The **\<fileError\>** and **\<registryError\>** elements.
- **Child elements**: None.
Syntax: `<nonfatal errorCode="any">` *&lt;pattern&gt;* `</nonFatal>`
Syntax:
```xml
<nonfatal errorCode="any"> <specify pattern here> </nonFatal>
```
|Parameter|Required|Value|
|--- |--- |--- |
|**&lt;errorCode&gt;**|No|"any" or "*specify system error message here*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.|
|**\<errorCode\>**|No|"any" or "*specify system error message*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.|
You use the **&lt;nonFatal&gt;** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration.
The **\<nonFatal\>** element can be used to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration.
### &lt;registryError&gt;
### \<registryError\>
The **&lt;registryError&gt;** element isn't required.
The **\<registryError\>** element isn't required.
- **Number of occurrences**: Once for each component
- **Parent elements**: **&lt;ErrorControl&gt;**
- **Parent elements**: **\<ErrorControl\>**
- **Child elements**: **&lt;nonfatal&gt;** and **&lt;fatal&gt;**
- **Child elements**: **\<nonfatal\>** and **\<fatal\>**
Syntax: `<registryError>` `</registryError>`
Syntax:
```xml
<registryError errorcode="any"> </registryError>
```
|Parameter|Required|Value|
|--- |--- |--- |
|**&lt;errorCode&gt;**|No|"any" or "*specify system error message here*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.|
|**\<errorCode\>**|No|"any" or "*specify system error message here*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.|
You use the **&lt;registryError&gt;** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration.
The **\<registryError\>** element can be used to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration.
### &lt;HardLinkStoreControl&gt;
### \<HardLinkStoreControl\>
The **&lt;HardLinkStoreControl&gt;** element contains elements that describe how to handle files during the creation of a hard-link migration store. Its only valid child is **&lt;fileLocked&gt;**.
The **\<HardLinkStoreControl\>** element contains elements that describe how to handle files during the creation of a hard-link migration store. Its only valid child is **\<fileLocked\>**.
Syntax: `<HardLinkStoreControl>` `</HardLinkStoreControl>`
Syntax:
```xml
<HardLinkStoreControl> </HardLinkStoreControl>
```
- **Number of occurrences**: Once for each component
- **Parent elements**: **&lt;Policies&gt;**
- **Parent elements**: **\<Policies\>**
- **Child elements**: **&lt;fileLocked&gt;**
- **Child elements**: **\<fileLocked\>**
Syntax: `<HardLinkStoreControl>` `</HardLinkStoreControl>`
Syntax:
The **&lt;HardLinkStoreControl&gt;** sample code below specifies that hard links can be created to locked files only if the locked file resides somewhere under C:\\Users\\. Otherwise, a file-access error occurs when a locked file is encountered that can't be copied, even though is technically possible for the link to be created.
```xml
<HardLinkStoreControl> </HardLinkStoreControl>
```
The following **\<HardLinkStoreControl\>** sample code specifies that hard links can be created to locked files only if the locked file resides somewhere under C:\\Users\\. Otherwise, a file-access error occurs when a locked file is encountered that can't be copied, even though is technically possible for the link to be created.
> [!IMPORTANT]
> The **&lt;ErrorControl&gt;** section can be configured to conditionally ignore file access errors, based on the file's location.
>
> The **\<ErrorControl\>** section can be configured to conditionally ignore file access errors, based on the file's location.
```xml
<Policy>
@ -165,45 +204,69 @@ The **&lt;HardLinkStoreControl&gt;** sample code below specifies that hard links
</Policy>
```
### &lt;fileLocked&gt;
### \<fileLocked\>
The **&lt;fileLocked&gt;** element contains elements that describe how to handle files that are locked for editing. The rules defined by the **&lt;fileLocked&gt;** element are processed in the order in which they appear in the XML file.
The **\<fileLocked\>** element contains elements that describe how to handle files that are locked for editing. The rules defined by the **\<fileLocked\>** element are processed in the order in which they appear in the XML file.
Syntax: `<fileLocked>` `</fileLocked>`
Syntax:
### &lt;createHardLink&gt;
```xml
<fileLocked> </fileLocked>
```
The **&lt;createHardLink&gt;** 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.
### \<createHardLink\>
Syntax: `<createHardLink>` *&lt;pattern&gt;* `</createHardLink>`
The **\<createHardLink\>** 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.
### &lt;errorHardLink&gt;
Syntax:
The **&lt;errorHardLink&gt;** 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. USMT will attempt to copy files under these paths into the migration store. However, if that isn't possible, **Error\_Locked** is thrown. This error is a standard Windows application programming interface (API) error that can be captured by the **&lt;ErrorControl&gt;** section to either cause USMT to skip the file or abort the migration.
```xml
<createHardLink> <specify pattern here> </createHardLink>
```
Syntax: `<errorHardLink>` *&lt;pattern&gt;* `</errorHardLink>`
### \<errorHardLink\>
### &lt;ProfileControl&gt;
The **\<errorHardLink\>** 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. USMT attempts to copy files under these paths into the migration store. However, if that isn't possible, **Error\_Locked** is thrown. This error is a standard Windows application programming interface (API) error that can be captured by the **\<ErrorControl\>** section to either cause USMT to skip the file or abort the migration.
This element is used to contain other elements that establish rules for migrating profiles, users, and policies around local group membership during the migration. **&lt;ProfileMigration&gt;** is a child of **&lt;Configuration&gt;**.
Syntax:
Syntax: &lt;`ProfileControl>` `</ProfileControl>`
```xml
<errorHardLink> <specify pattern here> </errorHardLink>
```
### &lt;localGroups&gt;
### \<ProfileControl\>
This element is used to contain other elements that establish rules for how to migrate local groups. **&lt;localGroups&gt;** is a child of **&lt;ProfileControl&gt;**.
This element is used to contain other elements that establish rules for migrating profiles, users, and policies around local group membership during the migration. **\<ProfileMigration\>** is a child of **\<Configuration\>**.
Syntax: `<localGroups>` `</localGroups>`
Syntax:
### &lt;mappings&gt;
```xml
<ProfileControl> </ProfileControl>
```
### \<localGroups\>
This element is used to contain other elements that establish rules for how to migrate local groups. **\<localGroups\>** is a child of **\<ProfileControl\>**.
Syntax:
```xml
<localGroups> </localGroups>
```
### \<mappings\>
This element is used to contain other elements that establish mappings between groups.
Syntax: `<mappings>` `</mappings>`
Syntax:
### &lt;changeGroup&gt;
```xml
<mappings> </mappings>
```
This element describes the source and destination groups for a local group membership change during the migration. It's a child of **&lt;localGroups&gt;**. The following parameters are defined:
### \<changeGroup\>
This element describes the source and destination groups for a local group membership change during the migration. It's a child of **\<localGroups\>**. The following parameters are defined:
|Parameter|Required|Value|
|--- |--- |--- |
@ -211,25 +274,38 @@ This element describes the source and destination groups for a local group membe
|To|Yes|A local group that the users are to be moved to during the migration.|
|appliesTo|Yes|nonmigratedUsers, migratedUsers, AllUsers. This value defines which users the change group operation should apply to.|
The valid and required children of **&lt;changeGroup&gt;** are **&lt;include&gt;** and **&lt;exclude&gt;**. Although both can be children at the same time, only one is required.
The valid and required children of **\<changeGroup\>** are **\<include\>** and **\<exclude\>**. Although both can be children at the same time, only one is required.
Syntax: `<changeGroup From="Group1" To= "Group2">` `</changeGroup>`
Syntax:
### &lt;include&gt;
```xml
<changeGroup From="Group1" To= "Group2"> </changeGroup>
```
This element specifies that its required child, *&lt;pattern&gt;*, should be included in the migration.
### \<include\>
Syntax: `<include>` `</include>`
This element specifies that its required child, *\<pattern\>*, should be included in the migration.
### &lt;exclude&gt;
Syntax:
This element specifies that its required child, *&lt;pattern&gt;*, should be excluded from the migration.
```xml
<include> </include>
```
Syntax: `<exclude>` `</exclude>`
### \<exclude\>
This element specifies that its required child, *\<pattern\>*, should be excluded from the migration.
Syntax:
```xml
<exclude> </exclude>
```
## Sample Config.xml File
Refer to the following sample `Config.xml` file for more details about items you can choose to exclude from a migration.
The following sample `Config.xml` file contains detailed examples about items that can be excluded from a migration.
<br>
<br>
<details>
@ -430,4 +506,4 @@ Refer to the following sample `Config.xml` file for more details about items you
## Related articles
[USMT XML reference](usmt-xml-reference.md)
- [USMT XML reference](usmt-xml-reference.md).

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

@ -1,40 +1,44 @@
---
title: Conflicts and Precedence (Windows 10)
description: In this article, learn how User State Migration Tool (USMT) 10.0 deals with conflicts and precedence.
title: Conflicts and Precedence
description: In this article, learn how User State Migration Tool (USMT) deals with conflicts and precedence.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Conflicts and precedence
When you include, exclude, and reroute files and settings, it's important to know how User State Migration Tool (USMT) 10.0 deals with conflicts and precedence. When working with USMT, the following are the most important conflicts and precedence guidelines to keep in mind.
When including, excluding, and rerouting files and settings, it's important to know how User State Migration Tool (USMT) deals with conflicts and precedence. The following are the most important conflicts and precedence guidelines to keep in mind when working with USMT.
- **If there are conflicting rules within a component, the most specific rule is applied.** However, the **&lt;unconditionalExclude&gt;** rule is an exception because it takes precedence over all others. Directory names take precedence over file extensions. For examples, see [What happens when there are conflicting &lt;include&gt; and &lt;exclude&gt; rules?](#what-happens-when-there-are-conflicting-include-and-exclude-rules) and the first example in [&lt;include&gt; and &lt;exclude&gt; rules precedence examples](#include-and-exclude-rules-precedence-examples) later in this article.
- **If there are conflicting rules within a component, the most specific rule is applied.** However, the **\<unconditionalExclude\>** rule is an exception because it takes precedence over all others. Directory names take precedence over file extensions. For examples, see [What happens when there are conflicting \<include\> and \<exclude\> rules?](#what-happens-when-there-are-conflicting-include-and-exclude-rules) and the first example in [\<include\> and \<exclude\> rules precedence examples](#include-and-exclude-rules-precedence-examples) later in this article.
- **Only rules inside the same component can affect each other, depending on specificity.** Rules that are in different components don't affect each other, except for the **&lt;unconditionalExclude&gt;** rule.
- **Only rules inside the same component can affect each other, depending on specificity.** Rules that are in different components don't affect each other, except for the **\<unconditionalExclude\>** rule.
- **If the rules are equally specific, &lt;exclude&gt; takes precedence over &lt;include&gt;.** For example, if you use the **&lt;exclude&gt;** rule to exclude a file and use the **&lt;include&gt;** rule to include the same file, the file will be excluded.
- **If the rules are equally specific, \<exclude\> takes precedence over \<include\>.** For example, if the **\<exclude\>** rule is used to exclude a file and use the **\<include\>** rule to include the same file, the file is excluded.
- **The ordering of components does not matter.** It doesn't matter which components are listed in which .xml file, because each component is processed independently of the other components across all of the .xml files.
- **The ordering of components does not matter.** It doesn't matter which components are listed in which **.xml** file, because each component is processed independently of the other components across all of the **.xml** files.
- **The ordering of the &lt;include&gt; and &lt;exclude&gt; rules within a component does not matter.**
- **The ordering of the \<include\> and \<exclude\> rules within a component does not matter.**
- **You can use the &lt;unconditionalExclude&gt; element to globally exclude data.** This element excludes objects, regardless of any other **&lt;include&gt;** rules that are in the .xml files. For example, you can use the **&lt;unconditionalExclude&gt;** element to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`.
- **The \<unconditionalExclude\> element can be used to globally exclude data.** This element excludes objects, regardless of any other **\<include\>** rules that are in the **.xml** files. For example, the **\<unconditionalExclude\>** element can be used to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`.
## General
### What is the relationship between rules that are located within different components?
Only rules inside the same component can affect each other, depending on specificity, except for the **&lt;unconditionalExclude&gt;** rule. Rules that are in different components don't affect each other. If there's an **&lt;include&gt;** rule in one component and an identical **&lt;exclude&gt;** rule in another component, the data will be migrated because the two rules are independent of each other.
Only rules inside the same component can affect each other, depending on specificity, except for the **\<unconditionalExclude\>** rule. Rules that are in different components don't affect each other. If there's an **\<include\>** rule in one component and an identical **\<exclude\>** rule in another component, the data is migrated because the two rules are independent of each other.
If you have an **&lt;include&gt;** rule in one component and a **&lt;locationModify&gt;** rule in another component for the same file, the file will be migrated in both places. That is, it will be included based on the **&lt;include&gt;** rule, and it will be migrated based on the **&lt;locationModify&gt;** rule.
If an **\<include\>** rule is in one component and a **\<locationModify\>** rule is in another component for the same file, the file is migrated in both places. That is, the file is included based on the **\<include\>** rule, and the file is migrated based on the **\<locationModify\>** rule.
The following .xml file migrates all files from C:\\Userdocs, including .mp3 files, because the **&lt;exclude&gt;** rule is specified in a separate component.
The following **.xml** file migrates all files from C:\\Userdocs, including **.mp3** files, because the **\<exclude\>** rule is specified in a separate component.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/UserDocs">
@ -68,7 +72,7 @@ The following .xml file migrates all files from C:\\Userdocs, including .mp3 fil
### How does precedence work with the Config.xml file?
Specifying `migrate="no"` in the `Config.xml` file is the same as deleting the corresponding component from the migration .xml file. However, if you set `migrate="no"` for My Documents, but you have a rule similar to the one shown below in a migration .xml file (which includes all of the .doc files from My Documents), then only the .doc files will be migrated, and all other files will be excluded.
Specifying `migrate="no"` in the `Config.xml` file is the same as deleting the corresponding component from the migration **.xml** file. However, if `migrate="no"` is set for the **Documents** folder, but a rule similar to the following rule exists in a migration **.xml** file (which includes all of the **.doc** files from the **Documents** folder), then only the **.doc** files is migrated, and all other files are excluded:
```xml
<include>
@ -80,27 +84,27 @@ Specifying `migrate="no"` in the `Config.xml` file is the same as deleting the c
### How does USMT process each component in an .xml file with multiple components?
The ordering of components doesn't matter. Each component is processed independently of other components. For example, if you have an **&lt;include&gt;** rule in one component and a **&lt;locationModify&gt;** rule in another component for the same file, the file will be migrated in both places. That is, it will be included based on the **&lt;include&gt;** rule, and it will be migrated based on the **&lt;locationModify&gt;** rule.
The ordering of components doesn't matter. Each component is processed independently of other components. For example, if an **\<include\>** rule is in one component and a **\<locationModify\>** rule is in another component for the same file, the file is migrated in both places. That is, the file is included based on the **\<include\>** rule, and the file is migrated based on the **\<locationModify\>** rule.
### How are rules processed?
There are two broad categories of rules.
- **Rules that affect the behavior of both the ScanState and LoadState tools**. For example, the **&lt;include&gt;**, **&lt;exclude&gt;**, and **&lt;unconditionalExclude&gt;** rules are processed for each component in the .xml files. For each component, USMT creates an include list and an exclude list. Some of the rules in the component might be discarded due to specificity, but all of the remaining rules are processed. For each **&lt;include&gt;** rule, USMT iterates through the elements to see if any of the locations need to be excluded. USMT enumerates all of the objects and creates a list of objects it's going to collect for each user. Once the list is complete, each of the objects is stored or migrated to the destination computer.
- **Rules that affect the behavior of both the ScanState and LoadState tools**. For example, the **\<include\>**, **\<exclude\>**, and **\<unconditionalExclude\>** rules are processed for each component in the **.xml** files. For each component, USMT creates an include list and an exclude list. Some of the rules in the component might be discarded due to specificity, but all of the remaining rules are processed. For each **\<include\>** rule, USMT iterates through the elements to see if any of the locations need to be excluded. USMT enumerates all of the objects and creates a list of objects it's going to collect for each user. Once the list is complete, each of the objects is stored or migrated to the destination computer.
- **Rules that affect the behavior of only the LoadState tool**. For example, the **&lt;locationModify&gt;**, **&lt;contentModify&gt;**, and **&lt;destinationCleanup&gt;** rules don't affect ScanState. They're processed only with LoadState. First, the LoadState tool determines the content and location of each component based on the **&lt;locationModify&gt;** and **&lt;contentModify&gt;** rules. Then, LoadState processes all of the **&lt;destinationCleanup&gt;** rules and deletes data from the destination computer. Lastly, LoadState applies the components to the computer.
- **Rules that affect the behavior of only the LoadState tool**. For example, the **\<locationModify\>**, **\<contentModify\>**, and **\<destinationCleanup\>** rules don't affect ScanState. They're processed only with LoadState. First, the **LoadState** tool determines the content and location of each component based on the **\<locationModify\>** and **\<contentModify\>** rules. Then, **LoadState** processes all of the **\<destinationCleanup\>** rules and deletes data from the destination computer. Lastly, **LoadState** applies the components to the computer.
### How does USMT combine all of the .xml files that I specify on the command line?
USMT doesn't distinguish the .xml files based on their name or content. It processes each component within the files separately. USMT supports multiple .xml files only to make it easier to maintain and organize the components within them. Because USMT uses a urlid to distinguish each component from the others, be sure that each .xml file that you specify on the command line has a unique migration urlid.
USMT doesn't distinguish the **.xml** files based on their name or content. It processes each component within the files separately. USMT supports multiple **.xml** files only to make it easier to maintain and organize the components within them. Because USMT uses a urlid to distinguish each component from the others, be sure that each **.xml** file that is specified on the command line has a unique migration urlid.
## The &lt;include&gt; and &lt;exclude&gt; rules
## The \<include\> and \<exclude\> rules
### What happens when there are conflicting &lt;include&gt; and &lt;exclude&gt; rules?
### What happens when there are conflicting \<include\> and \<exclude\> rules?
If there are conflicting rules within a component, the most specific rule is applied, except with the **&lt;unconditionalExclude&gt;** rule, which takes precedence over all other rules. If the rules are equally specific, then the data won't be migrated. For example if you exclude a file, and include the same file, the file won't be migrated. If there are conflicting rules within different components, the rules don't affect each other because each component is processed independently.
If there are conflicting rules within a component, the most specific rule is applied, except with the **\<unconditionalExclude\>** rule, which takes precedence over all other rules. If the rules are equally specific, then the data isn't migrated. For example if the same file is both excluded and included, the file isn't migrated. If there are conflicting rules within different components, the rules don't affect each other because each component is processed independently.
In the following example, mp3 files won't be excluded from the migration. The mp3 files won't be excluded because directory names take precedence over the file extensions.
In the following example, mp3 files aren't excluded from the migration. The mp3 files aren't excluded because directory names take precedence over the file extensions.
```xml
<include>
@ -115,9 +119,9 @@ In the following example, mp3 files won't be excluded from the migration. The mp
</exclude>
```
### &lt;include&gt; and &lt;exclude&gt; rules precedence examples
### \<include\> and \<exclude\> rules precedence examples
These examples explain how USMT deals with **&lt;include&gt;** and **&lt;exclude&gt;** rules. When the rules are in different components, the resulting behavior will be the same regardless of whether the components are in the same or in different migration .xml files.
These examples explain how USMT deals with **\<include\>** and **\<exclude\>** rules. When the rules are in different components, the resulting behavior is the same regardless of whether the components are in the same or in different migration **.xml** files.
- [Including and excluding files](#including-and-excluding-files)
@ -125,42 +129,42 @@ These examples explain how USMT deals with **&lt;include&gt;** and **&lt;exclude
### Including and excluding files
| If you have the following code in the same component | Resulting behavior | Explanation |
| If the following code exists in the same component | Resulting behavior | Explanation |
|-----|-----|-----|
| <ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:* [.txt]&lt;/pattern&gt;</li></ul> | Migrates all files and subfolders in Dir1 (including all .txt files in C:). | The **&lt;exclude&gt;** rule doesn't affect the migration because the **&lt;include&gt;** rule is more specific. |
| <ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</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: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\ * [.txt]&lt;/pattern&gt;</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: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li></ul> | Nothing will be migrated. | The rules are equally specific, so the **&lt;exclude&gt;** rule takes precedence over the **&lt;include&gt;** 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\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. |
| <ul><li>Include rule: \<pattern type="File"\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type="File"\>C:* [.txt]\</pattern\></li></ul> | Migrates all files and subfolders in Dir1 (including all **.txt** files in C:). | The **\<exclude\>** rule doesn't affect the migration because the **\<include\>** rule is more specific. |
| <ul><li>Include rule: \<pattern type="File"\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type="File"\>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="File"\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type="File"\>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="File"\>C:\Dir1\Dir2* [.txt]\</pattern\></li><li>Exclude rule: \<pattern type="File"\>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\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 you have the following code in different components | Resulting behavior | Explanation |
| If the following code exists in different components | Resulting behavior | Explanation |
|-----|----|----|
| Component 1:<ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li></ul> <br/>Component 2:<ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</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 **&lt;unconditionalExclude&gt;** 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 **&lt;include&gt;** rule, so the **&lt;exclude&gt;** rule isn't processed. |
| Component 1:<ul><li>Include rule: \<pattern type="File"\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type="File"\>C:\Dir1\Dir2* [.txt]\</pattern\></li></ul><br>Component 2:<ul><li>Include rule: \<pattern type="File"\>C:\Dir1\Dir2* [.txt]\</pattern\></li><li>Exclude rule: \<pattern type="File"\>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 you have the following code in the same component | Resulting behavior | Explanation |
| 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 **&lt;include&gt;** rule is more specific than the **&lt;exclude&gt;** 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 **&lt;exclude&gt;** rule takes precedence over the &lt;include&gt; 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 you have the following code in different components | Resulting behavior | Explanation |
| 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 **&lt;unconditionalExclude&gt;** rule. Therefore, 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
### What is the default behavior when there are file collisions?
If there isn't a **&lt;merge&gt;** rule, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally: for example, OriginalFileName(1).OriginalExtension, OriginalFileName(2).OriginalExtension, and so on.
If there isn't a **\<merge\>** rule, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally: for example, OriginalFileName(1).OriginalExtension, OriginalFileName(2).OriginalExtension, and so on.
### How does the &lt;merge&gt; rule work when there are file collisions?
### How does the \<merge\> rule work when there are file collisions?
When a collision is detected, USMT will select the most specific **&lt;merge&gt;** rule and apply it to resolve the conflict. For example, if you have a **&lt;merge&gt;** rule for **C:\\\* \[\*\]** set to **sourcePriority()** and another **&lt;merge&gt;** rule for **C:\\subfolder\\\* \[\*\]** set to **destinationPriority()** , then USMT uses the **destinationPriority()** rule because it's the most specific.
When a collision is detected, USMT selects the most specific **\<merge\>** rule and apply it to resolve the conflict. For example, if a **\<merge\>** rule exists for **C:\\\* \[\*\]** set to **sourcePriority()** and another **\<merge\>** rule for **C:\\subfolder\\\* \[\*\]** set to **destinationPriority()** , then USMT uses the **destinationPriority()** rule because it's the most specific.
### Example scenario
@ -178,7 +182,7 @@ The destination computer contains the following files:
- `C:\Data\SampleB.txt`
You have a custom .xml file that contains the following code:
A custom **.xml** file contains the following code:
```xml
<include>
@ -188,7 +192,7 @@ You have a custom .xml file that contains the following code:
</include>
```
For this example, the following information describes the resulting behavior if you add the code to your custom .xml file.
For this example, the following information describes the resulting behavior if the code is added to the custom **.xml** file.
#### Example 1
@ -200,7 +204,7 @@ For this example, the following information describes the resulting behavior if
</merge>
```
**Result**: During ScanState, all the files will be added to the store. During LoadState, only `C:\Data\SampleA.txt` will be restored.
**Result**: During ScanState, all the files are added to the store. During LoadState, only `C:\Data\SampleA.txt` is restored.
#### Example 2
@ -212,8 +216,8 @@ For this example, the following information describes the resulting behavior if
</merge>
```
**Result**: During ScanState, all the files will be added to the store.
During LoadState, all the files will be restored, overwriting the existing files on the destination computer.
**Result**: During ScanState, all the files are added to the store.
During LoadState, all the files are restored, overwriting the existing files on the destination computer.
#### Example 3
@ -225,12 +229,12 @@ During LoadState, all the files will be restored, overwriting the existing files
</merge>
```
**Result**: During ScanState, all the files will be added to the store. During LoadState, the following actions will occur:
**Result**: During ScanState, all the files are added to the store. During LoadState, the following actions occur:
- `C:\Data\SampleA.txt` will be restored.
- `C:\Data\SampleB.txt` will be restored, overwriting the existing file on the destination computer.
- `C:\Data\Folder\SampleB.txt` won't be restored.
- `C:\Data\SampleA.txt` is restored.
- `C:\Data\SampleB.txt` is restored, overwriting the existing file on the destination computer.
- `C:\Data\Folder\SampleB.txt` aren't restored.
## Related articles
[USMT XML reference](usmt-xml-reference.md)
[USMT XML reference](usmt-xml-reference.md).

31
windows/deployment/usmt/usmt-custom-xml-examples.md
View File

@ -1,20 +1,24 @@
---
title: Custom XML Examples (Windows 10)
description: Use custom XML examples to learn how to migrate an unsupported application, migrate files and registry keys, and migrate the My Videos folder.
title: Custom XML Examples
description: Use custom XML examples to learn how to migrate an unsupported application, migrate files and registry keys, and migrate the Videos folder.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.topic: article
ms.technology: itpro-deploy
ms.date: 11/01/2022
ms.date: 01/09/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Custom XML Examples
## Example 1: Migrating an unsupported application
The following template is a template for the sections that you need to migrate your application. The template isn't functional on its own, but you can use it to write your own .xml file.
The following template is a template for the sections that are needed to migrate applications. The template isn't functional on its own, but it can be used to write custom **.xml** file.
**Template**
<br>
@ -89,19 +93,19 @@ The following template is a template for the sections that you need to migrate y
## Example 2: Migrating the My Videos folder
The following sample is a custom .xml file named `CustomFile.xml` that migrates **My Videos** for all users, if the folder exists on the source computer.
The following sample is a custom **.xml** file named `CustomFile.xml` that migrates the **Videos** folder for all users, if the folder exists on the source computer.
- **Sample condition**: Verifies that **My Videos** exists on the source computer:
- **Sample condition**: Verifies that the **Videos** folder exists on the source computer:
`<condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_MYVIDEO%")</condition>`
- **Sample filter**: Filters out the shortcuts in **My Videos** that don't resolve on the destination computer:
- **Sample filter**: Filters out the shortcuts in the **Videos** folder that don't resolve on the destination computer:
`<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>`
This filter has no effect on files that aren't shortcuts. For example, if there's a shortcut in **My Videos** on the source computer that points to `C:\Folder1`, that shortcut will be migrated only if `C:\Folder1` exists on the destination computer. However, all other files, such as .mp3 files, migrate without any filtering.
This filter has no effect on files that aren't shortcuts. For example, if there's a shortcut in the **Videos** folder on the source computer that points to `C:\Folder1`, that shortcut is migrated only if `C:\Folder1` exists on the destination computer. However, all other files, such as **.mp3** files, migrate without any filtering.
- **Sample pattern**: Migrates **My Videos** for all users:
- **Sample pattern**: Migrates the **Videos** folder for all users:
`<pattern type="File">%CSIDL_MYVIDEO%* [*]</pattern>`
@ -137,7 +141,7 @@ The following sample is a custom .xml file named `CustomFile.xml` that migrates
## Example 3: Migrating files and registry keys
The sample patterns describe the behavior in the following example .xml file.
The sample patterns describe the behavior in the following example **.xml** file.
- **Sample pattern**: Migrates all instances of the file `Usmttestfile.txt` from all subdirectories under `%ProgramFiles%\USMTTestFolder`:
@ -195,7 +199,7 @@ The sample patterns describe the behavior in the following example .xml file.
## Example 4: Migrating specific folders from various locations
The behavior for this custom .xml file is described within the `<displayName>` tags in the code.
The behavior for this custom **.xml** file is described within the `<displayName>` tags in the code.
**XML file**
<br>
@ -275,6 +279,5 @@ The behavior for this custom .xml file is described within the `<displayName>` t
## Related articles
[USMT XML reference](usmt-xml-reference.md)
[Customize USMT XML files](usmt-customize-xml-files.md)
- [USMT XML reference](usmt-xml-reference.md).
- [Customize USMT XML files](usmt-customize-xml-files.md).

62
windows/deployment/usmt/usmt-customize-xml-files.md
View File

@ -1,77 +1,84 @@
---
title: Customize USMT XML Files (Windows 10)
title: Customize USMT XML Files
description: Learn how to customize USMT XML files. Also, learn about the migration XML files that are included with USMT.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Customize USMT XML files
## Overview
If you want the ScanState and LoadState tools to use any of the migration .xml files, specify these files at the command line using the `/i` option. Because the ScanState and LoadState tools need the .xml files to control the migration, specify the same set of .xml files for both the `ScanState.exe` and `LoadState.exe` commands. However, you don't have to specify the `Config.xml` file with the `/config` option, unless you want to exclude some of the files and settings that you migrated to the store. For example, you might want to migrate the My Documents folder to the store but not to the destination computer. To achieve this scenario, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. Then the `LoadState.exe` command will migrate only the files and settings that you want to migrate.
To use any of the migration **.xml** files with the **ScanState** and **LoadState** tools, specify these files at the command line using the `/i` option. Because the **ScanState** and **LoadState** tools need the **.xml** files to control the migration, specify the same set of **.xml** files for both the `ScanState.exe` and `LoadState.exe` commands. However, the `Config.xml` file with the `/config` option doesn't need to be specified, unless some of the migrated files and settings from the store need to be excluded. For example, to migrate the **Documents** folder to the store but not to the destination computer. To achieve this scenario, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. The `LoadState.exe` command then only migrates the desired files and settings.
If you leave out an .xml file from the `LoadState.exe` command, all of the data in the store that was migrated with the missing .xml files will be migrated. However, the migration rules that were specified with the `ScanState.exe` command won't apply. For example, if you leave out an .xml file, and it contains a rerouting rule such as:
If an **.xml** file is left out from the `LoadState.exe` command, all of the data in the store that was migrated with the missing **.xml** files are migrated. However, the migration rules that were specified with the `ScanState.exe` command don't apply. For example, if an **.xml** file is left out, and it contains a rerouting rule such as:
`MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")`
USMT won't reroute the files, and they'll be migrated to `C:\data`.
USMT doesn't reroute the files, and they're migrated to `C:\data`.
To modify the migration, do one or more of the following.
- **Modify the migration .xml files.** If you want to exclude a portion of a component, for example, you want to migrate C:\\ but exclude all of the .mp3 files, or if you want to move data to a new location on the destination computer, modify the .xml files. To modify these files, you must be familiar with the migration rules and syntax. If you want ScanState and LoadState to use these files, specify them at the command line when each command is entered.
- **Modify the migration .xml files.** To exclude a portion of a component, modify the **.xml** files. For example, to migrate C:\\ but exclude all of the **.mp3** files, or to move data to a new location on the destination computer. To modify these files, familiarity with the migration rules and syntax is a must. For **ScanState** and **LoadState** to use these files, specify them at the command line when each command is entered.
- **Create a custom .xml file.** You can also create a custom .xml file to migrate settings for another application, or to change the migration behavior to suit your needs. For ScanState and LoadState to use this file, specify them on both command lines.
- **Create a custom .xml file.** A custom **.xml** file can also be created to migrate settings for another application, or to change the migration behavior to suit the organization's needs. For **ScanState** and **LoadState** to use this file, specify them on both command lines.
- **Create and modify a Config.xml file.** Create and modify a `Config.xml` file if you want to exclude an entire component from the migration. For example, you can use a `Config.xml` file to exclude the entire My Documents folder, or exclude the settings for an application. Excluding components using a `Config.xml` file is easier than modifying the migration .xml files because you don't need to be familiar with the migration rules and syntax. In addition, using a `Config.xml` file is the only way to exclude the operating system settings from being migrated.
- **Create and modify a Config.xml file.** Create and modify a `Config.xml` file to exclude an entire component from the migration. For example, a `Config.xml` file can be used to exclude the entire **Documents** folder, or exclude the settings for an application. Excluding components using a `Config.xml` file is easier than modifying the migration **.xml** files because familiarity with the migration rules and syntax isn't needed. In addition, using a `Config.xml` file is the only way to exclude the operating system settings from being migrated.
For more information about excluding data, see the [Exclude Files and Settings](usmt-exclude-files-and-settings.md) article.
## Migration .xml files
This section describes the migration .xml files that are included with USMT. Each file contains migration rules that control which components are migrated and where they're migrated to on the destination computer.
This section describes the migration **.xml** files that are included with USMT. Each file contains migration rules that control which components are migrated and where they're migrated to on the destination computer.
> [!NOTE]
> You can use the asterisk (\*) wildcard character in each of these files. However, you cannot use a question mark (?) as a wildcard character.
>
> The asterisk (\*) wildcard character can be used in each of these files. However, a question mark (?) can't be used as a wildcard character.
- **The MigApp.xml file.** Specify this file with both the `ScanState.exe` and `LoadState.exe` commands to migrate application settings.
- **The MigDocs.xml file.** Specify this file with both the ScanState and LoadState tools to migrate all user folders and files that are found by the **MigXmlHelper.GenerateDocPatterns** helper function. This helper function finds user data that resides on the root of any drive and in the Users directory. However, it doesn't find and migrate any application data, program files, or any files in the Windows directory. You can modify the `MigDocs.xml` file.
- **The MigDocs.xml file.** Specify this file with both the **ScanState** and **LoadState** tools to migrate all user folders and files that are found by the **MigXmlHelper.GenerateDocPatterns** helper function. This helper function finds user data that resides on the root of any drive and in the Users directory. However, it doesn't find and migrate any application data, program files, or any files in the Windows directory. The `MigDocs.xml` file can be modified.
- **The MigUser.xml file.** Specify this file with both the `ScanState.exe` and `LoadState.exe` commands to migrate user folders, files, and file types. You can modify the `MigUser.xml` file. This file doesn't contain rules that migrate specific user accounts. The only way to specify which user accounts to migrate is on the command line using the ScanState and the LoadState user options.
- **The MigUser.xml file.** Specify this file with both the `ScanState.exe` and `LoadState.exe` commands to migrate user folders, files, and file types. The `MigUser.xml` file can be modified. This file doesn't contain rules that migrate specific user accounts. The only way to specify which user accounts to migrate is on the command line by using the [ScanState User options](usmt-scanstate-syntax.md#user-options) and the [LoadState User options](usmt-loadstate-syntax.md#user-options).
> [!NOTE]
>
> Don't use the `MigUser.xml` and `MigDocs.xml` files together. For more information, see the [Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md) and [USMT best practices](usmt-best-practices.md) articles.
## Custom .xml files
You can create custom .xml files to customize the migration for your unique needs. For example, you may want to create a custom file to migrate a line-of-business application or to modify the default migration behavior. If you want `ScanState.exe` and `LoadState.exe` to use this file, specify it with both commands. For more information, see the [Custom XML examples](usmt-custom-xml-examples.md) article.
Custom **.xml** files can be created to customize the migration for the organization's unique needs. For example, a custom **.xml** file can be created to migrate a line-of-business application or to modify the default migration behavior. For `ScanState.exe` and `LoadState.exe` to use this file, specify it with both commands. For more information, see the [Custom XML examples](usmt-custom-xml-examples.md) article.
## The Config.xml file
The `Config.xml` file is an optional file that you create using the `/genconfig` option with the `ScanState.exe` command. You should create and modify this file if you want to exclude certain components from the migration. In addition, you must create and modify this file if you want to exclude any of the operating system settings from being migrated. The `Config.xml` file format is different from the migration .xml files because it doesn't contain any migration rules. It contains only a list of the operating system components, applications, and the user documents that can be migrated. For an example, see the [Config.xml File](usmt-configxml-file.md) article. For this reason, excluding components using this file is easier than modifying the migration .xml files because you don't need to be familiar with the migration rules and syntax. However, you can't use wildcard characters in a `Config.xml` file.
The `Config.xml` file is an optional file that is created using the `/genconfig` option with the `ScanState.exe` command. This file should be created and modified to exclude certain components from the migration. In addition, this file must be created and modified to exclude any of the operating system settings from being migrated. The `Config.xml` file format is different from the migration **.xml** files because it doesn't contain any migration rules. It contains only a list of the operating system components, applications, and the user documents that can be migrated. For an example, see the [Config.xml File](usmt-configxml-file.md) article. For this reason, excluding components using the `Config.xml` file is easier than modifying the migration **.xml** files. With the `Config.xml`, familiarity with the migration rules and syntax isn't. However, wildcard characters can't be used in a `Config.xml` file.
If you want to include all of the default components, you don't need to create the `Config.xml` file. Alternatively, if you're satisfied with the default migration behavior defined in the `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml` files, and you want to exclude only some components, you can create and modify a `Config.xml` file and leave the other .xml files in their original state.
To include all of the default components, a `Config.xml` file doesn't need to be created. Alternatively, if the default migration behavior defined in the `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml` files are satisfactory, and only some components need to be excluded, a `Config.xml` file can be created. The other **.xml** files can be left in their original state.
When you run the `ScanState.exe` command with the `/genconfig` option, `ScanState.exe` reads the other .xml files that you specify using the `/i` option to create a custom list of components that can be migrated from the computer. This file will contain only operating system components, applications, and the user document sections that are in both of the .xml files and that are installed on the computer when you run the `ScanState.exe` command with the `/genconfig` option. Therefore, you should create this file on a source computer that contains all of the components, applications, and settings that will be present on the destination computers. Creating the file on the source computer will ensure that this file contains every component that can be migrated. The components are organized into sections: &lt;Applications&gt;, &lt;WindowsComponents&gt;, and &lt;Documents&gt;. To choose not to migrate a component, change its entry to `migrate="no"`.
When the `ScanState.exe` command is run with the `/genconfig` option, `ScanState.exe` reads the other **.xml** files that are specified using the `/i` option to create a custom list of components that can be migrated from the computer. This file contains only operating system components, applications, and the user document sections that are in both of the **.xml** files and that are installed on the computer when the `ScanState.exe` command is run with the `/genconfig` option. Therefore, this file should be created on a source computer that contains all of the components, applications, and settings that are present on the destination computers. Creating the file on the source computer ensures that this file contains every component that can be migrated. The components are organized into sections: \<Applications\>, \<WindowsComponents\>, and \<Documents\>. To choose not to migrate a component, change its entry to `migrate="no"`.
After you create this file, you need to specify it only with the `ScanState.exe` command using the `/Config` option for it to affect the migration. However, if you want to exclude additional data that you migrated to the store, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. For example, if you collected the My Documents folder in the store, but you decide that you don't want to migrate the My Documents folder to a destination computer, you can modify the `Config.xml` file to indicate `migrate="no"` before you run the `LoadState.exe` command, and the file won't be migrated. For more information about the precedence that takes place when excluding data, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article.
After this file is created, it only needs to be specified with the `ScanState.exe` command using the `/Config` option for it to affect the migration. However, if additional data that was migrated to the store needs to be excluded, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. For example, if the **Documents** folder is collected in the store, but the **Documents** folder doesn't need to be migrated to a destination computer, the `Config.xml` file can be modified to indicate `migrate="no"` before the `LoadState.exe` command runs, and the file aren't be migrated. For more information about the precedence that takes place when excluding data, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article.
In addition, note the following functionality with the `Config.xml` file:
- If a parent component is removed from the migration in the `Config.xml` file by specifying `migrate="no"`, all of its child components will automatically be removed from the migration, even if the child component is set to `migrate="yes"`.
- If a parent component is removed from the migration in the `Config.xml` file by specifying `migrate="no"`, all of its child components are automatically removed from the migration, even if the child component is set to `migrate="yes"`.
- If you mistakenly have two lines of code for the same component where one line specifies `migrate="no"` and the other line specifies `migrate="yes"`, the component will be migrated.
- If mistakenly two lines of code exist for the same component where one line specifies `migrate="no"` and the other line specifies `migrate="yes"`, the component is migrated.
- In USMT, there are several migration policies that can be configured in the `Config.xml` file. For example, you can configure additional **&lt;ErrorControl&gt;**, **&lt;ProfileControl&gt;**, and **&lt;HardLinkStoreControl&gt;** options. For more information, see the [Config.xml File](usmt-configxml-file.md) article.
- In USMT, there are several migration policies that can be configured in the `Config.xml` file. For example, additional **\<ErrorControl\>**, **\<ProfileControl\>**, and **\<HardLinkStoreControl\>** options can be configured. For more information, see the [Config.xml File](usmt-configxml-file.md) article.
> [!NOTE]
> To exclude a component from the `Config.xml` file, set the **migrate** value to **"no"**. Deleting the XML tag for the component from the `Config.xml` file will not exclude the component from your migration.
>
> To exclude a component from the `Config.xml` file, set the **migrate** value to **"no"**. Deleting the XML tag for the component from the `Config.xml` file doesn't exclude the component from the migration.
### Examples
@ -79,7 +86,7 @@ In addition, note the following functionality with the `Config.xml` file:
`ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:5`
- The following command creates an encrypted store using the `Config.xml` file and the default migration .xml files:
- The following command creates an encrypted store using the `Config.xml` file and the default migration **.xml** files:
`ScanState.exe \\server\share\migration\mystore /i:MigApp.xml /i:MigDocs.xml /o /config:Config.xml /v:5 /encrypt /key:"mykey"`
@ -89,14 +96,11 @@ In addition, note the following functionality with the `Config.xml` file:
## Additional information
- For more information about how to change the files and settings that are migrated, see the [User State Migration Tool (USMT) how-to topics](usmt-how-to.md).
- For more information about each .xml element, see the [XML elements library](usmt-xml-elements-library.md) article.
- For more information about how to change the files and settings that are migrated, see the [User State Migration Tool (USMT) how-to articles](usmt-how-to.md).
- For more information about each **.xml** element, see the [XML elements library](usmt-xml-elements-library.md) article.
- For answers to common questions, see ".xml files" in the [Frequently asked questions](usmt-faq.yml) article.
## Related articles
[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md)
[USMT resources](usmt-resources.md)
- [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md).
- [USMT resources](usmt-resources.md).

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

@ -1,28 +1,37 @@
---
title: Determine What to Migrate (Windows 10)
description: Determine migration settings for standard or customized for the User State Migration Tool (USMT) 10.0.
title: Determine What to Migrate
description: Determine migration settings for standard or customized for the User State Migration Tool (USMT).
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Determine what to migrate
By default, User State Migration Tool (USMT) 10.0 migrates the items listed in [What does USMT migrate?](usmt-what-does-usmt-migrate.md), depending on the migration .xml files you specify. These default settings are often enough for a basic migration.
By default, User State Migration Tool (USMT) migrates the items listed in [What does USMT migrate?](usmt-what-does-usmt-migrate.md), depending on the migration **.xml** files that are specified. These default settings are often enough for a basic migration.
However, when considering what settings to migrate, you should also consider what settings you would like the user to be able to configure, if any, and what settings you would like to standardize. Many organizations use their migration as an opportunity to create and begin enforcing a better-managed environment. Some of the settings that users can configure on unmanaged computers prior to the migration can be locked on the new, managed computers. For example, standard wallpaper, Internet Explorer security settings, and desktop configuration are some of the items you can choose to standardize.
However, when considering what settings to migrate, also consider:
To reduce complexity and increase standardization, your organization should consider creating a *standard operating environment (SOE)*. An SOE is a combination of hardware and software that you distribute to all users. Creating an SOE means selecting:
- What settings the user can configure, if any.
- What settings should be standardized.
- A baseline for all computers, including standard hardware drivers
- Core operating system features
- Core productivity applications, especially if they are under volume licensing
Many organizations use their migration as an opportunity to create and begin enforcing a better-managed environment. Some of the settings that users can configure on unmanaged computers prior to the migration can be locked on the new, managed computers. For example, standard wallpaper and desktop configuration are some of the items that can be standardized.
To reduce complexity and increase standardization, the organization should consider creating a *standard operating environment (SOE)*. An SOE is a combination of hardware and software that is distributed to all users. Creating an SOE means selecting:
- A baseline for all computers, including standard hardware drivers.
- Core operating system features.
- Core productivity applications, especially if they are under volume licensing.
- Core utilities.
- A standard set of security features, as outlined in the organization's corporate policy
- A standard set of security features, as outlined in the organization's corporate policy.
Using an SOE can vastly simplify the migration and reduce overall deployment challenges.
@ -31,10 +40,10 @@ Using an SOE can vastly simplify the migration and reduce overall deployment cha
| Link | Description |
|--- |--- |
|[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 you want to migrate and prepare a list of application settings to 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)|Determine and locate the standard, company-specified, and non-standard locations of the file types, files, folders, and settings that you want to migrate.|
|[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
[What does USMT migrate?](usmt-what-does-usmt-migrate.md)
- [What does USMT migrate?](usmt-what-does-usmt-migrate.md).

71
windows/deployment/usmt/usmt-estimate-migration-store-size.md
View File

@ -1,77 +1,87 @@
---
title: Estimate Migration Store Size (Windows 10)
description: Estimate the disk space requirement for a migration so that you can use User State Migration Tool (USMT).
title: Estimate Migration Store Size
description: Estimate the disk space requirement for a migration so that the User State Migration Tool (USMT) can be used.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Estimate migration store size
The disk space requirements for a migration are dependent on the size of the migration store and the type of migration. You can estimate the amount of disk space needed for computers in your organization based on information about your organization's infrastructure. You can also calculate the disk space requirements using the ScanState tool.
The disk space requirements for a migration are dependent on the size of the migration store and the type of migration. The amount of disk space needed for computers in the organization can be estimated based on information about the organization's infrastructure. Disk space requirements can also be calculated using the **ScanState** tool.
## Hard disk space requirements
- **Store**: For non-hard-link migrations, you should ensure that there's enough available disk space at the location where you'll save your store to contain the data being migrated. You can save your store to another partition, an external storage device such as a USB flash drive or a server. For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md).
- **Store**: For non-hard-link migrations, ensure that there's enough available disk space at the location where the store is saved. The store contains the data being migrated. The store can be saved to another partition, an external storage device such as a USB flash drive, or a server. For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md).
- **Source Computer**: The source computer needs enough available space for the following items:
- **E250 megabytes (MB) minimum of hard disk space**: Space is needed to support the User State Migration Tool (USMT) 10.0 operations, for example, growth in the page file. If every volume involved in the migration is formatted as NTFS, 250 MB should be enough space to ensure success for almost every hard-link migration, regardless of the size of the migration. The USMT tools won't create the migration store if 250 MB of disk space isn't available.
- **E250 megabytes (MB) minimum of hard disk space**: Space is needed to support the User State Migration Tool (USMT) operations, for example, growth in the page file. If every volume involved in the migration is formatted as NTFS, 250 MB should be enough space to ensure success for almost every hard-link migration, regardless of the size of the migration. The USMT tool that captures data (ScanState) doesn't create the migration store if 250 MB of disk space isn't available.
- **Temporary space for USMT to run**: Extra disk space for the USMT tools to operate is required. This disk space requirement doesn't include the minimum 250 MB needed to create the migration store. The amount of temporary space required can be calculated using the ScanState tool.
- **Temporary space for USMT to run**: Extra disk space is required for the USMT tools to operate. This disk space requirement doesn't include the minimum 250 MB needed to create the migration store. The amount of temporary space required can be calculated using the **ScanState** tool.
- **Hard-link migration store**: It isn't necessary to estimate the size of a hard-link migration store. The only case where the hard-link store can be large is when non-NTFS file volumes exist on the system and those volumes contain data being migrated.
- **Destination computer**: The destination computer needs enough available space for the following components:
- **Operating system**
- **Operating system**.
- **Applications**
- **Applications**.
- **Data being migrated**: Data being migrated includes files and registry information.
- **Temporary space for USMT to run**: Extra disk space for the USMT tools to operate is required. The amount of temporary space required can be calculated using the ScanState tool.
- **Temporary space for USMT to run**: Extra disk space is required for the USMT tools to operate. The amount of temporary space required can be calculated using the **ScanState** tool.
## Calculate disk space requirements using the ScanState tool
## Calculate disk space requirements using the **ScanState** tool
You can use the ScanState tool to calculate the disk space requirements for a particular compressed or uncompressed migration. It isn't necessary to estimate the migration store size for a hard-link migration since this method doesn't create a separate migration store. The ScanState tool provides disk space requirements for the state of the computer at the time the tool is run. The state of the computer may change during day-to-day use so it's recommended that you use the calculations as an estimate when planning your migration.
The **ScanState** tool can be used to calculate the disk space requirements for a particular compressed or uncompressed migration. It isn't necessary to estimate the migration store size for a hard-link migration since this method doesn't create a separate migration store. The **ScanState** tool provides disk space requirements for the state of the computer at the time the tool is run. The state of the computer might change during day-to-day use. For this reason, use the calculations as an estimate when planning the migration.
To run the ScanState tool on the source computer with USMT installed:
To run the **ScanState** tool on the source computer with USMT installed:
1. Open a command prompt with administrator privileges.
2. Navigate to the USMT tools. For example, enter:
1. Navigate to the USMT tools. For example, enter:
```cmd
cd /d "C:\Program Files (x86)\Windows Kits\8.0\Assessment and Deployment Kit\User State Migration Tool\<architecture>"
cd /d "C:\Program Files (x86)\Windows Kits\10.0\Assessment and Deployment Kit\User State Migration Tool\<architecture>"
```
where *&lt;architecture&gt;* is x86 or amd64.
where *\<architecture\>* is x86 or amd64.
3. Run the **ScanState** tool to generate an XML report of the space requirements. At the command prompt, enter:
1. Run the **ScanState** tool to generate an XML report of the space requirements. At the command prompt, enter:
```cmd
ScanState.exe <StorePath> /p:<path to a file>
```
Where *&lt;StorePath&gt;* is a path to a directory where the migration store will be saved and *&lt;path to a file&gt;* is the path and filename where the XML report for space requirements will be saved. For example:
Where:
- *\<StorePath\>* is a path to a directory where the migration store is saved.
- *\<path to a file\>* is the path and filename where the XML report for space requirements is saved.
For example:
```cmd
ScanState.exe c:\store /p:c:\spaceRequirements.xml
```
Although a migration store isn't created by running this command, the *&lt;StorePath&gt;* is still a required parameter.
Although a migration store isn't created by running this command, the *\<StorePath\>* is still a required parameter.
The ScanState tool also allows you to estimate disk space requirements based on a customized migration. For example, you might not want to migrate the My Documents folder to the destination computer. You can specify this condition in a configuration file when you run the ScanState tool. For more information, see [Customize USMT XML files](usmt-customize-xml-files.md).
The **ScanState** tool also allows estimation of disk space requirements based on a customized migration. For example, the **Documents** folder might need to be migrated to the destination computer. This condition can be specified in a configuration file when the **ScanState** tool is run. For more information, see [Customize USMT XML files](usmt-customize-xml-files.md).
> [!NOTE]
> To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option is still available in USMT without having to specify the path to a file. See [Monitoring Options](usmt-scanstate-syntax.md#monitoring-options) for more information.
>
> To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option is still available in USMT without having to specify the path to a file. For more information, see [Monitoring Options](usmt-scanstate-syntax.md#monitoring-options).
The space requirements report provides two elements, &lt;**storeSize**&gt; and &lt;**temporarySpace**&gt;. The &lt;**temporarySpace**&gt; value shows the disk space, in bytes, that USMT uses to operate during the migration but it doesn't include the minimum 250 MB needed to support USMT. The &lt;**storeSize**&gt; value shows the disk space, in bytes, required to host the migration store contents on both the source and destination computers. The following example shows a report generated using `/p:`*&lt;path to a file&gt;*.
The space requirements report provides two elements, \<**storeSize**\> and \<**temporarySpace**\>. The \<**temporarySpace**\> value shows the disk space, in bytes, that USMT uses to operate during the migration but it doesn't include the minimum 250 MB needed to support USMT. The \<**storeSize**\> value shows the disk space, in bytes, required to host the migration store contents on both the source and destination computers. The following example shows a report generated using `/p:`*\<path to a file\>*.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -85,25 +95,26 @@ The space requirements report provides two elements, &lt;**storeSize**&gt; and &
</PreMigration>
```
Additionally, USMT performs a compliance check for a required minimum of 250 MB of available disk space and won't create a store if the compliance check fails.
Additionally, USMT performs a compliance check for a required minimum of 250 MB of available disk space and doesn't create a store if the compliance check fails.
## Estimating migration store size
Determine how much space you'll need to store the migrated data. You should base your calculations on the volume of e-mail, personal documents, and system settings for each user. The best way to estimate the required space is to survey several computers to arrive at an average for the size of the store that you'll need.
Determine how much space is needed to store the migrated data. Calculations should be based on the volume of e-mail, personal documents, and system settings for each user. The best way to estimate the required space is to survey several computers to arrive at an average for the size of the store that is needed.
The amount of space that is required in the store will vary, depending on the local storage strategies your organization uses. For example, one key element that determines the size of migration data sets is e-mail storage. If e-mail is stored centrally, data sets will be smaller. If e-mail is stored locally, such as offline-storage files, data sets will be larger. Mobile users will typically have larger data sets than workstation users. You should perform tests and inventory the network to determine the average data set size in your organization.
The amount of space that is required in the store varies and depends on the local storage strategies the organization uses. For example, one key element that determines the size of migration data sets is e-mail storage. If e-mail is stored centrally, data sets are smaller. If e-mail is stored locally, such as offline-storage files, data sets are larger. Mobile users typically have larger data sets than workstation users. Tests should be performed and the network inventoried to determine the average data set size in the organization.
> [!NOTE]
> You can create a space-estimate file (`Usmtsize.txt`) to estimate the size of the store by using the legacy `/p` command-line option .
>
> A space-estimate file (`Usmtsize.txt`) can be created to estimate the size of the store by using the legacy `/p` command-line option.
When trying to determine how much disk space you'll need, consider the following issues:
When trying to determine how much disk space is needed, consider the following issues:
- **E-mail**: If users deal with a large volume of e-mail or keep e-mail on their local computers instead of on a mail server, the e-mail can take up as much disk space as all other user files combined. Prior to migrating user data, make sure that users who store e-mail locally synchronize their inboxes with their mail server.
- **User documents**: Frequently, all of a user's documents fit into less than 50 MB of space, depending on the types of files involved. This estimate assumes typical office work, such as word-processing documents and spreadsheets. This estimate can vary substantially based on the types of documents that your organization uses. For example, an architectural firm that predominantly uses computer-aided design (CAD) files needs much more space than a law firm that primarily uses word-processing documents. You don't need to migrate the documents that users store on file servers through mechanisms such as Folder Redirection, as long as users will have access to these locations after the migration.
- **User documents**: Frequently, all of a user's documents fit into less than 50 MB of space, depending on the types of files involved. This estimate assumes typical office work, such as word-processing documents and spreadsheets. This estimate can vary substantially based on the types of documents that the organization uses. For example, an architectural firm that predominantly uses computer-aided design (CAD) files needs more space than a law firm that primarily uses word-processing documents. Documents that users store on file servers through mechanisms such as Folder Redirection don't need to be migrated, as long as users will have access to these locations after the migration.
- **User system settings**: Five megabytes is adequate space to save the registry settings. This requirement can fluctuate, however, based on the number of applications that have been installed. It's rare, however, for the user-specific portion of the registry to exceed 5 MB.
- **User system settings**: Five megabytes is adequate space to save the registry settings. This requirement can fluctuate, however, based on the number of applications that are installed. It's rare, however, for the user-specific portion of the registry to exceed 5 MB.
## Related articles
[Common migration scenarios](usmt-common-migration-scenarios.md)
- [Common migration scenarios](usmt-common-migration-scenarios.md).

61
windows/deployment/usmt/usmt-exclude-files-and-settings.md
View File

@ -1,40 +1,44 @@
---
title: Exclude Files and Settings (Windows 10)
title: Exclude Files and Settings
description: In this article, learn how to exclude files and settings when creating a custom .xml file and a Config.xml file.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 09/18/2023
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Exclude files and settings
When you specify the migration .xml files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, the User State Migration Tool (USMT) 10.0 migrates the settings and components listed, as discussed in [What does USMT migrate?](usmt-what-does-usmt-migrate.md) You can create a custom .xml file to further specify what to include or exclude in the migration. In addition, you can create a `Config.xml` file to exclude an entire component from a migration. You can't, however, exclude users by using the migration .xml files or the `Config.xml` file. The only way to specify which users to include and exclude is by using the user options on the command line in the ScanState tool. For more information, see the [User options](usmt-scanstate-syntax.md#user-options) section of the [ScanState syntax](usmt-scanstate-syntax.md) article.
When the migration **.xml** files `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml` are specified, the User State Migration Tool (USMT) migrates the settings and components listed, as discussed in [What does USMT migrate?](usmt-what-does-usmt-migrate.md) A custom **.xml** file can be created to further specify what to include or exclude in the migration. In addition, a `Config.xml` file can be created to exclude an entire component from a migration. However, users can't be excluded by using the migration **.xml** files or the `Config.xml` file. The only way to specify which users to include and exclude is by using the user options on the command line in the **ScanState** tool. For more information, see the [User options](usmt-scanstate-syntax.md#user-options) section of the [ScanState syntax](usmt-scanstate-syntax.md) article.
Methods to customize the migration and include and exclude files and settings include:
- [Create a custom .xml file](#create-a-custom-xml-file). You can use the following elements to specify what to exclude:
- [Create a custom .xml file](#create-a-custom-xml-file). The following elements can be used to specify what to exclude:
- [Include and exclude](#include-and-exclude): You can use the **&lt;include&gt;** and **&lt;exclude&gt;** elements to exclude objects with conditions. For example, you can migrate all files located in the `C:\` drive, except any `.mp3` files. It's important to remember that [Conflicts and precedence](usmt-conflicts-and-precedence.md) apply to these elements.
- [Include and exclude](#include-and-exclude): The **\<include\>** and **\<exclude\>** elements can be used to exclude objects with conditions. For example, all files located in the `C:\` drive can be migrated, except any `.mp3` files. It's important to remember that [Conflicts and precedence](usmt-conflicts-and-precedence.md) apply to these elements.
- [unconditionalExclude](#example-1-how-to-migrate-all-files-from-c-except-mp3-files): You can use the **&lt;unconditionalExclude&gt;** element to globally exclude data. This element takes precedence over all other include and exclude rules in the .xml files. Therefore, this element excludes objects regardless of any other **&lt;include&gt;** rules that are in the .xml files. For example, you can exclude all .mp3 files on the computer, or you can exclude all files from C:\\UserData.
- [unconditionalExclude](#example-1-how-to-migrate-all-files-from-c-except-mp3-files): The **\<unconditionalExclude\>** element can be used to globally exclude data. This element takes precedence over all other include and exclude rules in the **.xml** files. Therefore, this element excludes objects regardless of any other **\<include\>** rules that are in the **.xml** files. For example, all **.mp3** files can be excluded on the computer, or all files from C:\\UserData can be excluded.
- [Create a Config.xml file](#create-a-config-xml-file): You can create and modify a `Config.xml` file to exclude an entire component from the migration. For example, you can use this file to exclude the settings for one of the default applications. In addition, creating and modifying a `Config.xml` file is the only way to exclude the operating-system settings that are migrated to computers running Windows. Excluding components using this file is easier than modifying the migration .xml files because you don't need to be familiar with the migration rules and syntax.
- [Create a Config.xml file](#create-a-config-xml-file): A `Config.xml` file can be created and modified to exclude an entire component from the migration. For example, this file can be used to exclude the settings for one of the default applications. In addition, creating and modifying a `Config.xml` file is the only way to exclude the operating-system settings that are migrated to computers running Windows. Excluding components using this file is easier than modifying the migration **.xml** files because familiarity with the migration rules and syntax isn't required.
## Create a custom .xml file
We recommend that you create a custom .xml file instead of modifying the default migration .xml files. When you use a custom .xml file, you can keep your changes separate from the default .xml file, which makes it easier to track your modifications.
Microsoft recommends creating a custom **.xml** file instead of modifying the default migration **.xml** files. When a custom **.xml** file is used, the changes can be kept separate from the default **.xml** file, which makes it easier to track the modifications.
### &lt;include&gt; and &lt;exclude&gt;
### \<include\> and \<exclude\>
The migration .xml files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, contain the **&lt;component&gt;** element, which typically represents a self-contained component or an application such as Microsoft® Office Outlook® and Word. To exclude the files and registry settings that are associated with these components, use the **&lt;include&gt;** and **&lt;exclude&gt;** elements. For example, you can use these elements to migrate all files and settings with pattern X except files and settings with pattern Y, where Y is more specific than X. For the syntax of these elements, see [USMT XML Reference](usmt-xml-reference.md).
The migration **.xml** files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, contain the **\<component\>** element, which typically represents a self-contained component or an application such as Microsoft Office Outlook and Word. To exclude the files and registry settings that are associated with these components, use the **\<include\>** and **\<exclude\>** elements. For example, these elements can be used to migrate all files and settings with pattern X except files and settings with pattern Y, where Y is more specific than X. For the syntax of these elements, see [USMT XML Reference](usmt-xml-reference.md).
> [!NOTE]
>
> If you specify an **&lt;exclude&gt;** rule, always specify a corresponding **&lt;include&gt;** rule. Otherwise, if you don't specify an **&lt;include&gt;** rule, the specific files or settings aren't included. They're already excluded from the migration. Thus, an unaccompanied **&lt;exclude&gt;** rule is unnecessary.
> If an **\<exclude\>** rule is specified, always specify a corresponding **\<include\>** rule. Otherwise, if an **\<include\>** rule isn't specified, the specific files or settings aren't included. They're already excluded from the migration. Thus, an unaccompanied **\<exclude\>** rule is unnecessary.
- [Example 1: How to migrate all files from C:\\ except .mp3 files](#example-1-how-to-migrate-all-files-from-c-except-mp3-files)
@ -48,7 +52,7 @@ The migration .xml files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, contai
### Example 1: How to migrate all files from `C:\` except `.mp3` files
The following .xml file migrates all files located on the C: drive, except any .mp3 files.
The following **.xml** file migrates all files located on the C: drive, except any **.mp3** files.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/mp3files">
@ -75,7 +79,7 @@ The following .xml file migrates all files located on the C: drive, except any .
### Example 2: How to migrate all files located in `C:\Data` except files in `C:\Data\tmp`
The following .xml file migrates all files and subfolders in `C:\Data`, except the files and subfolders in `C:\Data\tmp`.
The following **.xml** file migrates all files and subfolders in `C:\Data`, except the files and subfolders in `C:\Data\tmp`.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -101,7 +105,7 @@ The following .xml file migrates all files and subfolders in `C:\Data`, except t
### Example 3: How to exclude the files in a folder but include all subfolders
The following .xml file migrates any subfolders in `C:\`EngineeringDrafts`, but excludes all files that are in `C:\EngineeringDrafts`.
The following **.xml** file migrates any subfolders in `C:\EngineeringDrafts`, but excludes all files that are in `C:\EngineeringDrafts`.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -127,7 +131,7 @@ The following .xml file migrates any subfolders in `C:\`EngineeringDrafts`, but
### Example 4: How to exclude a file from a specific folder
The following .xml file migrates all files and subfolders in `C:\EngineeringDrafts`, except for the `Sample.doc` file in `C:\EngineeringDrafts`.
The following **.xml** file migrates all files and subfolders in `C:\EngineeringDrafts`, except for the `Sample.doc` file in `C:\EngineeringDrafts`.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -153,13 +157,13 @@ The following .xml file migrates all files and subfolders in `C:\EngineeringDraf
### Example 5: How to exclude a file from any location
To exclude a Sample.doc file from any location on the C: drive, use the **&lt;pattern&gt;** element. If multiple files exist with the same name on the C: drive, all of these files are excluded.
To exclude a Sample.doc file from any location on the C: drive, use the **\<pattern\>** element. If multiple files exist with the same name on the C: drive, all of these files are excluded.
```xml
<pattern type="File"> C:\* [Sample.doc] </pattern>
```
To exclude a Sample.doc file from any drive on the computer, use the **&lt;script&gt;** element. If multiple files exist with the same name, all of these files are excluded.
To exclude a Sample.doc file from any drive on the computer, use the **\<script\>** element. If multiple files exist with the same name, all of these files are excluded.
```xml
<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>
@ -171,7 +175,7 @@ Here are some examples of how to use XML to exclude files, folders, and registry
##### Example 1: How to exclude all `.mp3` files
The following .xml file excludes all `.mp3` files from the migration:
The following **.xml** file excludes all `.mp3` files from the migration:
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/excludefiles">
@ -192,7 +196,7 @@ The following .xml file excludes all `.mp3` files from the migration:
##### Example 2: How to exclude all of the files on a specific drive
The following .xml file excludes only the files located on the C: drive.
The following **.xml** file excludes only the files located on the C: drive.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/allfiles">
@ -213,7 +217,7 @@ The following .xml file excludes only the files located on the C: drive.
##### Example 3: How to exclude registry keys
The following .xml file unconditionally excludes the `HKEY_CURRENT_USER` registry key and all of its subkeys.
The following **.xml** file unconditionally excludes the `HKEY_CURRENT_USER` registry key and all of its subkeys.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -240,7 +244,7 @@ The following .xml file unconditionally excludes the `HKEY_CURRENT_USER` registr
##### Example 4: How to Exclude `C:\Windows` and `C:\Program Files`
The following .xml file unconditionally excludes the system folders of `C:\Windows` and `C:\Program Files`. All `*.docx`, `*.xls` and `*.ppt` files aren't migrated because the **&lt;unconditionalExclude&gt;** element takes precedence over the **&lt;include&gt;** element.
The following **.xml** file unconditionally excludes the system folders of `C:\Windows` and `C:\Program Files`. All `*.docx`, `*.xls` and `*.ppt` files aren't migrated because the **\<unconditionalExclude\>** element takes precedence over the **\<include\>** element.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -270,22 +274,21 @@ The following .xml file unconditionally excludes the system folders of `C:\Windo
## Create a Config XML File
You can create and modify a `Config.xml` file if you want to exclude components from the migration. Excluding components using this file is easier than modifying the migration .xml files because you don't need to be familiar with the migration rules and syntax. `Config.xml` is an optional file that you can create using the `/genconfig` command-line option with the ScanState tool. For example, you can use the `Config.xml` file to exclude the settings for one of the default applications. In addition, creating and modifying this file is the only way to exclude the operating-system settings that are migrated to computers running Windows.
A `Config.xml` file can be created and modified to exclude components from the migration. Excluding components using this file is easier than modifying the migration **.xml** files because familiarity with the migration rules and syntax isn't required. `Config.xml` is an optional file that can be created using the `/genconfig` command-line option with the **ScanState** tool. For example, the `Config.xml` file can be used to exclude the settings for one of the default applications. In addition, creating and modifying this file is the only way to exclude the operating-system settings that are migrated to computers running Windows.
- **To exclude the settings for a default application:** Specify `migrate="no"` for the application under the **&lt;Applications&gt;** section of the `Config.xml` file.
- **To exclude the settings for a default application:** Specify `migrate="no"` for the application under the **\<Applications\>** section of the `Config.xml` file.
- **To exclude an operating system setting:** Specify `migrate="no"` for the setting under the **&lt;WindowsComponents&gt;** section.
- **To exclude an operating system setting:** Specify `migrate="no"` for the setting under the **\<WindowsComponents\>** section.
- **To exclude My Documents:** Specify `migrate="no"` for **My Documents** under the **&lt;Documents&gt;** section. Any **&lt;include&gt;** rules in the .xml files are still applied. For example, if you have a rule that includes all the .docx files in My Documents, then .docx files are still migrated. However, any additional files that aren't .docx aren't migrated.
- **To exclude the Documents folder:** Specify `migrate="no"` for the **Documents** folder under the **\<Documents\>** section. Any **\<include\>** rules in the **.xml** files are still applied. For example, if a rule exists that includes all the **.docx** files in the **Documents** folder, then **.docx** files are still migrated. However, any additional files that aren't **.docx** aren't migrated.
For more information, see [Config.xml File](usmt-configxml-file.md).
> [!NOTE]
>
> To exclude a component from the `Config.xml` file, set the **migrate** value to **"no"**. Deleting the XML tag for the component from the `Config.xml` file doesn't exclude the component from your migration.
> To exclude a component from the `Config.xml` file, set the **migrate** value to **"no"**. Deleting the XML tag for the component from the `Config.xml` file doesn't exclude the component from the migration.
## Related articles
- [Customize USMT XML files](usmt-customize-xml-files.md)
- [USMT XML reference](usmt-xml-reference.md)
- [Customize USMT XML files](usmt-customize-xml-files.md).
- [USMT XML reference](usmt-xml-reference.md).

42
windows/deployment/usmt/usmt-extract-files-from-a-compressed-migration-store.md
View File

@ -1,18 +1,22 @@
---
title: Extract Files from a Compressed USMT Migration Store (Windows 10)
title: Extract Files from a Compressed USMT Migration Store
description: In this article, learn how to extract files from a compressed User State Migration Tool (USMT) migration store.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Extract files from a compressed USMT migration store
When you migrate files and settings during a typical PC-refresh migration, you usually create a compressed migration store file on the intermediate store. This migration store is a single image file that contains all files being migrated as well as a catalog file. To protect the compressed file, you can encrypt it by using different encryption algorithms. When you migrate the file back to the source computer after the operating system is installed, you can run the **UsmtUtils** command with the `/extract` option to recover the files from the compressed migration store. You can also use the **UsmtUtils** command with the `/extract` option any time you need to recover data from a migration store.
When files and settings are migrated during a typical PC-refresh migration, a compressed migration store file is usually created on the intermediate store. This migration store is a single image file that contains all files being migrated as well as a catalog file. To protect the compressed file, it can be encrypted by using different encryption algorithms. When the file is migrated back to the source computer after the operating system is installed, the **UsmtUtils** command can be run with the `/extract` option to recover the files from the compressed migration store. The **UsmtUtils** command with the `/extract` option can also be used any time data needs to be recovered from a migration store.
Options used with the `/extract` option can specify:
@ -22,7 +26,7 @@ Options used with the `/extract` option can specify:
- Include and exclude patterns for selective data extraction.
In addition, you can specify the file patterns that you want to extract by using the `/i` option to include file patterns or the `/e` option to exclude file patterns. When both the `/i` option and the `/e` option are used in the same command, include patterns take precedence over exclude patterns. Note that this is different from the include and exclude rules used in the **ScanState** and **LoadState** tools.
In addition, the file patterns that need to be extracted can be specified by using the `/i` option to include file patterns or the `/e` option to exclude file patterns. When both the `/i` option and the `/e` option are used in the same command, include patterns take precedence over exclude patterns. The `/i` and the `/e` options are different from the include and exclude rules used in the **ScanState** and **LoadState** tools.
## To run the UsmtUtils tool with the /extract option
@ -34,23 +38,23 @@ UsmtUtils.exe /extract <filePath> <destinationPath> [/i:<includePattern>] [/e:<e
Where the placeholders have the following values:
- **&lt;USMTpath&gt;** is the location where you have saved the USMT files and tools.
- **\<USMTpath\>** is the location where the USMT files and tools are saved.
- **&lt;filePath&gt;** is the location of the migration store.
- **\<filePath\>** is the location of the migration store.
- **&lt;destination path&gt;** is the location of the file where you want the **/extract** option to put the extracted migration store contents.
- **\<destination path\>** is the location of the file where the **/extract** option should put the extracted migration store contents.
- **&lt;includePattern&gt;** specifies the pattern for the files to include in the extraction.
- **\<includePattern\>** specifies the pattern for the files to include in the extraction.
- **&lt;excludePattern&gt;** specifies the pattern for the files to omit from the extraction.
- **\<excludePattern\>** specifies the pattern for the files to omit from the extraction.
- **&lt;AlgID&gt;** is the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line.
- **\<AlgID\>** is the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line.
- **&lt;logfile&gt;** is the location and name of the log file.
- **\<logfile\>** is the location and name of the log file.
- **&lt;keystring&gt;** is the encryption key that was used to encrypt the migration store.
- **\<keystring\>** is the encryption key that was used to encrypt the migration store.
- **&lt;filename&gt;** is the location and name of the text file that contains the encryption key.
- **\<filename\>** is the location and name of the text file that contains the encryption key.
### To extract all files from a compressed migration store
@ -80,18 +84,16 @@ UsmtUtils.exe /extract D:\MyMigrationStore\USMT\store.mig /e:*.exe C:\ExtractedS
### To extract file types using the include pattern and the exclude pattern
To extract files from a compressed migration store, and to exclude files of one type (such as .exe files) while including only specific files, use both the include pattern and the exclude pattern, as in this example:
When files are extracted from a compressed migration store, both the include and the exclude patterns can be used at the same time. Files of one type can be excluded while files of another type can be included. For example:
```cmd
UsmtUtils.exe /extract D:\MyMigrationStore\USMT\store.mig /i:myProject.* /e:*.exe C:\ExtractedStore /o
```
In this example, if there is a myProject.exe file, it will also be extracted because the include pattern option takes precedence over the exclude pattern option.
In this example, if there's a **myProject.exe** file, the file is also extracted because the include pattern option takes precedence over the exclude pattern option.
## Related articles
[UsmtUtils syntax](usmt-utilities.md)
[Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes)
[Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md)
- [UsmtUtils syntax](usmt-utilities.md).
- [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes).
- [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md).

87
windows/deployment/usmt/usmt-faq.yml
View File

@ -1,7 +1,7 @@
### YamlMime:FAQ
metadata:
title: 'Frequently Asked Questions (Windows 10)'
description: 'Learn about frequently asked questions and recommended solutions for migrations using User State Migration Tool (USMT) 10.0.'
title: 'USMT Frequently Asked Questions'
description: 'Learn about frequently asked questions and recommended solutions for migrations using User State Migration Tool (USMT).'
ms.assetid: 813c13a7-6818-4e6e-9284-7ee49493241b
ms.prod: windows-client
ms.technology: itpro-deploy
@ -11,11 +11,16 @@ metadata:
ms.mktglfcycl: deploy
ms.sitesec: library
audience: itpro
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: faq
title: Frequently Asked Questions
summary: |
The following sections provide frequently asked questions and recommended solutions for migrations using User State Migration Tool (USMT) 10.0.
**Applies to:**
- Windows 11
- Windows 10
The following sections provide frequently asked questions and recommended solutions for migrations using User State Migration Tool (USMT).
sections:
@ -33,54 +38,66 @@ sections:
- Uncompressed store
- question: |
Can I store the files and settings directly on the destination computer or do I need a server?
Can the files and settings be stored directly on the destination computer or is a server needed?
answer: |
You don't need to save the files to a server. If you're moving the user state to a new computer, you can create the store on a shared folder, on media that you can remove, such as a USB flash drive (UFD), or you can store it directly on the destination computer, as in the following steps:
Files don't need to be saved to a server. If moving the user state to a new computer, the store can be created on:
- A shared folder.
- On removable media, such as a USB flash drive (UFD).
- Directly on the destination computer.
To store it directly on the destination computer:
1. Create and share the directory `C:\store` on the destination computer.
2. Run the **ScanState** tool on the source computer and save the files and settings to `\\<DestinationComputerName>\store`
1. Run the **ScanState** tool on the source computer and save the files and settings to `\\<DestinationComputerName>\store`
3. Run the **LoadState** tool on the destination computer and specify `C:\store` as the store location.
1. Run the **LoadState** tool on the destination computer and specify `C:\store` as the store location.
- question: |
Can I migrate data between operating systems with different languages?
Can data be migrated between operating systems with different languages?
answer: |
No. USMT doesn't support migrating data between operating systems with different languages; the source computer's operating-system language must match the destination computer's operating-system language.
- question: |
Can I change the location of the temporary directory on the destination computer?
Can the location of the temporary directory on the destination computer be changed?
answer: |
Yes. The environment variable `USMT\_WORKING\_DIR` can be changed to an alternative temporary directory. There are some offline migration scenarios where changing the temporary directory is necessary, for example, when the USMT binaries are located on read-only Windows Preinstallation Environment (WinPE) boot media.
- question: |
How do I install USMT?
How is USMT installed?
answer: |
Because USMT is included in Windows Assessment and Deployment Kit (Windows ADK), you need to install the Windows ADK package on at least one computer in your environment. The USMT binaries can then be copied from the USMT directory located on the original computer where the Windows ADK was installed to additional client computers.
Because USMT is included in Windows Assessment and Deployment Kit (Windows ADK), the Windows ADK package needs to be installed on at least one computer in the environment. The USMT binaries can then be copied from the USMT directory located on the original computer where the Windows ADK was installed to additional client computers.
- question: |
How do I uninstall USMT?
How is USMT uninstalled?
answer: |
If you've installed the Windows ADK on the computer, uninstalling Windows ADK will uninstall USMT. For client computers that don't have the Windows ADK installed, you can delete the USMT directory to uninstall USMT.
For computers that have the Windows ADK installed, uninstalling the Windows ADK from the computer uninstalls USMT. For client computers that don't have the Windows ADK installed, the USMT directory can be deleted to uninstall USMT.
- name: Files and Settings
questions:
- question: |
How can I exclude a folder or a certain type of file from the migration?
How can a folder or a certain type of file be excluded from the migration?
answer: |
You can use the **&lt;unconditionalExclude&gt;** element to globally exclude data from the migration. For example, you can use this element to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`. This element excludes objects regardless of any other **&lt;include&gt;** rules that are in the .xml files. For an example, see **&lt;unconditionalExclude&gt;** in the [Exclude files and settings](usmt-exclude-files-and-settings.md) article. For the syntax of this element, see [XML elements library](usmt-xml-elements-library.md).
The **\<unconditionalExclude\>** element can be used to globally exclude data from the migration. For example, this element can be used to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`. This element excludes objects regardless of any other **\<include\>** rules that are in the **.xml** files. For an example, see **\<unconditionalExclude\>** in the [Exclude files and settings](usmt-exclude-files-and-settings.md) article. For the syntax of this element, see [XML elements library](usmt-xml-elements-library.md).
- question: |
What happens to files that were located on a drive that don't exist on the destination computer?
answer: |
USMT migrates the files to the `%SystemDrive%` while maintaining the correct folder hierarchy. For example, if `E:\data\File.pst` is on the source computer, but the destination computer doesn't have an E:\\ drive, the file will be migrated to `C:\data\File.pst`, if C:\\ is the system drive. This behavior holds true even when **&lt;locationModify&gt;** rules attempt to move data to a drive that doesn't exist on the destination computer.
USMT migrates the files to the `%SystemDrive%` while maintaining the correct folder hierarchy. For example:
- `E:\data\File.pst` is on the source computer.
- Destination computer doesn't have an E:\\ drive.
- C:\\ is the system drive on the destination computer.
the file is migrated to `C:\data\File.pst`. This behavior holds true even when **\<locationModify\>** rules attempt to move data to a drive that doesn't exist on the destination computer.
- name: USMT .xml Files
questions:
- question: |
Where can I get examples of USMT .xml files?
Where are there examples of USMT **.xml** files?
answer: |
The following articles include examples of USMT .xml files:
The following articles include examples of USMT **.xml** files:
- [Exclude files and settings](usmt-exclude-files-and-settings.md)
@ -91,37 +108,37 @@ sections:
- [Custom XML examples](usmt-custom-xml-examples.md)
- question: |
Can I use custom .xml files that were written for USMT 5.0?
Can custom **.xml** files that were written for USMT 5.0 be used?
answer: |
Yes. You can use custom .xml files that were written for USMT 5.0 with USMT for Windows 10. However, in order to use new USMT functionality, you must revisit your custom USMT files and refresh them to include the new command-line options and XML elements.
Yes. Custom **.xml** files that were written for USMT 5.0 can be used with newer versions of USMT. However, in order to use new USMT functionality, the custom USMT files must be revisited and refreshed to include the new command-line options and XML elements.
- question: |
How can I validate the .xml files?
How can the **.xml** files be validated?
answer: |
You can use the USMT XML Schema (`MigXML.xsd`) to write and validate migration .xml files.
The USMT XML Schema (`MigXML.xsd`) can be used to write and validate migration **.xml** files.
- question: |
Why must I list the .xml files with both the `ScanState.exe` and `LoadState.exe` commands?
Why must the **.xml** files be included with both the `ScanState.exe` and `LoadState.exe` commands?
answer: |
The .xml files aren't copied to the store as in previous versions of USMT. Because the **ScanState** and **LoadState** tools need the .xml files to control the migration, you must specify the same set of .xml files for the `ScanState.exe` and `LoadState.exe` commands. If you used a particular set of mig\*.xml files in the **ScanState** tool, either called through the `/auto` option, or individually through the `/i` option, then you should use same option to call the exact same mig\*.xml files in the **LoadState** tool. However, you don't have to specify the `Config.xml` file, unless you want to exclude some of the files and settings that you migrated to the store. For example, you might want to migrate the **My Documents** folder to the store, but not to the destination computer. To do this type of migration, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. **LoadState** will migrate only the files and settings that you want to migrate.
The **.xml** files aren't copied to the store as in previous versions of USMT. Because the **ScanState** and **LoadState** tools need the **.xml** files to control the migration, the same set of **.xml** files must be specified for the `ScanState.exe` and `LoadState.exe` commands. If a particular set of mig\*.xml files were used in the **ScanState** tool, either called through the `/auto` option, or individually through the `/i` option, then the same option should be used to call the exact same mig\*.xml files in the **LoadState** tool. However, the `Config.xml` file doesn't need to be specified, unless files and settings that were migrated to the store need to be excluded. For example, the **Documents** folder might be migrated to the store, but not to the destination computer. To do this type of migration, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. **LoadState** migrates only the desired files and settings.
If you exclude an .xml file from the `LoadState.exe` command, then all of the data that is in the store that was migrated with the missing .xml files will be migrated. However, the migration rules that were specified for the `ScanState.exe` command won't apply. For example, if you exclude a `MigApp.xml` file that has a rerouting rule such as `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")`, USMT won't reroute the files. Instead, it will migrate them to `C:\data`.
If an **.xml** file is excluded from the `LoadState.exe` command, then all of the data in the store that was migrated with the missing **.xml** files are migrated. However, the migration rules that were specified for the `ScanState.exe` command don't apply. For example, if a `MigApp.xml` file that has a rerouting rule such as `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")` is excluded, USMT doesn't reroute the files. Instead, it migrates them to `C:\data`.
- question: |
Which files can I modify and specify on the command line?
Which files can be modified and specified on the command line?
answer: |
You can specify the `MigUser.xml` and `MigApp.xml` files on the command line. You can modify each of these files. The migration of operating system settings is controlled by the manifests, which you can't modify. If you want to exclude certain operating-system settings or any other components, create and modify the `Config.xml` file.
The `MigUser.xml`, `MigApp.xml`, and `MigDocs.xml` files can be specified on the command line. Each of these files can be modified. Manifests control the migration of operating system settings. Manifests can't be modified. To exclude certain operating-system settings or any other components, create and modify the `Config.xml` file.
- question: |
What happens if I don't specify the .xml files on the command line?
What happens if the **.xml** files aren't specified on the command line?
answer: |
- **ScanState**
If you don't specify any files with the `ScanState.exe` command, all user accounts and default operating system components are migrated.
If no files are specified with the `ScanState.exe` command, all user accounts and default operating system components are migrated.
- **LoadState**
If you don't specify any files with the `LoadState.exe` command, all data that is in the store is migrated. However, any target-specific migration rules that were specified in .xml files with the `ScanState.exe` command won't apply. For example, if you exclude a `MigApp.xml` file that has a rerouting rule such as `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")`, USMT won't reroute the files. Instead, it will migrate them to `C:\data`.
If no files are specified with the `LoadState.exe` command, all data that is in the store is migrated. However, any target-specific migration rules that were specified in **.xml** files with the `ScanState.exe` command doesn't apply. For example, if a `MigApp.xml` file that has a rerouting rule such as `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")` is excluded, USMT doesn't reroute the files. Instead, it migrates them to `C:\data`.
- name: Conflicts and Precedence
questions:
@ -135,8 +152,6 @@ additionalContent: |
## Related topics
[User State Migration Tool (USMT) Troubleshooting](usmt-troubleshooting.md)
[Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md)
[Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md)
- [User State Migration Tool (USMT) Troubleshooting](usmt-troubleshooting.md).
- [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md).
- [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md).

72
windows/deployment/usmt/usmt-general-conventions.md
View File

@ -1,58 +1,62 @@
---
title: General Conventions (Windows 10)
title: General Conventions
description: Learn about general XML guidelines and how to use XML helper functions in the XML Elements library to change migration behavior.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# General conventions
This topic describes the XML helper functions.
This article describes the XML helper functions.
## General XML guidelines
Before you modify the .xml files, become familiar with the following guidelines:
Before modifying the **.xml** files, become familiar with the following guidelines:
- **XML schema**
- **XML schema.**
You can use the User State Migration Tool (USMT) 10.0 XML schema, MigXML.xsd, to write and validate migration .xml files.
The User State Migration Tool (USMT) XML schema, `MigXML.xsd`, can be used to write and validate migration **.xml** files.
- **Conflicts**
- **Conflicts.**
In general, when there are conflicts within the XML schema, the most specific pattern takes precedence. For more information, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
- **Required elements**
- **Required elements.**
The required elements for a migration .xml file are **&lt;migration&gt;**, **&lt;component&gt;**, **&lt;role&gt;**, and **&lt;rules&gt;**.
The required elements for a migration **.xml** file are **\<migration\>**, **\<component\>**, **\<role\>**, and **\<rules\>**.
- **Required child elements**
- **Required child elements.**
- USMT doesn't fail with an error if you don't specify the required child elements. However, you must specify the required child elements for the parent element to affect the migration.
- USMT doesn't fail with an error if the required child elements aren't specified. However, the required child elements must be specified for the parent element to affect the migration.
- The required child elements apply only to the first definition of the element. If these elements are defined and then referred to using their name, the required child elements don't apply. For example, if you define `<detects name="Example">` in **&lt;namedElements&gt;**, and you specify `<detects name="Example"/>` in **&lt;component&gt;** to refer to this element, the definition inside **&lt;namedElements&gt;** must have the required child elements, but the **&lt;component&gt;** element doesn't need to have the required child elements.
- The required child elements apply only to the first definition of the element. If these elements are defined and then referred to using their name, the required child elements don't apply. For example, if `<detects name="Example">` is defined in **\<namedElements\>**, and `<detects name="Example"/>` is specified in **\<component\>** to refer to this element, the definition inside **\<namedElements\>** must have the required child elements, but the **\<component\>** element doesn't need to have the required child elements.
- **File names with brackets**
- **File names with brackets.**
If you're migrating a file that has a bracket character (\[ or \]) in the file name, you must insert a carat (^) character directly before the bracket for the bracket character to be valid. For example, if there's a file named **file].txt**, you must specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.
If a file that has a bracket character (\[ or \]) in the file name is being migrated, a carat (^) character must be inserted. The carat (^) character must be directly before the bracket for the bracket character 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>`.
- **Using quotation marks**
- **Using quotation marks.**
When you surround code in quotation marks, you can use either double ("") or single (') quotation marks.
When code is surrounded in quotation marks, either the double ("") or the single (') quotation marks can be used.
## Helper functions
You can use the XML helper functions in the [XML elements library](usmt-xml-elements-library.md) to change migration behavior. Before you use these functions in an .xml file, note the following items:
The XML helper functions in the [XML elements library](usmt-xml-elements-library.md) can be used to change migration behavior. Before using these functions in an **.xml** file, note the following items:
- **All of the parameters are strings**
- **All of the parameters are strings.**
- **You can leave NULL parameters blank**
- **NULL parameters can be left blank.**
As with parameters with a default value convention, if you have a NULL parameter at the end of a list, you can leave it out. For example, the following function:
As with parameters with a default value convention, if there's a NULL parameter at the end of a list, it can be left out. For example, the following function:
```cmd
SomeFunction("My String argument",NULL,NULL)
@ -64,20 +68,36 @@ You can use the XML helper functions in the [XML elements library](usmt-xml-elem
SomeFunction("My String argument")
```
- **The encoded location used in all the helper functions is an unambiguous string representation for the name of an object**
- **The encoded location used in all the helper functions is an unambiguous string representation for the name of an object.**
It's composed of the node part, optionally followed by the leaf enclosed in square brackets. This format makes a clear distinction between nodes and leaves.
The encoded location is composed of the node part, optionally followed by the leaf enclosed in square brackets. This format makes a clear distinction between nodes and leaves.
For example, specify the file `C:\Windows\Notepad.exe`: **c:\\Windows\[Notepad.exe\]**. Similarly, specify the directory `C:\Windows\System32` like this: **c:\\Windows\\System32**; note the absence of the **\[\]** characters.
For example, specify the file
`C:\Windows\Notepad.exe`
as
**c:\\Windows\[Notepad.exe\]**
Similarly, specify the directory
`C:\Windows\System32`
as
**c:\\Windows\\System32**
Note the absence of the **\[\]** characters in second example.
The registry is represented in a similar way. The default value of a registry key is represented as an empty **\[\]** construct. For example, the default value for the `HKLM\SOFTWARE\MyKey` registry key is **HKLM\\SOFTWARE\\MyKey\[\]**.
- **You specify a location pattern in a way that is similar to how you specify an actual location**
- **A location pattern is specified in a way that is similar to how an actual location is specified.**
The exception is that both the node and leaf part accept patterns. However, a pattern from the node doesn't extend to the leaf.
For example, the pattern **c:\\Windows\\\\\*** will match the `\Windows` directory and all subdirectories, but it will not match any of the files in those directories. To match the files as well, you must specify **c:\\Windows\\\*\[\*\]**.
For example, the pattern **c:\\Windows\\\\\*** matches the `\Windows` directory and all subdirectories, but it doesn't match any of the files in those directories. To match the files as well, **c:\\Windows\\\*\[\*\]** must be specified.
## Related articles
[USMT XML reference](usmt-xml-reference.md)
- [USMT XML reference](usmt-xml-reference.md).

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

@ -1,78 +1,87 @@
---
title: Hard-Link Migration Store (Windows 10)
title: Hard-Link Migration Store
description: Use of a hard-link migration store for a computer-refresh scenario drastically improves migration performance and significantly reduces hard-disk utilization.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Hard-Link Migration Store
A **hard-link migration store** enables you to perform an in-place migration where all user state is maintained on the computer while the old operating system is removed and the new operating system is installed. This functionality is what makes **hard-link migration store** best suited for the computer-refresh scenario. Use of a hard-link migration store for a computer-refresh scenario drastically improves migration performance and significantly reduces hard-disk utilization, reduces deployment costs, and enables entirely new migration scenarios.
A **hard-link migration store** enables an in-place migration to be performed where all user state is maintained on the computer while the old operating system is removed and the new operating system is installed. This functionality is what makes **hard-link migration store** best suited for the computer-refresh scenario. Use of a hard-link migration store for a computer-refresh scenario drastically improves migration performance and significantly reduces hard-disk utilization, reduces deployment costs, and enables entirely new migration scenarios.
## When to use a hard-link migration
You can use a hard-link migration store when your planned migration meets both of the following criteria:
A hard-link migration store can be used when the planned migration meets both of the following criteria:
- You're upgrading the operating system on existing hardware rather than migrating to new computers.
- The operating system is being upgraded on existing hardware rather than migrating to new computers.
- You're upgrading the operating system on the same volume of the computer.
- The operating system is being upgraded on the same volume of the computer.
You can't use a hard-link migration store if your planned migration includes any of the following tasks:
A hard-link migration store can't be used if the planned migration includes any of the following tasks:
- You're migrating data from one computer to a second computer.
- Data is being migrated from one computer to a different computer.
- You're migrating data from one volume on a computer to another volume, for example from `C:` to `D:`.
- Data is being migrating from one volume on a computer to another volume on the same computer, for example from `C:` to `D:`.
- You're formatting or repartitioning the disk outside of Windows Setup, or specifying a disk format or repartition during Windows Setup that will remove the migration store.
- The disk containing the migration store is being formatted or repartitioned disk either outside of Windows Setup or during Windows Setup.
## Understanding a hard-link migration
The hard-link migration store is created using the command-line option, `/hardlink`, and is equivalent to other migration-store types. However, it differs in that hard links are utilized to keep files stored on the source computer during the migration. Keeping the files in place on the source computer eliminates the redundant work of duplicating files. It also enables the performance benefits and reduction in disk utilization that define this scenario.
When you create a hard link, you give an existing file one more path. For instance, you could create a hard link to `c:\file1.txt` called `c:\hard link\myFile.txt`. These two paths relate to the same file. If you open `c:\file1.txt`, make changes, and save the file, you'll see those changes when you open `c:\hard link\myFile.txt`. If you delete `c:\file1.txt`, the file still exists on your computer as `c:\hardlink\myFile.txt`. You must delete both references to the file in order to delete the file.
When a hard link is created, an existing file is given one more path. For instance, a hard link to `c:\file1.txt` can be created called `c:\hard link\myFile.txt`. These two paths relate to the same file. If `c:\file1.txt` is opened, then changes made to the file followed by the file being saved, those changes are seen when `c:\hard link\myFile.txt` is opened. If `c:\file1.txt` is deleted, the file still exists on the computer as `c:\hardlink\myFile.txt`. Both references to the file must be deleted in order to delete the file.
> [!NOTE]
> A hard link can only be created for a file on the same volume. If you copy a hard-link migration store to another drive or external device, the files, and not the links, are copied, as in a non-compressed migration-store scenario.
>
>A hard link can only be created for a file on the same volume. If a hard-link migration store is copied to another drive or external device, the files, and not the links, are copied, as in a non-compressed migration-store scenario.
For more information about hard links, see [Hard Links and Junctions](/windows/win32/fileio/hard-links-and-junctions)
In most aspects, a hard-link migration store is identical to an uncompressed migration store. It's located where specified by the **ScanState.exe** command-line tool and you can view the contents of the store by using Windows Explorer. Once created, it can be deleted or copied to another location without changing user state. Restoring a hard-link migration store is similar to restoring any other migration store. However, as with creating the store, the same hard-link functionality is used to keep files in-place.
In most aspects, a hard-link migration store is identical to an uncompressed migration store. The hard-link migration store is located as specified by the **ScanState.exe** command-line tool. The contents of the store can be viewed by using Windows Explorer. Once created, it can be deleted or copied to another location without changing user state. Restoring a hard-link migration store is similar to restoring any other migration store. However, as with creating the store, the same hard-link functionality is used to keep files in-place.
As a best practice, it's recommended that you delete the hard-link migration store after you confirm that the **LoadState** tool has successfully migrated the files. Since **LoadState** has created new paths to the files on the new installation of a Windows operating system, deleting the hard links in the migration store will only delete one path to the files, and won't delete the actual files or the paths to them from the new operating system.
As a best practice, delete the hard-link migration store after confirming that the files are successfully migrated via the **LoadState** tool. Since **LoadState** creates new paths to the files on the new installation of a Windows operating system, deleting the hard links in the migration store only deletes one path to the files. It doesn't delete the actual files or the paths to them from the new operating system.
> [!IMPORTANT]
> Using the `/c` option will force the **LoadState** tool to continue applying files when non-fatal errors occur. If you use the `/c` option, you should verify that no errors are reported in the logs before deleting the hard-link migration store in order to avoid data loss.
>
> Using the `/c` option forces the **LoadState** tool to continue applying files when non-fatal errors occur. If the `/c` option is used, verify that no errors are reported in the logs before deleting the hard-link migration store in order to avoid data loss.
Keeping the hard-link migration store can result in extra disk space being consumed or problems with some applications for the following reasons:
- Applications reporting file-system statistics, for example, space used and free space, might incorrectly report these statistics while the hard-link migration store is present. The file may be reported twice because of the two paths that reference that file.
- Applications reporting file-system statistics, for example, space used and free space, might incorrectly report these statistics while the hard-link migration store is present. The file might be reported twice because of the two paths that reference that file.
- A hard link may lose its connection to the original file. Some applications save changes to a file by creating a temporary file and then renaming the original to a backup filename. The path that wasn't used to open the file in this application will continue to refer to the unmodified file. The unmodified file that isn't in use is taking up more disk space. You should create the hard-link migration store just before you perform the migration, and not use applications once the store is created, in order to make sure you're migrating the latest versions of all files.
- A hard link might lose its connection to the original file. Some applications save changes to a file by creating a temporary file and then renaming the original to a backup filename. The path that wasn't used to open the file in this application continues to refer to the unmodified file. The unmodified file that isn't in use is taking up more disk space. The hard-link migration store should be created just before the migration is performed. Once the store is created, applications shouldn't be used in order to make sure the latest versions of all files are being migrating.
- Editing the file by using different paths simultaneously may result in data corruption.
- Editing the file by using different paths simultaneously might result in data corruption.
> [!IMPORTANT]
>
> The read-only file attribute on migrated files is lost when the hard-link migration store is deleted. This is due to a limitation in NTFS file system hard links.
## Hard-link migration scenario
For example, a company has decided to deploy Windows 10 on all of their computers. Each employee will keep the same computer, but the operating system on each computer will be updated.
For example, an organization decides to deploy the latest supported version of Windows on all of their computers. Each employee keeps the same computer, but the operating system on each computer will be updated.
1. An administrator runs the **ScanState** command-line tool on each computer, specifying the `/hardlink` command-line option. The **ScanState** tool saves the user state to a hard-link migration store on each computer, improving performance by reducing file duplication, except in certain specific instances.
> [!NOTE]
> As a best practice, we recommend that you do not create your hard-link migration store until just before you perform the migration in order to migrate the latest versions of your files. You should not use your software applications on the computer after creating the migration store until you have finished migrating your files with **LoadState**.
>
> As a best practice, Microsoft recommends not to create the hard-link migration store until just before the migration is performed in order to migrate the latest versions of files. Software applications shouldn't be used on the computer after creating the migration store until files finish migrating with **LoadState**.
2. On each computer, an administrator installs the company's standard operating environment (SOE), which includes Windows 10 and other applications the company currently uses.
1. On each computer, an administrator installs the organization's standard operating environment (SOE), which includes the latest supported version of Windows and other applications the organization currently uses.
3. An administrator runs the **LoadState** command-line tool on each computer. The **LoadState** tool restores user state back on each computer.
1. An administrator runs the **LoadState** command-line tool on each computer. The **LoadState** tool restores user state back on each computer.
> [!NOTE]
>
> During the update of a domain-joined computer, the profiles of users whose SID cannot be resolved will not be migrated. When using a hard-link migration store, it could cause a data loss.
## Hard-link migration store details
@ -85,46 +94,52 @@ The `/hardlink` command-line option proceeds with creating the migration store o
### Hard-link store size estimation
It isn't necessary to estimate the size of a hard-link migration store since hard-link migration store on NTFS volumes will be relatively small and require much less incremental space than other store options. Estimating the size of a migration store is only useful in scenarios where the migration store is large. The only case where the local store can be large with hard-link migrations is when non-NTFS file systems exist on the system and the non-NTFS files system contain data that needs to be migrated. Since NTFS has been the default file system format for Windows XP and newer operating systems, this situation is unusual.
It isn't necessary to estimate the size of a hard-link migration store since a hard-link migration store on an NTFS volume is relatively small and require much less incremental space than other store options. Estimating the size of a migration store is only useful in scenarios where the migration store is large. The only case where the local store can be large with hard-link migrations is:
- A non-NTFS file system exists on the system.
- The non-NTFS files system contains data that needs to be migrated.
Since NTFS is the default file system format for all currently supported versions of Windows, this situation is unusual.
### Migration store path on multiple volumes
Separate hard-link migration stores are created on each NTFS volume that contain data being migrated. In this scenario, the primary migration-store location will be specified on the command line, and should be the operating-system volume. Migration stores with identical names and directory names will be created on every volume containing data being migrated. For example:
Separate hard-link migration stores are created on each NTFS volume that contain data being migrated. In this scenario, the primary migration-store location is specified on the command line, and should be the operating-system volume. Migration stores with identical names and directory names are created on every volume containing data being migrated. For example:
```cmd
```cmd
ScanState.exe /hardlink c:\USMTMIG […]
```
Running this command on a system that contains the operating system on the C: drive and the user data on the D: drive will generate migration stores in the following locations, assuming that both drives are NTFS:
Running this command on a system that contains the operating system on the C: drive and the user data on the D: drive generates migration stores in the following locations, assuming that both drives are NTFS:
`C:\USMTMIG\`
`D:\USMTMIG\`
The drive you specify on the command line for the hard-link migration store is important, because it defines where the **master migration store** should be placed. The **master migration store** is the location where data migrating from non-NTFS volumes is stored. This volume must have enough space to contain all of the data that comes from non-NTFS volumes. As in other scenarios, if a migration store already exists at the specified path, the `/o` option must be used to overwrite the existing data in the store.
The drive specified on the command line for the hard-link migration store is important, because it defines where the **master migration store** should be placed. The **master migration store** is the location where data migrating from non-NTFS volumes is stored. This volume must have enough space to contain all of the data that comes from non-NTFS volumes. As in other scenarios, if a migration store already exists at the specified path, the `/o` option must be used to overwrite the existing data in the store.
### Location modifications
Location modifications that redirect migrated content from one volume to a different volume have an adverse impact on the performance of a hard-link migration. This impact is because the migrating data that must cross system volumes can't remain in the hard-link migration store, and must be copied across the system volumes.
Location modifications that redirect migrated content from one volume to a different volume have an adverse effect on the performance of a hard-link migration. Performance is affected because the migrating data that must cross system volumes can't remain in the hard-link migration store. They must be copied across the system volumes.
### Migrating Encrypting File System (EFS) certificates and files
To migrate Encrypting File System (EFS) files to a new installation of an operating system on the same volume of the computer, specify the `/efs:hardlink` option in the `ScanState.exe` command-line syntax.
If the EFS files are being restored to a different partition, you should use the `/efs:copyraw` option instead of the `/efs:hardlink` option. Hard links can only be created for files on the same volume. Moving the files to another partition during the migration requires a copy of the files to be created on the new partition. The `/efs:copyraw` option will copy the files to the new partition in encrypted format.
If the EFS files are being restored to a different partition, the `/efs:copyraw` option should be used instead of the `/efs:hardlink` option. Hard links can only be created for files on the same volume. Moving the files to another partition during the migration requires a copy of the files to be created on the new partition. The `/efs:copyraw` option copies the files to the new partition in encrypted format.
For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md) and [Encrypted file options](usmt-scanstate-syntax.md#encrypted-file-options).
### Migrating locked files with the hard-link migration store
Files that are locked by an application or the operating system are handled differently when using a hard-link migration store.
When an application or the operating system has a lock on a file, the file is handled differently when using a hard-link migration store.
Files that are locked by the operating system can't remain in place and must be copied into the hard-link migration store. As a result, selecting many operating-system files for migration significantly reduces performance during a hard-link migration. As a best practice, we recommend that you don't migrate any files out of the `\Windows` directory, which minimizes performance-related issues.
Operating system locked files can't remain in place and must be copied into the hard-link migration store. As a result, selecting many operating-system files for migration significantly reduces performance during a hard-link migration. As a best practice, Microsoft recommends not migrating any files out of the `\Windows` directory, which minimizes performance-related issues.
Files that are locked by an application are treated the same in hard-link migrations as in other scenarios when the volume shadow-copy service isn't being utilized. The volume shadow-copy service can't be used with hard-link migrations. However, by modifying the new **&lt;HardLinkStoreControl&gt;** section in the `Config.xml` file, it's possible to enable the migration of files locked by an application.
Application locked files are treated the same in hard-link migrations as in other scenarios when the volume shadow-copy service isn't being utilized. The volume shadow-copy service can't be used with hard-link migrations. However, by modifying the new **\<HardLinkStoreControl\>** section in the `Config.xml` file, it's possible to enable the migration of files locked by an application.
> [!IMPORTANT]
> There are some scenarios in which modifying the **&lt;HardLinkStoreControl&gt;** section in the `Config.xml` file makes it more difficult to delete a hard-link migration store. In these scenarios, you must use `UsmtUtils.exe` to schedule the migration store for deletion on the next restart.
>
> There are some scenarios in which modifying the **\<HardLinkStoreControl\>** section in the `Config.xml` file makes it more difficult to delete a hard-link migration store. In these scenarios, `UsmtUtils.exe` must be used to schedule the migration store for deletion on the next restart.
## XML elements in the Config.xml file
@ -132,14 +147,15 @@ A new section in the `Config.xml` file allows optional configuration of some of
| Element | Description |
|--- |--- |
| **&lt;Policies&gt;** | This element contains elements that describe the policies that USMT follows while creating a migration store. |
| **&lt;HardLinkStoreControl&gt;** | This element contains elements that describe how to handle files during the creation of a hard link migration store. |
| **&lt;fileLocked&gt;** | This element contains elements that describe how to handle files that are locked for editing. |
| **&lt;createHardLink&gt;** | 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>` |
| **&lt;errorHardLink&gt;** | 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>` |
| **\<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>` |
> [!IMPORTANT]
> You must use the `/nocompress` option with the `/HardLink` option.
>
> The `/nocompress` option must be used with the `/HardLink` option.
The following XML sample specifies that files locked by an application under the `\Users` directory can remain in place during the migration. It also specifies that locked files that aren't located in the `\Users` directory should result in the **File in Use** error. It's important to exercise caution when specifying the paths using the **`<createhardlink>`** tag in order to minimize scenarios that make the hard-link migration store more difficult to delete.
@ -156,4 +172,4 @@ The following XML sample specifies that files locked by an application under the
## Related articles
[Plan your migration](usmt-plan-your-migration.md)
- [Plan the migration](usmt-plan-your-migration.md).

96
windows/deployment/usmt/usmt-how-it-works.md
View File

@ -1,75 +1,78 @@
---
title: How USMT Works (Windows 10)
title: How USMT Works
description: Learn how USMT works and how it includes two tools that migrate settings and data - ScanState and LoadState.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.topic: article
ms.technology: itpro-deploy
ms.date: 11/01/2022
ms.date: 01/09/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# How USMT works
USMT includes two tools that migrate settings and data: **ScanState** and **LoadState**. **ScanState** collects information from the source computer, and **LoadState** applies that information to the destination computer.
- [How USMT works](#how-usmt-works)
- [The ScanState process](#the-scanstate-process)
- [The LoadState process](#the-loadstate-process)
- [Related articles](#related-articles)
> [!NOTE]
> For more information about how USMT processes the rules and the XML files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
> [!NOTE]
>
> For more information about how USMT processes the rules and the XML files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
## The ScanState process
When you run the **ScanState** tool on the source computer, it goes through the following process:
When the **ScanState** tool runs on the source computer, it goes through the following process:
1. It parses and validates the command-line parameters, creates the `ScanState.log` file, and then begins logging.
2. It collects information about all of the migration components that need to be migrated. A *migration component* is a logical group of files, registry keys, and values. For example, the set of files, registry keys, and values that store the settings of Adobe Acrobat is grouped into a single migration component.
1. It collects information about all of the migration components that need to be migrated. A *migration component* is a logical group of files, registry keys, and values. For example, the set of files, registry keys, and values that store the settings of Adobe Acrobat is grouped into a single migration component.
There are three types of components:
- Components that migrate the operating system settings
- Components that migrate the operating system settings.
- Components that migrate application settings
- Components that migrate application settings.
- Components that migrate users' files
- Components that migrate users' files.
The **ScanState** tool collects information about the application settings and user data components from the .xml files that are specified on the command line.
The **ScanState** tool collects information about the application settings and user data components from the **.xml** files that are specified on the command line.
In Windows 7, and Windows 8, the manifest files control how the operating-system settings are migrated. You can't modify these files. If you want to exclude certain operating-system settings, you must create and modify a `Config.xml` file.
In currently supported versions of Windows, the manifest files control how the operating-system settings are migrated. These files can't be modified. To exclude certain operating-system settings, a `Config.xml` file must be created and modified.
3. **ScanState** determines which user profiles should be migrated. By default, all user profiles on the source computer are migrated. However, you can include and exclude users using the User Options. The public profile in a source computer running Windows 7, Windows 8, and Windows 10 is always migrated, and you can't exclude these profiles from the migration.
1. **ScanState** determines which user profiles should be migrated. By default, all user profiles on the source computer are migrated. However, users can be included and excluded using the [User options](usmt-scanstate-syntax.md#user-options). The System profile and the Public profile in a source computer running currently supported versions of Windows is always migrated, and these profiles can't be excluded from the migration.
4. In the **Scanning** phase, **ScanState** does the following for each user profile selected for migration:
1. In the **Scanning** phase, **ScanState** does the following for each user profile selected for migration:
1. For each component, **ScanState** checks the type of the component. If the current user profile is the system profile and the component type is **System** or **UserAndSystem**, the component is selected for this user. Otherwise, the component is ignored. Alternatively, if the current user profile isn't the system profile and the component type is **User** or **UserAndSystem**, the component is selected for this user. Otherwise, this component is ignored.
> [!NOTE]
> From this point on, **ScanState** does not distinguish between components that migrate operating-system settings, those that migrate application settings, and those that migrate users' files. **ScanState** processes all components in the same way.
>
> From this point on, **ScanState** doesn't distinguish between components that migrate operating-system settings, components that migrate application settings, and components that migrate users' files. **ScanState** processes all components in the same way.
2. Each component that is selected in the previous step is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile that is being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents`, assuming that the user profiles are stored in the `C:\Users` directory.
1. Each component that is selected in the previous step is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile that is being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents`, assuming that the user profiles are stored in the `C:\Users` directory.
3. For each selected component, **ScanState** evaluates the **&lt;detects&gt;** section. If the condition in the **&lt;detects&gt;** section evaluates to false, the component isn't processed any further. Otherwise, the processing of this component continues.
1. For each selected component, **ScanState** evaluates the **\<detects\>** section. If the condition in the **\<detects\>** section evaluates to false, the component isn't processed any further. Otherwise, the processing of this component continues.
4. For each selected component, **ScanState** evaluates the **&lt;rules&gt;** sections. For each **&lt;rules&gt;** section, if the current user profile is the system profile and the context of the **&lt;rules&gt;** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **&lt;rules&gt;** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored.
1. For each selected component, **ScanState** evaluates the **\<rules\>** sections. For each **\<rules\>** section, if the current user profile is the system profile and the context of the **\<rules\>** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **\<rules\>** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored.
5. **ScanState** creates a list of migration units that need to be migrated by processing the various subsections under this **&lt;rules&gt;** section. Each unit is collected if it's mentioned in an **&lt;include&gt;** subsection, as long as there isn't a more specific rule for it in an **&lt;exclude&gt;** subsection in the same **&lt;rules&gt;** section. For more information about precedence in the .xml files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
1. **ScanState** creates a list of migration units that need to be migrated by processing the various subsections under this **\<rules\>** section. Each unit is collected if the unit is mentioned in an **\<include\>** subsection, as long as there isn't a more specific rule for it in an **\<exclude\>** subsection in the same **\<rules\>** section. For more information about precedence in the **.xml** files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
In addition, any migration unit (such as a file, registry key, or set of registry values) that is in an &lt;UnconditionalExclude&gt; section isn't migrated.
In addition, any migration unit (such as a file, registry key, or set of registry values) that is in an \<UnconditionalExclude\> section isn't migrated.
> [!NOTE]
> **ScanState** ignores some subsections such as &lt;destinationCleanup&gt; and &lt;locationModify&gt;. These sections are evaluated only on the destination computer.
>
> **ScanState** ignores some subsections such as \<destinationCleanup\> and \<locationModify\>. These sections are evaluated only on the destination computer.
5. In the **Collecting** phase, **ScanState** creates a master list of the migration units by combining the lists that were created for each selected user profile.
1. In the **Collecting** phase, **ScanState** creates a central list of the migration units by combining the lists that were created for each selected user profile.
6. In the **Saving** phase, **ScanState** writes the migration units that were collected to the store location.
1. In the **Saving** phase, **ScanState** writes the migration units that were collected to the store location.
> [!NOTE]
> **ScanState** does not modify the source computer in any way.
>
> **ScanState** doesn't modify the source computer in any way.
## The LoadState process
@ -77,45 +80,48 @@ The **LoadState** process is similar to the **ScanState** process. The **ScanSta
1. **ScanState** parses and validates the command-line parameters, creates the `ScanState.log` file, and then begins logging.
2. **LoadState** collects information about the migration components that need to be migrated.
1. **LoadState** collects information about the migration components that need to be migrated.
**LoadState** obtains information for the application-settings components and user-data components from the migration .xml files that are specified by the `LoadState.exe` command.
**LoadState** obtains information for the application-settings components and user-data components from the migration **.xml** files that are specified by the `LoadState.exe` command.
In Windows 7, Windows 8, and Windows 10, the manifest files control how the operating-system settings are migrated. You can't modify these files. If you want to exclude certain operating-system settings, you must create and modify a `Config.xml` file.
In currently supported versions of Windows, the manifest files control how the operating-system settings are migrated. These files can't be modified. To exclude certain operating-system settings, a `Config.xml` file must be created and modified.
3. **LoadState** determines which user profiles should be migrated. By default, all user profiles present on the source computer are migrated. However, you can include and exclude users using the **User Options**. The system profile, the Public profile in a source computer running Windows 7, Windows 8, and Windows 10 is always migrated and you can't exclude these profiles from the migration.
1. **LoadState** determines which user profiles should be migrated. By default, all user profiles present on the source computer are migrated. However, users can be included and excluded using the [User options](usmt-loadstate-syntax.md#user-options). The System profile and the Public profile in a source computer running currently supported versions of Windows is always migrated and these profiles can't be excluded from the migration.
- If you're migrating local user accounts and if the accounts don't already exist on the destination computer, you must use the `/lac` command-line option. If you don't specify the `/lac` option, any local user accounts that aren't already present on the destination computer, aren't migrated.
- If local user accounts are being migrated and if the accounts don't already exist on the destination computer, the `/lac` command-line option must be used. If the `/lac` option isn't specified, any local user accounts that aren't already present on the destination computer, aren't migrated.
- The `/md` and `/mu` options are processed to rename the user profile on the destination computer, if they've been included when the `LoadState.exe` command was specified.
- When specified with the `LoadState.exe` command, the `/md` and `/mu` options are processed to rename the user profile on the destination computer.
- For each user profile selected from the store, **LoadState** creates a corresponding user profile on the destination computer. The destination computer doesn't need to be connected to the domain for domain user profiles to be created. If USMT can't determine a domain, it attempts to apply the settings to a local account. For more information, see [Identify Users](usmt-identify-users.md).
4. In the **Scanning** phase, **LoadState** does the following for each user profile:
1. In the **Scanning** phase, **LoadState** does the following for each user profile:
1. For each component, **LoadState** checks the type of the component. If the current user profile is the system profile and the component type is **System** or **UserAndSystem**, the component is selected for this user. Otherwise, the component is ignored. Alternatively, if the current user profile isn't the system profile and the component type is **User** or **UserAndSystem**, the component is selected for this user. Otherwise, this component is ignored.
> [!NOTE]
> From this point on, **LoadState** does not distinguish between components that migrate operating-system settings, those that migrate application settings, and those that migrate users' files. **LoadState** evaluates all components in the same way.
>
> From this point on, **LoadState** doesn't distinguish between components that migrate operating-system settings, components that migrate application settings, and components that migrate users' files. **LoadState** evaluates all components in the same way.
2. Each component that is selected is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents` (assuming that the user profiles are stored in the `C:\Users` directory).
1. Each component that is selected is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents` (assuming that the user profiles are stored in the `C:\Users` directory).
> [!NOTE]
> **LoadState** ignores the **&lt;detects&gt;** section specified in a component. At this point, all specified components are considered to be detected and are selected for migration.
>
> **LoadState** ignores the **\<detects\>** section specified in a component. At this point, all specified components are considered to be detected and are selected for migration.
3. For each selected component, **LoadState** evaluates the **&lt;rules&gt;** sections. For each **&lt;rules&gt;** section, if the current user profile is the system profile and the context of the **&lt;rules&gt;** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **&lt;rules&gt;** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored.
1. For each selected component, **LoadState** evaluates the **\<rules\>** sections. For each **\<rules\>** section, if the current user profile is the system profile and the context of the **\<rules\>** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **\<rules\>** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored.
4. **LoadState** creates a master list of migration units by processing the various subsections under the **&lt;rules&gt;** section. Each migration unit that is in an **&lt;include&gt;** subsection is migrated as long, as there isn't a more specific rule for it in an **&lt;exclude&gt;** subsection in the same **&lt;rules&gt;** section. For more information about precedence, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
1. **LoadState** creates a central list of migration units by processing the various subsections under the **\<rules\>** section. Each migration unit that is in an **\<include\>** subsection is migrated as long, as there isn't a more specific rule for it in an **\<exclude\>** subsection in the same **\<rules\>** section. For more information about precedence, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
5. **LoadState** evaluates the destination computer-specific subsections, for example, the **&lt;destinationCleanup&gt;** and **&lt;locationModify&gt;** subsections.
1. **LoadState** evaluates the destination computer-specific subsections, for example, the **\<destinationCleanup\>** and **\<locationModify\>** subsections.
6. If the destination computer is running Windows 7, Windows 8, or Windows 10, then the migunits that were collected by **ScanState** using downlevel manifest files are processed by **LoadState** using the corresponding Component Manifest for Windows 7. The downlevel manifest files aren't used during **LoadState**.
1. If the destination computer is running a currently supported version of Windows, then the migunits that were collected by **ScanState** using downlevel manifest files are processed by **LoadState** using the corresponding Component Manifest from the downlevel Windows version. The downlevel manifest files aren't used during **LoadState**.
> [!IMPORTANT]
> It is important to specify the .xml files with the `LoadState.exe` command if you want **LoadState** to use them. Otherwise, any destination-specific rules, such as **&lt;locationModify&gt;**, in these .xml files are ignored, even if the same .xml files were provided when the `ScanState.exe` command ran.
>
> For **LoadState** to use the **.xml** files, it's important to specify them with the `LoadState.exe` command. Otherwise, any destination-specific rules, such as **\<locationModify\>**, in these **.xml** files are ignored, even if the same **.xml** files were provided when the `ScanState.exe` command ran.
5. In the **Apply** phase, **LoadState** writes the migration units that were collected to the various locations on the destination computer. If there are conflicts and there isn't a **&lt;merge&gt;** rule for the object, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally, for example, OriginalFileName(1).OriginalExtension. Some settings, such as fonts, wallpaper, and screen-saver settings, don't take effect until the next time the user logs on. For this reason, you should sign out when the `LoadState.exe` command actions have completed.
1. In the **Apply** phase, **LoadState** writes the migration units that were collected to the various locations on the destination computer. If there are conflicts and there isn't a **\<merge\>** rule for the object, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally, for example, OriginalFileName(1).OriginalExtension. Some settings, such as fonts, wallpaper, and screen-saver settings, don't take effect until the next time the user logs on. For this reason, sign out when the `LoadState.exe` command actions are finished.
## Related articles
[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md)
- [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md).

28
windows/deployment/usmt/usmt-how-to.md
View File

@ -1,34 +1,38 @@
---
title: User State Migration Tool (USMT) How-to articles (Windows 10)
description: Reference the articles in this article to learn how to use User State Migration Tool (USMT) 10.0 to perform specific tasks.
title: User State Migration Tool (USMT) How-to articles
description: Reference the articles in this article to learn how to use User State Migration Tool (USMT) to perform specific tasks.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# User State Migration Tool (USMT) how-to articles
The following table lists articles that describe how to use User State Migration Tool (USMT) 10.0 to perform specific tasks.
The following table lists articles that describe how to use User State Migration Tool (USMT) to perform specific tasks.
## In this section
| Link | Description |
|------ |----------- |
|[Exclude files and settings](usmt-exclude-files-and-settings.md)|Create a custom .xml file to exclude files, file types, folders, or registry settings from your migration.|
|[Exclude files and settings](usmt-exclude-files-and-settings.md)|Create a custom **.xml** file to exclude files, file types, folders, or registry settings from the migration.|
|[Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md)|Recover files from a compressed migration store after installing the operating system.|
|[Include files and settings](usmt-include-files-and-settings.md)|Create a custom .xml file to include files, file types, folders, or registry settings in your migration.|
|[Migrate application settings](migrate-application-settings.md)|Migrate the settings of an application that the MigApp.xml file doesn't include by default.|
|[Include files and settings](usmt-include-files-and-settings.md)|Create a custom **.xml** file to include files, file types, folders, or registry settings in the migration.|
|[Migrate application settings](migrate-application-settings.md)|Migrate the settings of an application that the `MigApp.xml` file doesn't include by default.|
|[Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md)|Migrate Encrypting File System (EFS) certificates by using USMT.|
|[Migrate user accounts](usmt-migrate-user-accounts.md)|Specify the users to include and exclude in your migration.|
|[Reroute files and settings](usmt-reroute-files-and-settings.md)|Create a custom .xml file to reroute files and settings during a migration.|
|[Migrate user accounts](usmt-migrate-user-accounts.md)|Specify the users to include and exclude in the migration.|
|[Reroute files and settings](usmt-reroute-files-and-settings.md)|Create a custom **.xml** file to reroute files and settings during a migration.|
|[Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md)|Determine whether a compressed migration store is intact, or whether it contains corrupt files or a corrupt catalog.|
## Related articles
- [User State Migration Tool (USMT) overview topics](usmt-topics.md)
- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md)
- [User State Migration Toolkit (USMT) reference](usmt-reference.md)
- [User State Migration Tool (USMT) overview topics](usmt-topics.md).
- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md).
- [User State Migration Toolkit (USMT) reference](usmt-reference.md).

26
windows/deployment/usmt/usmt-identify-application-settings.md
View File

@ -1,30 +1,34 @@
---
title: Identify Applications Settings (Windows 10)
description: Identify which applications and settings you want to migrate before using the User State Migration Tool (USMT).
title: Identify Applications Settings
description: Identify which applications and settings need to be migrated before using the User State Migration Tool (USMT).
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Identify applications settings
When planning for your migration, you should identify which applications and settings you want to migrate. For more information about how to create a custom .xml file to migrate the settings of another application, see [Customize USMT XML files](usmt-customize-xml-files.md).
Which applications and settings need to be migrated should be identified when planning a migration. For more information about how to create a custom **.xml** file to migrate the settings of another application, see [Customize USMT XML files](usmt-customize-xml-files.md).
## Applications
First, create and prioritize a list of applications that need to be migrated. It may be helpful to review the application lists and decide which applications will be redeployed and which applications will be retired. Often, what applications are migrated are prioritized based on a combination of how widely the application is used and how complex the application is.
First, create and prioritize a list of applications that need to be migrated. It might be helpful to review the application lists and decide which applications need to be redeployed and which applications need to be retired. Often, how the application is used and how complex the application is determines the priority of what applications are migrated.
Next, identify an application owner to be in charge of each application. Application ownership identification is necessary because the developers won't be experts on all of the applications in the organization. The application owner should have the most experience with an application. The application owner provides insight into how the organization installs, configures, and uses the application.
Next, identify an application owner to be in charge of each application. Application ownership identification is necessary because the developers aren't be experts on all of the applications in the organization. The application owner should have the most experience with an application. The application owner provides insight into how the organization installs, configures, and uses the application.
## Application settings
Next, determine and locate the application settings to be migrated. You can acquire much of the information that you need for this step when you're testing the new applications for compatibility with the new operating system.
Next, determine and locate the application settings to be migrated. Much of the information that is needed for this step can be acquired when testing the new applications for compatibility with the new operating system.
After completing the list of applications to be migrated, review the list, and work with each application owner on a list of settings to be migrated. For each setting, determine whether it needs to be migrated or if the default settings are adequate. Then, determine where the setting is located, for example, in the registry or in an .ini file. Next, consider the following questions to determine what needs to be done to migrate the setting successfully:
After completing the list of applications to be migrated, review the list, and work with each application owner on a list of settings to be migrated. For each setting, determine whether it needs to be migrated or if the default settings are adequate. Then, determine where the setting is located, for example, in the registry or in an **.ini** file. Next, consider the following questions to determine what needs to be done to migrate the setting successfully:
- Is the destination version of the application newer than the source version?
@ -32,9 +36,9 @@ After completing the list of applications to be migrated, review the list, and w
- Do the settings need to be moved or altered?
- Can the first-run process force the application to appear as if it had run already? If so, does this work correctly, or does it break the application?
- Can the first-run process force the application to appear as if it ran already? If so, does this work correctly, or does it break the application?
After answering these questions, create a custom .xml file to migrate settings. Work with the application owner to develop test cases and to determine the file types that need to be migrated for the application.
After answering these questions, create a custom **.xml** file to migrate settings. Work with the application owner to develop test cases and to determine the file types that need to be migrated for the application.
## Locating where settings are stored
@ -42,4 +46,4 @@ See [Migrate application settings](migrate-application-settings.md) and follow t
## Related articles
[Determine what to migrate](usmt-determine-what-to-migrate.md)
- [Determine what to migrate](usmt-determine-what-to-migrate.md).

37
windows/deployment/usmt/usmt-identify-file-types-files-and-folders.md
View File

@ -1,40 +1,45 @@
---
title: Identify File Types, Files, and Folders (Windows 10)
description: Learn how to identify the file types, files, folders, and settings that you want to migrate when you're planning your migration.
title: Identify File Types, Files, and Folders
description: Identify the file types, files, folders, and settings that need to be migrated when planning the migration.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Identify file types, files, and folders
When planning for your migration, if not using MigDocs.xml, you should identify the file types, files, folders, and settings that you want to migrate. First, you should determine the standard file locations on each computer, such as **My Documents** , `C:\Data` , and company-specified locations, such as `\\EngineeringDrafts`. Next, you should determine and locate the non-standard locations. For non-standard locations, consider the following items:
When a migration is planned and `MigDocs.xml` isn't being used, the file types, files, folders, and settings that need to be migrated should be identified. First, the standard file locations on each computer, such as the **Documents** folder, `C:\Data` , and organization-specified locations, such as `\\EngineeringDrafts`, should be determined. Next, non-standard locations should be determined and located. For non-standard locations, consider the following items:
- **File types**. Consider which file types need to be included and excluded from the migration. You can create this list based on common applications used in your organization. Applications normally use specific file name extensions. For example, Microsoft Office Word primarily uses `.doc`, `.docx` and `.dotx` file name extension. However, it also uses other file types, such as templates (`.dot` files), on a less frequent basis.
- **File types**: Consider which file types need to be included and excluded from the migration. This list can be created based on common applications used in the organization. Applications normally use specific file name extensions. For example, Microsoft Office Word primarily uses `.doc`, `.docx` and `.dotx` file name extension. However, it also uses other file types, such as templates (`.dot` files), on a less frequent basis.
- **Excluded locations**. Consider the locations on the computer that should be excluded from the migration (for example, `%WINDIR%` and **Program Files**).
- **Excluded locations**: Consider the locations on the computer that should be excluded from the migration (for example, `%WINDIR%` and **Program Files**).
- **New locations**. Decide where files should be migrated to on the destination computer, such as **My Documents**, a designated folder, or a folder matching the files' name and location on the source computer. For example, you might have shared data on source machine or you might wish to clean up documents outside the user profiles on the source system. Identify any data that needs to be redirected to a new location in the apply phase. Redirection can be accomplished with location modify rules.
- **New locations**: Decide where files should be migrated to on the destination computer, such as the **Documents** folder, a designated folder, or a folder matching the files' name and location on the source computer. For example, shared data might exist on the source machine or documents outside the user profiles on the source system might need to be cleaned up. Identify any data that needs to be redirected to a new location in the Apply phase. Redirection can be accomplished with location modify rules.
Once you've verified which files and file types that the end users work with regularly, you'll need to locate them. Files may be saved to a single folder or scattered across a drive. A good starting point for finding files types to include is to look at the registered file types on the computer.
Once which files and file types that the end users work with regularly is verified, locate the files and file types. Files might be saved to a single folder or scattered across a drive. A good starting point for finding files types to include is to look at the registered file types on the computer.
To find the registered file types on a computer running Windows 7, Windows 8, Windows 10, or Windows 11:
To find the registered file types on a computer running a currently supported version of Windows:
1. Open **Control Panel**
2. Make sure **View by:** is set to **Category** and then select **Programs**.
1. Right-click the **Start Menu** and select **Settings**.
3. Select **Default Programs**
1. When the **Settings** window opens, select **Apps**.
4. select **Associate a file type or protocol with a program**.
1. Select **Default apps**.
5. On this screen, the registered file types are displayed.
1. Scroll down and then select **Choose defaults by file type** or **Choose default apps by file type**.
For more information about how to change the file types, files, and folders that are migrated when you specify the MigUser.xml file, see [User State Migration Tool (USMT) how-to topics](usmt-how-to.md).
1. In the window that opens, the registered file types are displayed.
For more information about how to change the file types, files, and folders that are migrated when the `MigUser.xml` file is specified, see [User State Migration Tool (USMT) how-to articles](usmt-how-to.md).
## Related articles
[Determine what to migrate](usmt-determine-what-to-migrate.md)
- [Determine what to migrate](usmt-determine-what-to-migrate.md).

45
windows/deployment/usmt/usmt-identify-operating-system-settings.md
View File

@ -1,44 +1,65 @@
---
title: Identify Operating System Settings (Windows 10)
description: Identify which system settings you want to migrate, then use the User State Migration Tool (USMT) to select settings and keep the default values for all others.
title: Identify Operating System Settings
description: Identify which system settings need to be migrated. The User State Migration Tool (USMT) can then be used to select settings and keep the default values for all others.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Identify operating system settings
When planning for your migration, you should identify which operating system settings you want to migrate and to what extent you want to create a new standard environment on each of the computers. User State Migration Tool (USMT) 10.0 enables you to migrate select settings and keep the default values for all others. The operating system settings include the following parameters:
When the migration is being planned, which operating system settings need to be migrated should be identified. Additionally, to what extent a new standard environment should be created on each of the computers should also be identified. User State Migration Tool (USMT) enables migrating select settings and keep the default values for all others. The operating system settings include the following parameters:
- **Appearance**
The appearance factor includes items such as wallpaper, colors, sounds, and the location of the taskbar.
The appearance factor includes items such as wallpaper, colors, sounds, and the location of the taskbar.
- **Action**
The action factor includes items such as the key-repeat rate, whether double-clicking a folder opens it in a new window or the same window, and whether you need to single-click or double-click an item to open it.
The action factor includes items such as:
- The key-repeat rate.
- Whether double-clicking a folder opens it in a new window or the same window.
- Whether single-clicking or double-clicking an item opens it.
- **Internet**
The Internet factor includes the settings that let you connect to the Internet and control how your browser operates. The settings include items such as your home page URL, favorites, bookmarks, cookies, security settings, dial-up connections, and proxy settings.
The Internet factor includes the settings needed to connect to the Internet and controls how the browser operates. The settings include items such as the home page URL, favorites, bookmarks, cookies, security settings, and proxy settings. These settings might not be supported in all browsers.
- **Mail**
The mail factor includes the information that you need to connect to your mail server, your signature file, views, mail rules, local mail, and contacts.
The mail factor includes the information needed to connect the mail server, the signature file, views, mail rules, local mail, and contacts. These settings might not be supported in all email applications.
To help you decide which settings to migrate, you should consider any previous migration experiences and the results of any surveys and tests that you've conducted. You should also consider the number of help-desk calls related to operating-system settings that you've had in the past, and are able to handle in the future. Also decide how much of the new operating-system functionality you want to take advantage of.
To help determine which settings to migrate, consider any previous migration experiences and the results of any conducted surveys and tests. Also consider the number of help-desk calls related to operating-system settings from the past, and are able to handle in the future. Also decide how much of the new operating-system functionality needs to be taken advantage of.
You should migrate any settings that users need to get their jobs done, those settings that make the work environment comfortable, and those settings that will reduce help-desk calls after the migration. Although it's easy to dismiss migrating user preferences, you should consider the factor of users spending a significant amount of time restoring items such as wallpaper, screen savers, and other customizable user-interface features. Most users don't remember how these settings were applied. Although these items aren't critical to migration success, migrating these items increases user productivity and overall satisfaction of the migration process.
Settings that should be migrated include:
- Settings that allow users need to get their jobs done.
- Settings that make the work environment comfortable.
- Settings that will reduce help-desk calls after the migration.
Although it's easy to dismiss migrating user preferences, the factor should be considered of users spending time restoring items such as:
- Wallpaper.
- Screen savers.
- Other customizable user-interface features.
Most users don't remember how these settings were applied. Although these items aren't critical to migration success, migrating these items increases user productivity and overall satisfaction of the migration process.
> [!NOTE]
> For more information about how to change the operating-system settings that are migrated, see [User State Migration Tool (USMT) how-to topics](usmt-how-to.md).
>
> For more information about how to change the operating-system settings that are migrated, see [User State Migration Tool (USMT) how-to articles](usmt-how-to.md).
For information about the operating-system settings that USMT migrates, see [What does USMT migrate?](usmt-what-does-usmt-migrate.md)
## Related articles
[Determine What to Migrate](usmt-determine-what-to-migrate.md)
- [Determine What to Migrate](usmt-determine-what-to-migrate.md).

41
windows/deployment/usmt/usmt-identify-users.md
View File

@ -1,6 +1,7 @@
---
title: Identify Users (Windows 10)
description: Learn how to identify users you plan to migrate, and how to migrate local accounts and domain accounts.
title: Identify Users
description: Learn how to identify users that need to be migrated, and how to migrate local accounts and domain accounts.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
@ -8,25 +9,29 @@ author: frankroj
ms.topic: article
ms.localizationpriority: medium
ms.technology: itpro-deploy
ms.date: 11/01/2022
ms.date: 01/09/2024
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Identify users
It's important to carefully consider how you plan to migrate users. By default, all users are migrated by User State Migration Tool (USMT) 5.0. You must specify which users to include by using the command line. You can't specify users in the .xml files. For instructions on how to migrate users, see [Migrate user accounts](usmt-migrate-user-accounts.md).
It's important to carefully consider and plan how users are migrated. By default, User State Migration Tool (USMT) migrates all users. Which users to include must be specified by using the command line. Users can't be specified in the **.xml** files. For instructions on how to migrate users, see [Migrate user accounts](usmt-migrate-user-accounts.md).
## Migrating local accounts
Before migrating local accounts, be aware of the following items:
- **You must explicitly specify that local accounts that are not on the destination computer should be migrated**. If you're migrating local accounts and the local account doesn't exist on the destination computer, you must use the `/lac` option when using the `LoadState.exe` command. If the `/lac` option isn't specified, no local user accounts will be migrated.
- **Local accounts that aren't on the destination computer must be explicitly specified if they should be migrated.** If migrating local accounts and the local account doesn't exist on the destination computer, the `/lac` option must be specified when using the `LoadState.exe` command. If the `/lac` option isn't specified, no local user accounts are migrated.
- **Consider whether to enable user accounts that are new to the destination computer.** The `/lae` option enables the account that was created with the `/lac` option. However, if you create a disabled local account by using only the `/lac` option, a local administrator must enable the account on the destination computer.
- **Consider whether to enable user accounts that are new to the destination computer.** The `/lae` option enables the account that was created with the `/lac` option. However, if a disabled local account is created by using only the `/lac` option, a local administrator must enable the account on the destination computer.
- **Be careful when specifying a password for local accounts.** If you create the local account with a blank password, anyone could sign in that account on the destination computer. If you create the local account with a password, the password is available to anyone with access to the USMT command-line tools.
- **Be careful when specifying a password for local accounts.** If the local account is created with a blank password, anyone could sign in that account on the destination computer. If the local account is created with a password, the password is available to anyone with access to the USMT command-line tools.
> [!NOTE]
> If there are multiple users on a computer, and you specify a password with the `/lac` option, all migrated users will have the same password.
>
> If there are multiple users on a computer, and a password is specified with the `/lac` option, all migrated users have the same password.
## Migrating domain accounts
@ -36,22 +41,24 @@ The source and destination computers don't need to be connected to the domain fo
USMT provides several options to migrate multiple users on a single computer. The following command-line options specify which users to migrate.
- **Specifying users.** You can specify which users to migrate with the `/all`, `/ui`, `/uel`, and `/ue` options with both the **ScanState** and **LoadState** command-line tools.
- **Specifying users.** Which users to migrate can be specified with the `/all`, `/ui`, `/uel`, and `/ue` options with both the **ScanState** and **LoadState** command-line tools.
> [!IMPORTANT]
> The `/uel` option excludes users based on the **LastModified** date of the `Ntuser.dat` file. The `/uel` option is not valid in offline migrations.
>
> The `/uel` option excludes users based on the **LastModified** date of the `Ntuser.dat` file. The `/uel` option isn't valid in offline migrations.
- **Moving users to another domain.** You can move user accounts to another domain using the `/md` option with the **LoadState** command-line tool.
- **Moving users to another domain.** User accounts can be moved to another domain using the `/md` option with the **LoadState** command-line tool.
- **Creating local accounts.** You can create and enable local accounts using the `/lac` and `/lae` options with the **LoadState** command-line tool.
- **Creating local accounts.** Local accounts can be created and enabled using the `/lac` and `/lae` options with the **LoadState** command-line tool.
- **Renaming user accounts.** You can rename user accounts using the `/mu` option.
- **Renaming user accounts.** User accounts can be renamed using the `/mu` option.
> [!NOTE]
>By default, if a user name is not specified in any of the command-line options, the user will be migrated.
>
> By default, if a user name isn't specified in any of the command-line options, the user is migrated.
## Related articles
- [Determine what to migrate](usmt-determine-what-to-migrate.md)
- [ScanState syntax](usmt-scanstate-syntax.md)
- [LoadState syntax](usmt-loadstate-syntax.md)
- [Determine what to migrate](usmt-determine-what-to-migrate.md).
- [ScanState syntax](usmt-scanstate-syntax.md).
- [LoadState syntax](usmt-loadstate-syntax.md).

43
windows/deployment/usmt/usmt-include-files-and-settings.md
View File

@ -1,22 +1,26 @@
---
title: Include Files and Settings (Windows 10)
description: Specify the migration .xml files you want, then use the User State Migration Tool (USMT) 10.0 to migrate the settings and components specified.
title: Include Files and Settings
description: Specify the migration .xml files that are needed, then use the User State Migration Tool (USMT) to migrate the settings and components specified.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Include Files and Settings
When you specify the migration .xml files, User State Migration Tool (USMT) 10.0 migrates the settings and components specified in [What does USMT migrate?](usmt-what-does-usmt-migrate.md). To include additional files and settings, we recommend that you create a custom .xml file, and then include this file when using both the `ScanState.exe` and `LoadState.exe` commands. By creating a custom .xml file, you can keep your changes separate from the default .xml files, which makes it easier to track your modifications.
When the migration **.xml** files are specified, User State Migration Tool (USMT) migrates the settings and components specified in [What does USMT migrate?](usmt-what-does-usmt-migrate.md). To include additional files and settings, Microsoft recommends creating a custom **.xml** file, and then include this file when using both the `ScanState.exe` and `LoadState.exe` commands. Creating a custom **.xml** file allows changes to be kept separate from the default **.xml** files. Creating a custom **.xml** file makes it easier to track modifications.
## Migrate a single registry key
The following .xml file migrates a single registry key.
The following **.xml** file migrates a single registry key.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -41,7 +45,7 @@ The following examples show how to migrate a folder from a specific drive, and f
### Migrate a folder from a specific drive
- **Including subfolders.** The following .xml file migrates all files and subfolders from `C:\EngineeringDrafts` to the destination computer.
- **Including subfolders.** The following **.xml** file migrates all files and subfolders from `C:\EngineeringDrafts` to the destination computer.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -60,7 +64,7 @@ The following examples show how to migrate a folder from a specific drive, and f
</migration>
```
- **Excluding subfolders.** The following .xml file migrates all files from `C:\EngineeringDrafts`, but it doesn't migrate any subfolders within `C:\EngineeringDrafts`.
- **Excluding subfolders.** The following **.xml** file migrates all files from `C:\EngineeringDrafts`, but it doesn't migrate any subfolders within `C:\EngineeringDrafts`.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -81,7 +85,7 @@ The following examples show how to migrate a folder from a specific drive, and f
### Migrate a folder from any location
The following .xml file migrates all files and subfolders of the `EngineeringDrafts` folder from any drive on the computer. If multiple folders exist with the same name, then all files with this name are migrated.
The following **.xml** file migrates all files and subfolders of the `EngineeringDrafts` folder from any drive on the computer. If multiple folders exist with the same name, then all files with this name are migrated.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -101,7 +105,7 @@ The following .xml file migrates all files and subfolders of the `EngineeringDra
</migration>
```
The following .xml file migrates all files and subfolders of the `EngineeringDrafts` folder from any location on the `C:\` drive. If multiple folders exist with the same name, they're all migrated.
The following **.xml** file migrates all files and subfolders of the `EngineeringDrafts` folder from any location on the `C:\` drive. If multiple folders exist with the same name, they're all migrated.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -123,12 +127,12 @@ The following .xml file migrates all files and subfolders of the `EngineeringDra
## Migrate a file type into a specific folder
The following .xml file migrates `.mp3` files located in the specified drives on the source computer into the `C:\Music` folder on the destination computer.
The following **.xml** file migrates `.mp3` files located in the specified drives on the source computer into the `C:\Music` folder on the destination computer.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
<component type="Documents" context="System">
<displayName>All .mp3 files to My Documents</displayName>
<displayName>All .mp3 files to the Documents folder</displayName>
<role role="Data">
<rules>
<include>
@ -152,7 +156,7 @@ The following .xml file migrates `.mp3` files located in the specified drives on
The following examples show how to migrate a file from a specific folder, and how to migrate a file from any location.
- **To migrate a file from a folder.** The following .xml file migrates only the `Sample.doc` file from `C:\EngineeringDrafts` on the source computer to the destination computer.
- **To migrate a file from a folder.** The following **.xml** file migrates only the `Sample.doc` file from `C:\EngineeringDrafts` on the source computer to the destination computer.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -171,13 +175,13 @@ The following examples show how to migrate a file from a specific folder, and ho
</migration>
```
- **To migrate a file from any location.** To migrate the `Sample.doc` file from any location on the `C:\` drive, use the **&lt;pattern&gt;** element, as the following example shows. If multiple files exist with the same name on the `C:\` drive, all of files with this name are migrated.
- **To migrate a file from any location.** To migrate the `Sample.doc` file from any location on the `C:\` drive, use the **\<pattern\>** element, as the following example shows. If multiple files exist with the same name on the `C:\` drive, all of files with this name are migrated.
```xml
<pattern type="File"> C:\* [Sample.doc] </pattern>
```
To migrate the Sample.doc file from any drive on the computer, use &lt;script&gt; as the following example shows. If multiple files exist with the same name, all files with this name are migrated.
To migrate the Sample.doc file from any drive on the computer, use \<script\> as the following example shows. If multiple files exist with the same name, all files with this name are migrated.
```xml
<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>
@ -185,10 +189,7 @@ The following examples show how to migrate a file from a specific folder, and ho
## Related articles
[Customize USMT XML files](usmt-customize-xml-files.md)
[Custom XML examples](usmt-custom-xml-examples.md)
[Conflicts and precedence](usmt-conflicts-and-precedence.md)
[USMT XML reference](usmt-xml-reference.md)
- [Customize USMT XML files](usmt-customize-xml-files.md).
- [Custom XML examples](usmt-custom-xml-examples.md).
- [Conflicts and precedence](usmt-conflicts-and-precedence.md).
- [USMT XML reference](usmt-xml-reference.md).

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

@ -1,45 +1,45 @@
---
title: LoadState Syntax (Windows 10)
description: Learn about the syntax and usage of the command-line options available when you use the LoadState command.
title: LoadState Syntax
description: Learn about the syntax and usage of the command-line options available when using the LoadState command.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# LoadState syntax
The `LoadState.exe` command is used with the User State Migration Tool (USMT) 10.0 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.
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, we recommend 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 had 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.
- **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:
@ -48,58 +48,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, you'll need to specify the encryption key 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 will 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. We recommend that you use a compressed store during your 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 your .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 your migration. If no path is specified, USMT will use 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 "XML files" 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 will be 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 will fail 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* will be 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 will continue 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 won't fit on the computer, the `LoadState.exe` command will log an error and continue with the migration. Without the `/c` option, the `LoadState.exe` command will exit on the first error. You can use the new &lt;**ErrorControl**&gt; 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 your environment. In addition, the `/genconfig` option now generates a sample &lt;**ErrorControl**&gt; 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/>While restoring the user state, the `/r` option won'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 you specify a user name that contains spaces, you'll need to surround it 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 will be 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 has signed into another computer, that sign-in instance isn't considered by USMT. <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 have logged on, or whose accounts have been otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose accounts have been modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who have logged on or whose accounts have been 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 you specify a user name that contains spaces, you'll need to surround it 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* may contain the asterisk () wildcard character. <br/><br/>You can specify this option more than once. You may want to specify multiple `/md` options if you're consolidating users across multiple domains to a single domain. For example, you could specify the following to consolidate the users from the Corporate and FarNorth domains into the Fabrikam domain: `/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 will appear to complete successfully, without an error or warning. However, in this case, users won't be moved to *NewDomain* but will remain in their original domain. For example, if you misspell **contoso** and you instead specify **/md:contso:fabrikam**, the users will 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/>Specifies that if a user account is a local (non-domain) account, and it doesn't exist on the destination computer, USMT will create the account on the destination computer but it will be 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 won't be 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 because it's provided in plain text and can be obtained by anyone with access to the computer that is running the `LoadState.exe` command. <br/>Also, if the computer has multiple users, all migrated users will 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 |
|--- |--- |
@ -112,52 +112,53 @@ 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 will be included in the migration. For example, if you specify `/ui:contoso\* /ue:contoso\user1`, then User1 will be migrated, because the `/ui` option takes precedence over the `/ue` option.
**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 has logged on within the specified time period set by the `/uel` option, that user's profile will be migrated even if they're excluded by using the `/ue` option. For example, if you specify `/ue:contoso\user1 /uel:14`, the User1 will be migrated if they've 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, you'll need to 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 has a ✔️, 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 | |
| **/l** | | | | |
| **/progress** | | | X | |
| **/r** | | | X | |
| **/w** | | | X | |
| **/c** | | | X | |
| **/p** | | | X | N/A |
| **/all** | | | X | |
| **/ui** | | | X | X |
| **/ue** | | | X | X |
| **/uel** | | | X | X |
| **/genconfig** | | | N/A | |
| **/config** | | | X | |
| *StorePath* | | | | |
| **/md** | | | | |
| **/mu** | | | | |
| **/lae** | | | | |
| **/lac** | | | | |
| **/i** | ✔️ | ✔️ | ✔️ | ✔️ |
| **/v** | ✔️ | ✔️ | ✔️ | ✔️ |
| **/nocompress** | ✔️ | N/A | ❌ | ✔️ |
| **/key** | ❌ | ✔️ | ❌ | ✔️ |
| **/decrypt** | Required* | ❌ | ❌ | ✔️ |
| **/keyfile** | N/A | ✔️ | ❌ | ✔️ |
| **/l** | ✔️ | ✔️ | ✔️ | ✔️ |
| **/progress** | ✔️ | ✔️ | ❌ | ✔️ |
| **/r** | ✔️ | ✔️ | ❌ | ✔️ |
| **/w** | ✔️ | ✔️ | ❌ | ✔️ |
| **/c** | ✔️ | ✔️ | ❌ | ✔️ |
| **/p** | ✔️ | ✔️ | ❌ | N/A |
| **/all** | ✔️ | ✔️ | ❌ | ✔️ |
| **/ui** | ✔️ | ✔️ | ❌ | ❌ |
| **/ue** | ✔️ | ✔️ | ❌ | ❌ |
| **/uel** | ✔️ | ✔️ | ❌ | ❌ |
| **/genconfig** | ✔️ | ✔️ | N/A | ✔️ |
| **/config** | ✔️ | ✔️ | ❌ | ✔️ |
| *StorePath* | ✔️ | ✔️ | ✔️ | ✔️ |
| **/md** | ✔️ | ✔️ | ✔️ | ✔️ |
| **/mu** | ✔️ | ✔️ | ✔️ | ✔️ |
| **/lae** | ✔️ | ✔️ | ✔️ | ✔️ |
| **/lac** | ✔️ | ✔️ | ✔️ | ✔️ |
> [!NOTE]
> You must specify either the `/key` or `/keyfile` option with the `/encrypt` option.
>
> Either the `/key` or `/keyfile` option must be specified with the `/decrypt` option.
## Related articles
[XML elements library](usmt-xml-elements-library.md)
- [XML elements library](usmt-xml-elements-library.md).

153
windows/deployment/usmt/usmt-log-files.md
View File

@ -1,28 +1,25 @@
---
title: Log Files (Windows 10)
description: Learn how to use User State Migration Tool (USMT) 10.0 logs to monitor your migration and to troubleshoot errors and failed migrations.
title: USMT Log Files
description: Learn how to use User State Migration Tool (USMT) logs to monitor the migration and to troubleshoot errors and failed migrations.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# USMT log files
You can use User State Migration Tool (USMT) 10.0 logs to monitor your migration and to troubleshoot errors and failed migrations. This article describes the available command-line options to enable USMT logs, and new XML elements that configure which types of errors are fatal and should halt the migration, which types are non-fatal and should be skipped so that the migration can continue.
User State Migration Tool (USMT) logs can be used to monitor the migration and to troubleshoot errors and failed migrations. This article describes the available command-line options to enable USMT logs. It also describes new XML elements that can be used to configure:
[Log command-line options](#log-command-line-options)
[ScanState and LoadState logs](#scanstate-and-loadstate-logs)
[Progress log](#progress-log)
[List files log](#list-files-log)
[Diagnostic log](#diagnostic-log)
- Which types of errors are fatal and should halt the migration.
- Which types are non-fatal and should be skipped so that the migration can continue.
## Log command-line options
@ -37,21 +34,22 @@ The following table describes each command-line option related to logs, and it p
|Set the environment variable **MIG_ENABLE_DIAG** to a path to an XML file.|`USMTDiag.xml`|The diagnostic log contains detailed system environment information, user environment information, and information about the migration units (migunits) being gathered and their contents.|
> [!NOTE]
> You cannot store any of the log files in *StorePath*. If you do, the log will be overwritten when USMT is run.
>
> The log files can't be stored in *StorePath*. If the log files are stored in *StorePath*, the log files are overwritten when USMT runs.
## ScanState and LoadState logs
**ScanState** and **LoadState** logs are text files that are create when you run the **ScanState** and **LoadState** tools. You can use these logs to help monitor your migration. The content of the log depends on the command-line options that you use and the verbosity level that you specify. For more information about verbosity levels, see [Monitoring options](usmt-scanstate-syntax.md#monitoring-options) in [ScanState syntax](usmt-scanstate-syntax.md).
**ScanState** and **LoadState** logs are text files that are created when the **ScanState** and **LoadState** tools run. These logs can be used to help monitor the migration. The content of the log depends on the command-line options that are used and the verbosity level that is specified. For more information about verbosity levels, see [Monitoring options](usmt-scanstate-syntax.md#monitoring-options) in [ScanState syntax](usmt-scanstate-syntax.md).
## Progress log
You can create a progress log using the `/progress` option. External tools, such as Microsoft System Center Operations Manager, can parse the progress log to update your monitoring systems. The first three fields in each line are fixed as follows:
A progress log can be created using the `/progress` option. External tools, such as Microsoft System Center Operations Manager, can parse the progress log to update the monitoring systems. The first three fields in each line are fixed as follows:
- **Date:** Date, in the format of *day* *shortNameOfTheMonth* *year*. For example: 08 Jun 2006.
- **Date:** Date, in the format of *day* *shortNameOfTheMonth* *year*. For example: 08 Jun 2023.
- **Local time:** Time, in the format of *hrs*:*minutes*:*seconds* (using a 24-hour clock). For example: 13:49:13.
- **Migration time:** Duration of time that USMT was run, in the format of *hrs:minutes:seconds*. For example: 00:00:10.
- **Migration time:** Duration of time that USMT was run, in the format of *hrs:minutes:seconds*. For example: 00:00:20.
The remaining fields are key/value pairs as indicated in the following table.
@ -62,15 +60,15 @@ The remaining fields are key/value pairs as indicated in the following table.
| *computerName* | The name of the source or destination computer on which USMT was run. |
| *commandLine* | The full command used to run USMT. |
| *PHASE* | Reports that a new phase in the migration is starting. This key can be one of the following values:<ul><li>Initializing</li><li>Scanning</li><li>Collecting</li><li>Saving</li><li>Estimating</li><li>Applying</li></ul> |
| *detectedUser* | <ul><li>For the **ScanState** tool, this key are the users USMT detected on the source computer that can be migrated.</li><li>For the **LoadState** tool, this key are the users USMT detected in the store that can be migrated.</li></ul> |
| *detectedUser* | <ul><li>For the **ScanState** tool, this key is the users USMT detected on the source computer that can be migrated.</li><li>For the **LoadState** tool, this key is the users USMT detected in the store that can be migrated.</li></ul> |
| *includedInMigration* | Defines whether the user profile/component is included for migration. Valid values are **Yes** or **No**. |
| *forUser* | Specifies either of the following values:<ul><li>The user state being migrated.</li><li>*This Computer*, meaning files and settings that aren't associated with a user.</li></ul> |
| *detectedComponent* | Specifies a component detected by USMT.<ul><li>For *ScanState*, this key is a component or application that is installed on the source computer.</li><li>For **LoadState**, this key is a component or application that was detected in the store.</li></ul> |
| *totalSizeInMBToTransfer* | Total size of the files and settings to migrate in megabytes (MB). |
| *totalPercentageCompleted* | Total percentage of the migration that has been completed by either **ScanState** or **LoadState**. |
| *totalPercentageCompleted* | Total percentage of the migration that is completed by either **ScanState** or **LoadState**. |
| *collectingUser* | Specifies which user **ScanState** is collecting files and settings for. |
| *totalMinutesRemaining* | Time estimate, in minutes, for the migration to complete. |
| *error* | Type of non-fatal error that occurred. This key can be one of the following values:<ul><li>**UnableToCopy**: Unable to copy to store because the disk on which the store is located is full.</li><li>**UnableToOpen**: Unable to open the file for migration because the file is opened in non-shared mode by another application or service.</li><li>**UnableToCopyCatalog**: Unable to copy because the store is corrupted.</li><li>**UnableToAccessDevice**: Unable to access the device.</li><li>**UnableToApply**: Unable to apply the setting to the destination computer.</li></ul> |
| *error* | Type of non-fatal error that occurred. This key can be one of the following values:<ul><li>**UnableToCopy**: Unable to copy to store because the disk on which the store is located is full.</li><li>**UnableToOpen**: Unable to open the file for migration because another application or service has the file open in non-shared mode.</li><li>**UnableToCopyCatalog**: Unable to copy because the store is corrupted.</li><li>**UnableToAccessDevice**: Unable to access the device.</li><li>**UnableToApply**: Unable to apply the setting to the destination computer.</li></ul> |
| *objectName* | The name of the file or setting that caused the non-fatal error. |
| *action* | Action taken by USMT for the non-fatal error. The values are:<ul><li>**Ignore**: Non-fatal error ignored and the migration continued because the **/c** option was specified on the command line.</li><li>**Abort**: Stopped the migration because the **/c** option wasn't specified.</li></ul> |
| *errorCode* | The errorCode or return value. |
@ -83,45 +81,45 @@ The List files log (`Listfiles.txt`) provides a list of the files that were migr
## Diagnostic log
You can obtain the diagnostic log by setting the environment variable **MIG_ENABLE_DIAG** to a path to an XML file.
The diagnostic log can be obtained by setting the environment variable **MIG_ENABLE_DIAG** to a path to an XML file.
The diagnostic log contains:
- Detailed system environment information
- Detailed system environment information.
- Detailed user environment information
- Detailed user environment information.
- Information about the migration units (migunits) being gathered and their contents
- Information about the migration units (migunits) being gathered and their contents.
## Using the Diagnostic Log
The diagnostic log is essentially a report of all the migration units (migunits) included in the migration. A migunit is a collection of data that is identified by the component it's associated with in the XML files. The migration store is made up of all the migunits in the migration. The diagnostic log can be used to verify which migunits were included in the migration and can be used for troubleshooting while authoring migration XML files.
The diagnostic log is essentially a report of all the migration units (migunits) included in the migration. A migunit is a collection of data. In the XML files, the component identifies the migunit that the migunit is associated with. The migration store is made up of all the migunits in the migration. The diagnostic log can be used to verify which migunits were included in the migration and can be used for troubleshooting while authoring migration XML files.
The following examples describe common scenarios in which you can use the diagnostic log.
The following examples describe common scenarios in which the diagnostic log can be used.
**Why is this file not migrating when I authored an "include" rule for it?**
Let's imagine that we have the following directory structure and that we want the **data** directory to be included in the migration along with the **New Text Document.txt** file in the **New Folder**. The directory of `C:\data` contains:
```console
01/21/2009 10:08 PM <DIR> .
01/21/2009 10:08 PM <DIR> ..
01/21/2009 10:08 PM <DIR> New Folder
01/21/2009 09:19 PM 13 test (1).txt
01/21/2009 09:19 PM 13 test.txt
```cmd
12/21/2023 01:08 PM <DIR> .
12/21/2023 01:08 PM <DIR> ..
12/21/2023 01:08 PM <DIR> New Folder
12/21/2023 01:19 PM 13 test (1).txt
12/21/2023 01:19 PM 13 test.txt
2 File(s) 26 bytes
```
The directory of `C:\data\New Folder` contains:
```console
01/21/2009 10:08 PM <DIR> .
01/21/2009 10:08 PM <DIR> ..
01/21/2009 10:08 PM 0 New Text Document.txt
```cmd
12/21/2023 01:08 PM <DIR> .
12/21/2023 01:08 PM <DIR> ..
12/21/2023 01:08 PM 0 New Text Document.txt
1 File(s) 0 bytes
```
To migrate these files you author the following migration XML:
To migrate these files the following migration XML is authored:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -143,28 +141,28 @@ To migrate these files you author the following migration XML:
</migration>
```
However, upon testing the migration you notice that the **New Text Document.txt** file isn't included in the migration. To troubleshoot this failure, the migration can be repeated with the environment variable **MIG_ENABLE_DIAG** set such that the diagnostic log is generated. Upon searching the diagnostic log for the component **DATA1**, the following XML section is discovered:
However, upon testing the migration, the **New Text Document.txt** file is noticed that it wasn't included in the migration. To troubleshoot this failure, the migration can be repeated with the environment variable **MIG_ENABLE_DIAG** set such that the diagnostic log is generated. Searching the diagnostic log for the component **DATA1** reveals the following XML section:
```xml
<MigUnitList>
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data [*]"/>
</Patterns>
</MigUnit>
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data [*]"/>
</Patterns>
</MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.txt]" SimObj="false" Success="true"/>
</MigUnit>
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.txt]" SimObj="false" Success="true"/>
</MigUnit>
</Perform>
```
Analysis of this XML section reveals the migunit that was created when the migration rule was processed. The **&lt;Perform&gt;** section details the actual files that were scheduled for gathering and the result of the gathering operation. The **New Text Document.txt** file doesn't appear in this section, which confirms that the migration rule wasn't correctly authored.
Analysis of this XML section reveals the migunit that was created when the migration rule was processed. The **\<Perform\>** section details the actual files that were scheduled for gathering and the result of the gathering operation. The **New Text Document.txt** file doesn't appear in this section, which confirms that the migration rule wasn't correctly authored.
An analysis of the [XML elements library](usmt-xml-elements-library.md) reference article reveals that the [**&lt;pattern&gt;**](usmt-xml-elements-library.md#pattern) tag needs to be modified as follows:
An analysis of the [XML elements library](usmt-xml-elements-library.md) reference article reveals that the [**\<pattern\>**](usmt-xml-elements-library.md#pattern) tag needs to be modified as follows:
```xml
<pattern type="File">c:\data\* [*]</pattern>
@ -174,14 +172,14 @@ When the migration is performed again with the modified tag, the diagnostic log
```xml
<MigUnitList>
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data\* [*]"/>
</Patterns>
</MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.txt]" SimObj="false" Success="true"/>
@ -191,33 +189,33 @@ When the migration is performed again with the modified tag, the diagnostic log
</Perform>
```
This diagnostic log confirms that the modified **&lt;pattern&gt;** value enables the migration of the file.
This diagnostic log confirms that the modified **\<pattern\>** value enables the migration of the file.
**Why is this file migrating when I authored an exclude rule excluding it?**
In this scenario, you have the following directory structure and you want all files in the **Data** directory to migrate, except for text files. The `C:\Data` folder contains:
In this scenario, the following directory structure exists and all files in the **Data** directory should migrate, except for text files. The `C:\Data` folder contains:
```console
```cmd
Directory of C:\Data
01/21/2009 10:08 PM <DIR> .
01/21/2009 10:08 PM <DIR> ..
01/21/2009 10:08 PM <DIR> New Folder
01/21/2009 09:19 PM 13 test (1).txt
01/21/2009 09:19 PM 13 test.txt
12/21/2023 01:08 PM <DIR> .
12/21/2023 01:08 PM <DIR> ..
12/21/2023 01:08 PM <DIR> New Folder
12/21/2023 01:19 PM 13 test (1).txt
12/21/2023 01:19 PM 13 test.txt
2 File(s) 26 bytes
```
The `C:\Data\New Folder\` contains:
```console
01/21/2009 10:08 PM <DIR> .
01/21/2009 10:08 PM <DIR> ..
01/21/2009 10:08 PM 0 New Text Document.txt
```cmd
12/21/2023 01:08 PM <DIR> .
12/21/2023 01:08 PM <DIR> ..
12/21/2023 01:08 PM 0 New Text Document.txt
1 File(s) 0 bytes
```
You author the following migration XML:
The following migration XML is authored:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -245,11 +243,11 @@ You author the following migration XML:
</component>
```
However, upon testing the migration you notice that all the text files are still included in the migration. In order to troubleshoot this issue, the migration can be performed with the environment variable **MIG_ENABLE_DIAG** set so that the diagnostic log is generated. Upon searching the diagnostic log for the component **DATA1**, the following XML section is discovered:
However, upon testing the migration, all the text files are noticed that they're still included in the migration. In order to troubleshoot this issue, the migration can be performed with the environment variable **MIG_ENABLE_DIAG** set so that the diagnostic log is generated. Searching the diagnostic log for the component **DATA1** reveals the following XML section:
```xml
<MigUnitList>
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data\* [*]"/>
</Patterns>
@ -259,7 +257,7 @@ However, upon testing the migration you notice that all the text files are still
</MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.docx]" SimObj="false" Success="true"/>
@ -271,7 +269,7 @@ However, upon testing the migration you notice that all the text files are still
</Perform>
```
Upon reviewing the diagnostic log, you confirm that the files are still migrating, and that it's a problem with the authored migration XML rule. You author an update to the migration XML script as follows:
When the diagnostic log is reviewed, the files are still migrating is confirmed, and that it's a problem with the authored migration XML rule. An update is authored to the migration XML script as follows:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -302,11 +300,11 @@ Upon reviewing the diagnostic log, you confirm that the files are still migratin
</migration>
```
Your revised migration XML script excludes the files from migrating, as confirmed in the diagnostic log:
The revised migration XML script excludes the files from migrating, as confirmed in the diagnostic log:
```xml
<MigUnitList>
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data\* [*]"/>
</Patterns>
@ -316,7 +314,7 @@ Your revised migration XML script excludes the files from migrating, as confirme
</MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.docx]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data\New Folder" SimObj="false" Success="true"/>
@ -327,9 +325,6 @@ Your revised migration XML script excludes the files from migrating, as confirme
## Related articles
[XML elements library](usmt-xml-elements-library.md)
[ScanState syntax](usmt-scanstate-syntax.md)
[LoadState syntax](usmt-loadstate-syntax.md)
- [XML elements library](usmt-xml-elements-library.md).
- [ScanState syntax](usmt-scanstate-syntax.md).
- [LoadState syntax](usmt-loadstate-syntax.md).

26
windows/deployment/usmt/usmt-migrate-efs-files-and-certificates.md
View File

@ -1,13 +1,17 @@
---
title: Migrate EFS Files and Certificates (Windows 10)
title: Migrate EFS Files and Certificates
description: Learn how to migrate Encrypting File System (EFS) certificates. Also, learn where to find information about how to identify file types, files, and folders.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Migrate EFS files and certificates
@ -16,7 +20,7 @@ This article describes how to migrate Encrypting File System (EFS) certificates.
## To migrate EFS files and certificates
Encrypting File System (EFS) certificates will be migrated automatically. However, by default, the User State Migration Tool (USMT) 10.0 fails if an encrypted file is found unless you specify an `/efs` option. Therefore when a device has EFS encrypted files, you must specify the `/efs` option with any one of the following parameters:
Encrypting File System (EFS) certificates are migrated automatically. However, by default, the User State Migration Tool (USMT) fails if an encrypted file is found unless the `/efs` option is specified. Therefore when a device has EFS encrypted files, the `/efs` option must be specified with any one of the following parameters:
- `abort`
- `skip`
@ -24,23 +28,23 @@ Encrypting File System (EFS) certificates will be migrated automatically. Howeve
- `copyraw`
- `hardlink`
when running the `ScanState.exe` command to migrate the encrypted files. Then, when you run the `LoadState.exe` command on the destination computer, the encrypted file and the EFS certificate will be automatically migrated.
when running the `ScanState.exe` command to migrate the encrypted files. Then, when the `LoadState.exe` command is run on the destination computer, the encrypted file and the EFS certificate are automatically migrated.
> [!NOTE]
> The `/efs` options are not used with the `LoadState.exe` command.
>
> The `/efs` options aren't used with the `LoadState.exe` command.
Before using the **ScanState** tool for a migration that includes encrypted files and EFS certificates, you must ensure that all files in an encrypted folder are encrypted as well or remove the encryption attribute from folders that contain unencrypted files. If the encryption attribute has been removed from a file but not from the parent folder, the file will be encrypted during the migration using the credentials of the account used to run the **LoadState** tool.
Before using the **ScanState** tool for a migration that includes encrypted files and EFS certificates, all files in an encrypted folder must also be encrypted. Otherwise, remove the encryption attribute from folders that contain unencrypted files. If the encryption attribute is removed from a file but not from the parent folder, the file is encrypted during the migration using the credentials of the account used to run the **LoadState** tool.
You can run the [Cipher.exe](/windows-server/administration/windows-commands/cipher) tool at a Windows command prompt to review and change encryption settings on files and folders. For example, to remove encryption from a folder, at a command prompt enter:
The [Cipher.exe](/windows-server/administration/windows-commands/cipher) tool can be run at a Windows command prompt to review and change encryption settings on files and folders. For example, to remove encryption from a folder, at a command prompt enter:
```cmd
cipher.exe /D /S:<PATH>
```
where *&lt;Path&gt;* is the full path of the topmost parent directory where the encryption attribute is set.
where *\<Path\>* is the full path of the topmost parent directory where the encryption attribute is set.
## Related articles
[What does USMT migrate?](usmt-what-does-usmt-migrate.md)
[Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md)
- [What does USMT migrate?](usmt-what-does-usmt-migrate.md).
- [Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md).

43
windows/deployment/usmt/usmt-migrate-user-accounts.md
View File

@ -1,18 +1,22 @@
---
title: Migrate User Accounts (Windows 10)
title: Migrate User Accounts
description: Learn how to migrate user accounts and how to specify which users to include and exclude by using the User options on the command line.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Migrate User Accounts
By default, all users are migrated. The only way to specify which users to include and exclude is on the command line by using the User options. You can't specify users in the migration XML files or by using the `Config.xml` file.
By default, all users are migrated. The only way to specify which users to include and exclude is on the command line by using the [ScanState User options](usmt-scanstate-syntax.md#user-options) and the [LoadState User options](usmt-loadstate-syntax.md#user-options). Users can't be specified in the migration XML files or by using the `Config.xml` file.
## To migrate all user accounts and user settings
@ -20,30 +24,31 @@ Links to detailed explanations of commands are available in the [Related article
1. Sign into the source computer as an administrator.
2. Enter the following `ScanState.exe` command line in a command prompt window:
1. Enter the following `ScanState.exe` command line in a command prompt window:
```cmd
ScanState.exe \\server\share\migration\mystore /i:MigDocs.xml /i:MigApp.xml /o
````
3. Sign into the destination computer as an administrator.
1. Sign into the destination computer as an administrator.
4. Enter one of the following `LoadState.exe ` command lines in a command prompt window:
1. Enter one of the following `LoadState.exe` command lines in a command prompt window:
- If you're migrating domain accounts, enter:
- If migrating domain accounts, enter:
```cmd
LoadState.exe \\server\share\migration\mystore /i:MigDocs.xml /i:MigApp.xml
```
- If you're migrating local accounts along with domain accounts, enter:
- If migrating local accounts along with domain accounts, enter:
```cmd
LoadState.exe \\server\share\migration\mystore /i:MigDocs.xml /i:MigApp.xml /lac /lae
```
> [!NOTE]
> You do not have to specify the `/lae` option, which enables the account that was created with the `/lac` option. Instead, you can create a disabled local account by specifying only the `/lac` option, and then a local administrator needs to enable the account on the destination computer.
>
> The `/lae` option doesn't need to be specified, which enables the account that was created with the `/lac` option. Instead, create a disabled local account by specifying only the `/lac` option, and then a local administrator needs to enable the account on the destination computer.
## To migrate two domain accounts (User1 and User2)
@ -51,15 +56,15 @@ Links to detailed explanations of commands are available in the [Related article
1. Sign into the source computer as an administrator.
2. Enter the following `ScanState.exe` command line in a command prompt window:
1. Enter the following `ScanState.exe` command line in a command prompt window:
```cmd
ScanState.exe \\server\share\migration\mystore /ue:*\* /ui:contoso\user1 /ui:fabrikam\user2 /i:MigDocs.xml /i:MigApp.xml /o
```
3. Sign into the destination computer as an administrator.
1. Sign into the destination computer as an administrator.
4. Enter the following `LoadState.exe ` command line in a command prompt window:
1. Enter the following `LoadState.exe` command line in a command prompt window:
```cmd
LoadState.exe \\server\share\migration\mystore /i:MigDocs.xml /i:MigApp.xml
@ -71,15 +76,15 @@ Links to detailed explanations of commands are available in the [Related article
1. Sign into the source computer as an administrator.
2. Enter the following `ScanState.exe` command line in a command prompt window:
1. Enter the following `ScanState.exe` command line in a command prompt window:
```cmd
ScanState.exe \\server\share\migration\mystore /ue:*\* /ui:contoso\user1 /ui:contoso\user2 /i:MigDocs.xml /i:MigApp.xml /o
```
3. Sign into the destination computer as an administrator.
1. Sign into the destination computer as an administrator.
4. Enter the following `LoadState.exe ` command line in a command prompt window:
1. Enter the following `LoadState.exe` command line in a command prompt window:
```cmd
LoadState.exe \\server\share\migration\mystore /mu:contoso\user1:fabrikam\user1 /mu:contoso\user2:fabrikam\user2 /i:MigDocs.xml /i:MigApp.xml
@ -87,8 +92,6 @@ Links to detailed explanations of commands are available in the [Related article
## Related articles
[Identify users](usmt-identify-users.md)
[ScanState syntax](usmt-scanstate-syntax.md)
[LoadState syntax](usmt-loadstate-syntax.md)
- [Identify users](usmt-identify-users.md).
- [ScanState syntax](usmt-scanstate-syntax.md).
- [LoadState syntax](usmt-loadstate-syntax.md).

17
windows/deployment/usmt/usmt-migration-store-encryption.md
View File

@ -1,24 +1,28 @@
---
title: Migration Store Encryption (Windows 10)
title: Migration Store Encryption
description: Learn how the User State Migration Tool (USMT) enables support for stronger encryption algorithms, called Advanced Encryption Standard (AES).
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Migration store encryption
This article discusses User State Migration Tool (USMT) 10.0 options for migration store encryption to protect the integrity of user data during a migration.
This article discusses User State Migration Tool (USMT) options for migration store encryption to protect the integrity of user data during a migration.
## USMT encryption options
USMT enables support for stronger encryption algorithms, called Advanced Encryption Standard (AES), in several bit-level options. AES is a National Institute of Standards and Technology (NIST) specification for the encryption of electronic data.
The encryption algorithm you choose must be specified for both the `ScanState.exe` and the `LoadState.exe` commands, so that these commands can create or read the store during encryption and decryption. The new encryption algorithms can be specified on the `ScanState.exe` and the `LoadState.exe` command lines by using the `/encrypt`:*encryptionstrength* and the `/decrypt`:*encryptionstrength* command-line options. All of the encryption application programming interfaces (APIs) used by USMT are available in Windows 7, Windows 8, and Windows 10 operating systems. However, export restrictions might limit the set of algorithms that are available to computers in certain locales. You can use the `UsmtUtils.exe` file to determine which encryption algorithms are available to the computers' locales before you begin the migration.
The chosen encryption algorithm must be specified for both the `ScanState.exe` and the `LoadState.exe` commands, so that these commands can create or read the store during encryption and decryption. The new encryption algorithms can be specified on the `ScanState.exe` and the `LoadState.exe` command lines by using the `/encrypt`:*encryption_strength* and the `/decrypt`:*encryption_strength* command-line options. All of the encryption application programming interfaces (APIs) used by USMT are available in currently supported versions of Windows. However, export restrictions might limit the set of algorithms that are available to computers in certain locales. The `UsmtUtils.exe` file can be used to determine which encryption algorithms are available to the computers' locales before the migration begins.
The following table describes the command-line encryption options in USMT.
@ -28,8 +32,9 @@ The following table describes the command-line encryption options in USMT.
|*LoadState*|**/decrypt**<*AES, AES_128, AES_192, AES_256, 3DES, 3DES_112*>|This option and argument specify that the store must be decrypted and which algorithm to use. When the algorithm argument isn't provided, the **LoadState** tool employs the **3DES** algorithm.|
> [!IMPORTANT]
> Some encryption algorithms may not be available on your systems. You can verify which algorithms are available by running the `UsmtUtils.exe` command with the `/ec` option. For more information, see [UsmtUtils syntax](usmt-utilities.md).
>
> Some encryption algorithms might not be available on some systems. Which algorithms are available can be verified by running the `UsmtUtils.exe` command with the `/ec` option. For more information, see [UsmtUtils syntax](usmt-utilities.md).
## Related articles
[Plan your migration](usmt-plan-your-migration.md)
- [Plan the migration](usmt-plan-your-migration.md).

24
windows/deployment/usmt/usmt-overview.md
View File

@ -1,27 +1,33 @@
---
title: User State Migration Tool (USMT) overview
description: Learn about using User State Migration Tool (USMT) 10.0 to streamline and simplify user state migration during large deployments of Windows operating systems.
description: Learn about using User State Migration Tool (USMT) to streamline and simplify user state migration during large deployments of Windows operating systems.
ms.prod: windows-client
ms.technology: itpro-deploy
author: frankroj
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: overview
ms.collection:
- highpri
- tier2
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# User State Migration Tool (USMT) overview
You can use User State Migration Tool (USMT) 10.0 to streamline and simplify user state migration during large deployments of Windows operating systems. USMT captures user accounts, user files, operating system settings, and application settings, and then migrates them to a new Windows installation. You can use USMT for both PC replacement and PC refresh migrations. For more information, see [Common migration scenarios](usmt-common-migration-scenarios.md).
The User State Migration Tool (USMT) can be used to streamline and simplify user state migration during large deployments of Windows operating systems. USMT captures user accounts, user files, operating system settings, and application settings, and then migrates them to a new Windows installation. USMT can be used for both PC replacement and PC refresh migrations. For more information, see [Common migration scenarios](usmt-common-migration-scenarios.md).
USMT enables you to do the following actions:
USMT enables the following actions:
- Configure your migration according to your business needs by using the migration rule (.xml) files to control exactly which files and settings are migrated and how they're migrated. For more information about how to modify these files, see [USMT XML reference](usmt-xml-reference.md).
- Fit your customized migration into your automated deployment process by using the **ScanState** and **LoadState** tools, which control collecting and restoring the user files and settings. For more information, see [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md).
- Perform offline migrations. You can run migrations offline by using the ScanState command in Windows Preinstallation Environment (WinPE) or you can perform migrations from previous installations of Windows contained in Windows.old directories. For more information about migration types, see [Choose a migration store Type](usmt-choose-migration-store-type.md) and [Offline migration reference](offline-migration-reference.md).
- Configure the migration according to the organization's business needs by using the migration rule (.xml) files to control exactly which files and settings are migrated and how they're migrated. For more information about how to modify these files, see [USMT XML reference](usmt-xml-reference.md).
- Fit the customized migration into the automated deployment process by using the **ScanState** and **LoadState** tools, which control collecting and restoring the user files and settings. For more information, see [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md).
- Perform offline migrations. Migrations can be run offline by using the **ScanState** command in Windows Preinstallation Environment (WinPE) or migrations can be performed from previous installations of Windows contained in **Windows.old** directories. For more information about migration types, see [Choose a migration store Type](usmt-choose-migration-store-type.md) and [Offline migration reference](offline-migration-reference.md).
## Benefits
@ -36,7 +42,7 @@ USMT provides the following benefits to businesses that are deploying Windows op
## Limitations
USMT is intended for administrators who are performing large-scale automated deployments. If you're only migrating the user states of a few computers, you can use [PCmover Express](https://go.microsoft.com/fwlink/?linkid=620915). PCmover isn't a free utility. PCmover Express is a tool created by Microsoft's partner, Laplink.
USMT is intended for administrators who are performing large-scale automated deployments. If the user states of only a few computers are being migrated, [PCmover Express](https://go.microsoft.com/fwlink/?linkid=620915) can be used. PCmover isn't a free utility. PCmover Express is a tool created by Microsoft's partner, Laplink.
There are some scenarios in which the use of USMT isn't recommended. These scenarios include:
@ -45,4 +51,4 @@ There are some scenarios in which the use of USMT isn't recommended. These scena
## Related articles
- [User State Migration Tool (USMT) technical reference](usmt-technical-reference.md)
- [User State Migration Tool (USMT) technical reference](usmt-technical-reference.md).

26
windows/deployment/usmt/usmt-plan-your-migration.md
View File

@ -1,33 +1,37 @@
---
title: Plan Your Migration (Windows 10)
description: Learn how to your plan your migration carefully so your migration can proceed smoothly and so that you reduce the risk of migration failure.
title: Plan The Migration
description: Learn how to plan the migration carefully so the migration can proceed smoothly and so that the risk of migration failure is reduced.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Plan your migration
# Plan the migration
Before you use the User State Migration Tool (USMT) 10.0 to perform your migration, we recommend that you plan your migration carefully. Planning can help your migration proceed smoothly and can reduce the risk of migration failure.
Before using the User State Migration Tool (USMT) to perform a migration, Microsoft recommends that to plan the migration carefully. Planning can help the migration proceed smoothly and can reduce the risk of migration failure.
In migration planning, both organizations and individuals must first identify what to migrate, including user settings, applications and application settings, and personal data files and folders. Identifying the applications to migrate is especially important so that you can avoid capturing data about applications that may be phased out.
In migration planning, both organizations and individuals must first identify what to migrate, including user settings, applications and application settings, and personal data files and folders. Identifying the applications to migrate is especially important to avoid capturing data about applications that might be phased out.
One of the most important requirements for migrating settings and data is restoring only the information that the destination computer requires. Although the data that you capture on the source computer may be more comprehensive than the restoration data for backup purposes, restoring data or settings for applications that you won't install on the destination system is redundant. Restoring data or settings for applications that aren't installed can also introduce instability in a newly deployed computer.
One of the most important requirements for migrating settings and data is restoring only the information that the destination computer requires. Although the data that is captured on the source computer might be more comprehensive than the restoration data for backup purposes, restoring data or settings for applications that aren't installed on the destination system is redundant. Restoring data or settings for applications that aren't installed can also introduce instability in a newly deployed computer.
## In this section
| Link | Description |
|--- |--- |
|[Common migration scenarios](usmt-common-migration-scenarios.md)|Determine whether you'll perform a refresh migration or a replace migration.|
|[Common migration scenarios](usmt-common-migration-scenarios.md)|Determine whether to perform a refresh migration or a replace migration.|
|[What does USMT migrate?](usmt-what-does-usmt-migrate.md)|Learn which applications, user data, and operating system components USMT migrates.|
|[Choose a migration store type](usmt-choose-migration-store-type.md)|Choose an uncompressed, compressed, or hard-link migration store.|
|[Determine what to migrate](usmt-determine-what-to-migrate.md)|Identify user accounts, application settings, operating system settings, and files that you want to migrate inside your organization.|
|[Test your migration](usmt-test-your-migration.md)|Test your migration before you deploy Windows to all users.|
|[Determine what to migrate](usmt-determine-what-to-migrate.md)|Identify user accounts, application settings, operating system settings, and files that need to be migrated inside the organization.|
|[Test the migration](usmt-test-your-migration.md)|Test the migration before deploying Windows to all users.|
## Related articles
[USMT XML reference](usmt-xml-reference.md)
- [USMT XML reference](usmt-xml-reference.md).

40
windows/deployment/usmt/usmt-recognized-environment-variables.md
View File

@ -1,25 +1,29 @@
---
title: Recognized environment variables
description: Learn how to use environment variables to identify folders that may be different on different computers.
description: Learn how to use environment variables to identify folders that can be different on different computers.
ms.prod: windows-client
ms.technology: itpro-deploy
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: conceptual
ms.collection:
- highpri
- tier2
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Recognized environment variables
When using the XML files `MigDocs.xml`, `MigApp.xml`, and `MigUser.xml`, you can use environment variables to identify folders that may be different on different computers. Constant special item ID list (CSIDL) values provide a way to identify folders that applications use frequently but may not have the same name or location on any given computer. For example, the **Documents** folder may be `C:\Users\<Username>\My Documents` on one computer and `C:\Documents and Settings\<username>\My Documents` on another. You can use the asterisk (\*) wildcard character in `MigUser.xml`, `MigApp.xml` and `MigDoc.xml` files. However, you can't use the asterisk (\*) wildcard characters in the `Config.xml` file.
When the XML files `MigDocs.xml`, `MigApp.xml`, and `MigUser.xml` are used, the environment variables can be used to identify folders that can be different on different computers. Constant special item ID list (CSIDL) values provide a way to identify folders that applications use frequently but could have different names or locations on any given computer. For example, the **Documents** folder could be `C:\Users\<Username>\Documents` on one computer and `C:\Users\<Username>\My Documents` on another. The asterisk (\*) wildcard character can be used in the `MigUser.xml`, `MigApp.xml` and `MigDoc.xml` files. However, the asterisk (\*) wildcard character can't be used in the `Config.xml` file.
## Variables that are processed for the operating system and in the context of each user
You can use these variables within sections in the .xml files with `context=UserAndSystem`, `context=User`, and `context=System`.
These variables can be used within sections in the **.xml** files with `context=UserAndSystem`, `context=User`, and `context=System`.
|Variable|Explanation|
|--- |--- |
@ -40,8 +44,8 @@ You can use these variables within sections in the .xml files with `context=User
|*CSIDL_COMMON_STARTUP*|The file-system directory that contains the programs that appear in the Startup folder for all users. A typical path is `C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup`.|
|*CSIDL_COMMON_TEMPLATES*|The file-system directory that contains the templates that are available to all users. A typical path is `C:\ProgramData\Microsoft\Windows\Templates`.|
|*CSIDL_COMMON_VIDEO*|The file-system directory that serves as a repository for video files common to all users. A typical path is `C:\Users\Public\Videos`.|
|*CSIDL_DEFAULT_APPDATA*|Refers to the Appdata folder inside `%DEFAULTUSERPROFILE%`.|
|C*SIDL_DEFAULT_LOCAL_APPDATA*|Refers to the local Appdata folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_APPDATA*|Refers to the `Appdata` folder inside `%DEFAULTUSERPROFILE%`.|
|C*SIDL_DEFAULT_LOCAL_APPDATA*|Refers to the local `Appdata` folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_COOKIES*|Refers to the Cookies folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_CONTACTS*|Refers to the Contacts folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_DESKTOP*|Refers to the Desktop folder inside `%DEFAULTUSERPROFILE%`.|
@ -50,10 +54,10 @@ You can use these variables within sections in the .xml files with `context=User
|*CSIDL_DEFAULT_HISTORY*|Refers to the History folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_INTERNET_CACHE*|Refers to the Internet Cache folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_PERSONAL*|Refers to the Personal folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_MYDOCUMENTS*|Refers to the My Documents folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_MYPICTURES*|Refers to the My Pictures folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_MYMUSIC*|Refers to the My Music folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_MYVIDEO*|Refers to the My Videos folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_MYDOCUMENTS*|Refers to the Documents folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_MYPICTURES*|Refers to the Pictures folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_MYMUSIC*|Refers to the Music folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_MYVIDEO*|Refers to the Videos folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_RECENT*|Refers to the Recent folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_SENDTO*|Refers to the Send To folder inside `%DEFAULTUSERPROFILE%`.|
|*CSIDL_DEFAULT_STARTMENU*|Refers to the Start Menu folder inside `%DEFAULTUSERPROFILE%`.|
@ -83,12 +87,12 @@ You can use these variables within sections in the .xml files with `context=User
## Variables that are recognized only in the user context
You can use these variables in the .xml files within sections with `context=User` and `context=UserAndSystem`.
These variables can be used in the **.xml** files within sections with `context=User` and `context=UserAndSystem`.
|Variable|Explanation|
|--- |--- |
|*APPDATA*|Same as **CSIDL_APPDATA**.|
|*CSIDL_ADMINTOOLS*|The file-system directory that is used to store administrative tools for an individual user. The Microsoft® Management Console (MMC) saves customized consoles to this directory, which roams with the user profile.|
|*CSIDL_ADMINTOOLS*|The file-system directory that is used to store administrative tools for an individual user. The Microsoft Management Console (MMC) saves customized consoles to this directory, which roams with the user profile.|
|*CSIDL_ALTSTARTUP*|The file-system directory that corresponds to the user's non-localized Startup program group.|
|*CSIDL_APPDATA*|The file-system directory that serves as a common repository for application-specific data. A typical path is `C:\Users\<username>\AppData\Roaming`.|
|*CSIDL_BITBUCKET*|The virtual folder that contains the objects in the user's Recycle Bin.|
@ -99,20 +103,20 @@ You can use these variables in the .xml files within sections with `context=User
|*CSIDL_COOKIES*|The file-system directory that serves as a common repository for Internet cookies. A typical path is `C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Cookies`.|
|*CSIDL_DESKTOP*|The virtual folder representing the Windows desktop.|
|*CSIDL_DESKTOPDIRECTORY*|The file-system directory used to physically store file objects on the desktop, which shouldn't be confused with the desktop folder itself. A typical path is `C:\Users\<username>\Desktop`.|
|*CSIDL_DRIVES*|The virtual folder representing My Computer that contains everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.|
|*CSIDL_DRIVES*|The virtual folder representing **This PC** that contains everything on the local computer: storage devices, printers, and Control Panel. The folder could also contain mapped network drives.|
|*CSIDL_FAVORITES*|The file-system directory that serves as a common repository for the user's favorites. A typical path is `C:\Users\<username>\Favorites`.|
|*CSIDL_HISTORY*|The file-system directory that serves as a common repository for Internet history items.|
|*CSIDL_INTERNET*|A virtual folder for Internet Explorer.|
|*CSIDL_INTERNET_CACHE*|The file-system directory that serves as a common repository for temporary Internet files. A typical path is `C:\Users\<username>\AppData\Local\Microsoft\Windows\Temporary Internet Files`|
|*CSIDL_LOCAL_APPDATA*|The file-system directory that serves as a data repository for local, non-roaming applications. A typical path is `C:\Users\<username>\AppData\Local`.|
|*CSIDL_MYDOCUMENTS*|The virtual folder representing My Documents.A typical path is `C:\Users\<username>\Documents`.|
|*CSIDL_MYDOCUMENTS*|The virtual folder representing the **Documents** folder.A typical path is `C:\Users\<username>\Documents`.|
|*CSIDL_MYMUSIC*|The file-system directory that serves as a common repository for music files. A typical path is `C:\Users\<username>\Music`.|
|*CSIDL_MYPICTURES*|The file-system directory that serves as a common repository for image files. A typical path is `C:\Users\<username>\Pictures`.|
|*CSIDL_MYVIDEO*|The file-system directory that serves as a common repository for video files. A typical path is `C:\Users\<username>\Videos`.|
|*CSIDL_NETHOOD*|A file-system directory that contains the link objects that may exist in the My Network Places virtual folder. It isn't the same as *CSIDL_NETWORK*, which represents the network namespace root. A typical path is `C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Network Shortcuts`.|
|*CSIDL_NETWORK*|A virtual folder representing My Network Places, the root of the network namespace hierarchy.|
|*CSIDL_PERSONAL*|The virtual folder representing the My Documents desktop item. This value is equivalent to **CSIDL_MYDOCUMENTS**. A typical path is `C:\Documents and Settings\<username>\My Documents`.|
|*CSIDL_PLAYLISTS*|The virtual folder used to store play albums, typically `C:\Users\<username>\My Music\Playlists`.|
|*CSIDL_NETHOOD*|A file-system directory that contains the link objects that could exist in the **Network** virtual folder. It isn't the same as *CSIDL_NETWORK*, which represents the network namespace root. A typical path is `C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Network Shortcuts`.|
|*CSIDL_NETWORK*|A virtual folder representing the **Network** desktop item, the root of the network namespace hierarchy.|
|*CSIDL_PERSONAL*|The virtual folder representing the **\<User\>** desktop item. This value is equivalent to **CSIDL_MYDOCUMENTS**. A typical path is `C:\User\<username>\Documents`.|
|*CSIDL_PLAYLISTS*|The virtual folder used to store play albums, typically `C:\Users\<username>\Music\Playlists`.|
|*CSIDL_PRINTERS*|The virtual folder that contains installed printers.|
|*CSIDL_PRINTHOOD*|The file-system directory that contains the link objects that can exist in the Printers virtual folder. A typical path is `C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Printer Shortcuts`.|
|*CSIDL_PROFILE*|The user's profile folder. A typical path is `C:\Users\<username>`.|

20
windows/deployment/usmt/usmt-reference.md
View File

@ -1,13 +1,17 @@
---
title: User State Migration Toolkit (USMT) Reference (Windows 10)
title: User State Migration Toolkit (USMT) Reference
description: Use this User State Migration Toolkit (USMT) article to learn details about USMT, like operating system, hardware, and software requirements, and user prerequisites.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# User State Migration Toolkit (USMT) reference
@ -18,16 +22,14 @@ ms.technology: itpro-deploy
|--- |--- |
|[USMT requirements](usmt-requirements.md)|Describes operating system, hardware, and software requirements, and user prerequisites.|
|[USMT best practices](usmt-best-practices.md)|Discusses general and security-related best practices when using USMT.|
|[How USMT works](usmt-how-it-works.md)|Learn about the processes behind the ScanState and LoadState tools.|
|[Plan your migration](usmt-plan-your-migration.md)|Choose what to migrate and the best migration scenario for your enterprise.|
|[How USMT works](usmt-how-it-works.md)|Learn about the processes behind the **ScanState** and **LoadState** tools.|
|[Plan the migration](usmt-plan-your-migration.md)|Choose what to migrate and the best migration scenario for the organization.|
|[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md)|Explore command-line options for the ScanState, LoadState, and UsmtUtils tools.|
|[USMT XML reference](usmt-xml-reference.md)|Learn about customizing a migration with XML files.|
|[Offline Migration reference](offline-migration-reference.md)|Find requirements, best practices, and other considerations for performing a migration offline.|
## Related articles
[User State Migration Tool (USMT) overview topics](usmt-topics.md)
[User State Migration Tool (USMT) how-to topics](usmt-how-to.md)
[User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md)
- [User State Migration Tool (USMT) overview articles](usmt-topics.md).
- [User State Migration Tool (USMT) how-to articles](usmt-how-to.md).
- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md).

66
windows/deployment/usmt/usmt-requirements.md
View File

@ -1,59 +1,73 @@
---
title: USMT Requirements (Windows 10)
title: USMT Requirements
description: While the User State Migration Tool (USMT) doesn't have many requirements, these tips and tricks can help smooth the migration process.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/18/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# USMT requirements
## Supported operating systems
The User State Migration Tool (USMT) 10.0 doesn't have any explicit RAM or CPU speed requirements for either the source or destination computers. If your computer complies with the system requirements of the operating system, it also complies with the requirements for USMT. You need an intermediate store location large enough to hold all of the migrated data and settings, and the same amount of hard disk space on the destination computer for the migrated files and settings.
The User State Migration Tool (USMT) doesn't have any explicit RAM or CPU speed requirements for either the source or destination computers. If the computer complies with the system requirements of the operating system, it also complies with the requirements for USMT. An intermediate store location large enough to hold all of the migrated data and settings is needed. The same amount of hard disk space is also needed on the destination computer for the migrated files and settings.
The following table lists the operating systems supported in USMT.
|Operating Systems|ScanState (source computer)|LoadState (destination computer)|
| Operating<br>Systems | ScanState<br>(Source<br>Device)| LoadState<br>(Destination<br>Device)|
|--- |--- |--- |
|32-bit versions of Windows 7|✔️|✔️|
|64-bit versions of Windows 7|✔️|✔️|
|32-bit versions of Windows 8|✔️|✔️|
|64-bit versions of Windows 8|✔️|✔️|
|32-bit versions of Windows 10|✔️|✔️|
|64-bit versions of Windows 10|✔️|✔️|
|Windows 7|✔️|❌|
|Windows 8|✔️|❌|
|Windows 10|✔️|✔️|
|Windows 11|✔️|✔️|
> [!NOTE]
> You can migrate a 32-bit operating system to a 64-bit operating system. However, you cannot migrate a 64-bit operating system to a 32-bit operating system.
>
> - 32-bit operating system can be migrated to a 64-bit operating system. However, a 64-bit operating system can't be migrated to a 32-bit operating system.
>
> - Gathering data from a source device using **ScanState** for a version of Windows that is out of support is supported. However, restoring data to a destination device using **LoadState** to a version of Windows that is out of support isn't supported.
## Unsupported scenarios
- USMT doesn't support any of the Windows Server® operating systems.
- USMT for Windows 10 shouldn't be used for migrating between previous versions of Windows. USMT for Windows 10 is only meant to migrate to Windows 10 or between Windows 10 versions. For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)).
- USMT doesn't support any of the Windows Server operating systems.
- USMT doesn't support Microsoft Entra joined devices as either a source or destination device.
- USMT might work with Microsoft Entra hybrid joined devices, but it's not a tested scenario so therefore unsupported.
- USMT doesn't support migrating settings for Microsoft Store apps.
- USMT shouldn't be used for migrating between previous versions of Windows. USMT is only meant to:
- Migrate to a currently supported version of Windows
- Migrate between currently supported versions of Windows, assuming the version of Windows being migrated to is newer or the same as the previous version of Windows being migrated from.
For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)).
## Windows PE
- **Must use latest version of Windows PE.** For example, to migrate to Windows 10, you'll need Windows PE 5.1. For more info, see [What's New in Windows PE](/windows-hardware/manufacture/desktop/whats-new-in-windows-pe-s14).
- **Must use latest version of Windows PE.** For more info, see [What's New in Windows PE](/windows-hardware/manufacture/desktop/whats-new-in-windows-pe-s14).
## Credentials
- **Run as administrator**
When manually running the **ScanState** and **LoadState** tools on Windows 7, Windows 8, or Windows 10 you must run them from an elevated command prompt to ensure that all specified users are migrated. If you don't run USMT from an elevated prompt, only the user profile that is logged on will be included in the migration.
- **Run as administrator.**
When the **ScanState** and **LoadState** tools are run, they must be run from an elevated command prompt to ensure that all specified users are migrated. If USMT isn't run from an elevated prompt, only the user profile that is logged on is included in the migration.
To open an elevated command prompt:
1. Select **Start**.
2. Enter `cmd` in the search function.
3. Depending on the OS you're using, **cmd** or **Command Prompt** is displayed.
4. Right-click **cmd** or **Command Prompt**, and then select **Run as administrator**.
5. If the current user isn't already an administrator, you'll be prompted to enter administrator credentials.
1. Enter `cmd` in the search function.
1. **cmd** or **Command Prompt** is displayed.
1. Right-click **cmd** or **Command Prompt**, and then select **Run as administrator**.
1. If the current user isn't already an administrator, it prompts to enter administrator credentials.
> [!IMPORTANT]
> You must run USMT using an account with full administrative permissions, including the following privileges:
>
> USMT must run using an account with full administrative permissions, including the following privileges:
>
> - SeBackupPrivilege (Back up files and directories)
> - SeDebugPrivilege (Debug programs)
@ -63,9 +77,9 @@ To open an elevated command prompt:
## Config.xml
### Specify the `/c` option and &lt;ErrorControl&gt; settings in the `Config.xml` file
### Specify the `/c` option and \<ErrorControl\> settings in the `Config.xml` file
USMT will fail if it can't migrate a file or setting, unless you specify the `/c` option. When you specify the `/c` option, USMT logs an error each time it encounters a file that is in use that didn't migrate, but the migration won't be interrupted. In USMT, you can specify in the `Config.xml` file, which types of errors should allow the migration to continue, and which should cause the migration to fail. For more information about error reporting, and the **&lt;ErrorControl&gt;** element, see [Config.xml file](usmt-configxml-file.md#errorcontrol), [Log files](usmt-log-files.md), and [XML elements library](usmt-xml-elements-library.md).
USMT fails if it can't migrate a file or setting, unless the `/c` option is specified. When the `/c` option is specified, USMT logs an error each time it encounters a file that is in use that didn't migrate, but the migration isn't be interrupted. In USMT, which types of errors should allow the migration to continue and which should cause the migration to fail can be specified in the `Config.xml` file. For more information about error reporting, and the **\<ErrorControl\>** element, see [Config.xml file](usmt-configxml-file.md#errorcontrol), [Log files](usmt-log-files.md), and [XML elements library](usmt-xml-elements-library.md).
## LoadState
@ -88,6 +102,6 @@ This documentation assumes that IT professionals using USMT understand command-l
## Related articles
- [Plan your migration](usmt-plan-your-migration.md)
- [Estimate migration store size](usmt-estimate-migration-store-size.md)
- [User State Migration Tool (USMT) overview topics](usmt-topics.md)
- [Plan the migration](usmt-plan-your-migration.md).
- [Estimate migration store size](usmt-estimate-migration-store-size.md).
- [User State Migration Tool (USMT) overview articles](usmt-topics.md).

28
windows/deployment/usmt/usmt-reroute-files-and-settings.md
View File

@ -1,22 +1,26 @@
---
title: Reroute Files and Settings (Windows 10)
title: Reroute Files and Settings
description: Learn how to create a custom .xml file and specify this file name on both the ScanState and LoadState command lines to reroute files and settings.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Reroute Files and Settings
To reroute files and settings, create a custom .xml file and specify the .xml file name on both the `ScanState.exe` and `LoadState.exe` command-lines. Th custom .xml file enables you to keep your changes separate from the default .xml files, so that it's easier to track your modifications.
To reroute files and settings, create a custom **.xml** file and specify the **.xml** file name on both the `ScanState.exe` and `LoadState.exe` command-lines. The custom **.xml** file enables keeping changes separate from the default **.xml** files, so that it's easier to track modifications.
## Reroute a folder
The following custom .xml file migrates the directories and files from `C:\EngineeringDrafts` into the **My Documents** folder of every user. **%CSIDL_PERSONAL%** is the virtual folder representing the **My Documents** desktop item, which is equivalent to **CSIDL_MYDOCUMENTS**.
The following custom **.xml** file migrates the directories and files from `C:\EngineeringDrafts` into the **Documents** folder of every user. **%CSIDL_PERSONAL%** is the virtual folder representing the **\<User\>** desktop item, which is equivalent to **CSIDL_MYDOCUMENTS**.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -44,12 +48,12 @@ The following custom .xml file migrates the directories and files from `C:\Engin
## Reroute a specific file type
The following custom .xml file reroutes .mp3 files located in the fixed drives on the source computer into the `C:\Music` folder on the destination computer.
The following custom **.xml** file reroutes **.mp3** files located in the fixed drives on the source computer into the `C:\Music` folder on the destination computer.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
<component type="Documents" context="System">
<displayName>All .mp3 files to My Documents</displayName>
<displayName>All .mp3 files to the Documents folder</displayName>
<role role="Data">
<rules>
<include>
@ -71,12 +75,12 @@ The following custom .xml file reroutes .mp3 files located in the fixed drives o
## Reroute a specific file
The following custom .xml file migrates the `Sample.doc` file from `C:\EngineeringDrafts` into the **My Documents** folder of every user. **%CSIDL_PERSONAL%** is the virtual folder representing the **My Documents** desktop item, which is equivalent to **CSIDL_MYDOCUMENTS**.
The following custom **.xml** file migrates the `Sample.doc` file from `C:\EngineeringDrafts` into the **Documents** folder of every user. **%CSIDL_PERSONAL%** is the virtual folder representing the **\<User\>** desktop item, which is equivalent to **CSIDL_MYDOCUMENTS**.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
<component type="Documents" context="User">
<displayName>Sample.doc into My Documents</displayName>
<displayName>Sample.doc into the Documents folder</displayName>
<role role="Data">
<rules>
<include>
@ -97,8 +101,6 @@ The following custom .xml file migrates the `Sample.doc` file from `C:\Engineeri
## Related articles
[Customize USMT XML files](usmt-customize-xml-files.md)
[Conflicts and precedence](usmt-conflicts-and-precedence.md)
[USMT XML reference](usmt-xml-reference.md)
- [Customize USMT XML files](usmt-customize-xml-files.md).
- [Conflicts and precedence](usmt-conflicts-and-precedence.md).
- [USMT XML reference](usmt-xml-reference.md).

22
windows/deployment/usmt/usmt-resources.md
View File

@ -1,35 +1,39 @@
---
title: USMT Resources (Windows 10)
title: USMT Resources
description: Learn about User State Migration Tool (USMT) online resources, including Microsoft Visual Studio and forums.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# USMT resources
## USMT online resources
- [ADK Release Notes](/windows-hardware/get-started/what-s-new-in-kits-and-tools)
- [ADK Release Notes](/windows-hardware/get-started/what-s-new-in-kits-and-tools).
- Microsoft Visual Studio
- You can use the User State Migration Tool (USMT) XML schema (the `MigXML.xsd` file) to validate the migration .xml files using an XML authoring tool such as Microsoft® Visual Studio®.
- The User State Migration Tool (USMT) XML schema (the `MigXML.xsd` file) can be used to validate the migration **.xml** files using an XML authoring tool such as Microsoft Visual Studio.
For more information about how to use the schema with your XML authoring environment, see the environment's documentation.
For more information about how to use the schema with an XML authoring environment, see the environment's documentation.
- [Ask the Directory Services Team blog](https://techcommunity.microsoft.com/t5/ask-the-directory-services-team/bg-p/AskDS)
- [Ask the Directory Services Team blog](https://techcommunity.microsoft.com/t5/ask-the-directory-services-team/bg-p/AskDS).
- Forums:
- [Microsoft Deployment Toolkit forum](/answers/topics/mem-mdt.html)
- [Microsoft Deployment Toolkit forum](/answers/topics/mem-mdt.html).
- [Configuration Manager Operating System Deployment forum](/answers/topics/mem-cm-osd.html)
- [Configuration Manager Operating System Deployment forum](/answers/topics/mem-cm-osd.html).
## Related articles
[User State Migration Tool (USMT) overview topics](usmt-topics.md)
[User State Migration Tool (USMT) overview articles](usmt-topics.md).

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

@ -1,40 +1,44 @@
---
title: ScanState Syntax (Windows 10)
description: The ScanState command is used with the User State Migration Tool (USMT) 10.0 to scan the source computer, collect the files and settings, and create a store.
title: ScanState Syntax
description: The ScanState command is used with the User State Migration Tool (USMT) to scan the source computer, collect the files and settings, and create a store.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# ScanState syntax
The `ScanState.exe` command is used with the User State Migration Tool (USMT) 10.0 to scan the source computer, collect the files and settings, and create a store. This article discusses the `ScanState.exe` command syntax and the options available with it.
The `ScanState.exe` command is used with the User State Migration Tool (USMT) to scan the source computer, collect the files and settings, and create a store. This article discusses the `ScanState.exe` command syntax and the options available with it.
## Before you begin
## Before beginning
Before you run the `ScanState.exe` command, note the items:
Before running the `ScanState.exe` command, note the items:
- To ensure that all operating system settings migrate, in most cases you must run the `ScanState.exe` commands in administrator mode from an account with administrative credentials.
- To ensure that all operating system settings migrate, in run the `ScanState.exe` commands in administrator mode from an account with administrative credentials.
- If you encrypt the migration store, you'll be required to enter an encryption key or a path to a file containing the encryption key. Be sure to make note of the key or the key file location, because this information isn't kept anywhere in the migration store. You'll need this information when you run the `LoadState.exe` command to decrypt the migration store, or if you need to run the recovery utility. An incorrect or missing key or key file results in an error message.
- If the migration store is encrypted, an encryption key or a path to a file containing the encryption key is required. Be sure to make note of the key or the key file location, because this information isn't kept anywhere in the migration store. This information is needed when the `LoadState.exe` command is run to decrypt the migration store, or if the recovery utility needs to be used. An incorrect or missing key or key file results in an error message.
- For information about software requirements for running the `ScanState.exe` command, see [USMT requirements](usmt-requirements.md).
- Unless otherwise noted, you can use each option only once when running a tool on the command line.
- Unless otherwise noted, use each option only once when running a tool on the command line.
- You can gather domain accounts without the source computer having domain controller access. This functionality is available without any extra configuration.
- Domain accounts can be gathered without the source computer having domain controller access. This functionality is available without any extra configuration.
- 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.
- The directory location where you save the migration store will be excluded from the scan. For example, if you save the migration store to the root of the D drive, the D drive and all of its subdirectories will be excluded from the scan.
- The directory location where the migration store is saved is excluded from the scan. For example, if the migration store is saved to the root of the D drive, the D drive and all of its subdirectories is excluded from the scan.
## Syntax
This section explains the syntax and usage of the command-line options available when you use the `ScanState.exe` command. The options can be specified in any order. If the option contains a parameter, you can use either a colon or a space separator.
This section explains the syntax and usage of the command-line options available when using the `ScanState.exe` command. The options can be specified in any order. If the option contains a parameter, either a colon or a space separator can be used.
The `ScanState.exe` command's syntax is:
@ -46,7 +50,7 @@ For example, to create a `Config.xml` file in the current directory, use:
ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:13
```
To create an encrypted store using the `Config.xml` file and the default migration .xml files, use:
To create an encrypted store using the `Config.xml` file and the default migration **.xml** files, use:
`ScanState.exe \\server\share\migration\mystore /i:MigApp.xml /i:MigDocs.xml /o /config:Config.xml /v:13 /encrypt /key:"mykey"`
@ -54,94 +58,96 @@ To create an encrypted store using the `Config.xml` file and the default migrati
| Command-Line Option | Description |
|-----|-----|
| *StorePath* | Indicates a folder where files and settings will be saved. *StorePath* can't be `C:\`. You must specify the *StorePath* option in the `ScanState.exe` command, except when using the `/genconfig` option. You can't specify more than one *StorePath* location. |
| *StorePath* | Indicates a folder where files and settings are saved. *StorePath* can't be `C:\`. The *StorePath* option must be specified in the `ScanState.exe` command, except when using the `/genconfig` option. More than one *StorePath* location can't be specified. |
| **/apps** | Scans the image for apps and includes them and their associated registry settings. |
| **/ppkg** [*&lt;FileName&gt;*] | 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 will fail if the migration store already contains data. You can't use this option 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 **&lt;ErrorControl&gt;** section. <br/><br/>This option is only used with the **ScanState** executable file and can't be combined with the `/hardlink` option. |
| **/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. |
| **/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:** *&lt;KeyString&gt;* &#124; **/keyfile**:*&lt;file&gt;*]} | Encrypts the store with the specified key. Encryption is disabled by default. With this option, you'll need to specify the encryption key-in one of the following ways: <ul><li>`/key`: *KeyString* specifies the encryption key. If there's a space in *KeyString*, you'll need to surround *KeyString* 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 will 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**:*&lt;EncryptionStrength&gt;* | 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. You can use the uncompressed store to view what USMT stored, troubleshoot a problem, or run an antivirus utility against the files. You should use this option only in testing environments, because we recommend that you use a compressed store during your actual migration, unless you're 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 you do choose to migrate an uncompressed store, the `LoadState.exe` command will migrate 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` |
| **/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 "File" 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
You can run the `ScanState.exe` command in Windows Preinstallation Environment (WinPE). In addition, USMT supports migrations from previous installations of Windows contained in Windows.old directories. The offline directory can be a Windows directory when you run the `ScanState.exe` command in WinPE or a Windows.old directory when you run the `ScanState.exe` command in Windows.
The `ScanState.exe` command can be run in Windows Preinstallation Environment (WinPE). In addition, USMT supports migrations from previous installations of Windows contained in **Windows.old** directories. The offline directory can be a Windows directory when the `ScanState.exe` command is run in WinPE or a **Windows.old** directory when the `ScanState.exe` command is run in Windows.
There are several benefits to running the `ScanState.exe` command on an offline Windows image, including:
- **Improved performance.**
Because WinPE is a thin operating system, there are fewer running services. In this environment, the `ScanState.exe` command has more access to the local hardware resources, enabling **ScanState** to perform migration operations more quickly.
Because WinPE is a thin operating system, there are fewer running services. In this environment, the `ScanState.exe` command has more access to the local hardware resources, enabling **ScanState** to perform migration operations more quickly.
- **Simplified end to end deployment process.**
Migrating data from Windows.old simplifies the end-to-end deployment process by enabling the migration process to occur after the new operating system is installed.
Migrating data from **Windows.old** simplifies the end-to-end deployment process by enabling the migration process to occur after the new operating system is installed.
- **Improved success of migration.**
The migration success rate is increased because files won't be locked for editing while offline, and because WinPE provides administrator access to files in the offline Windows file system, eliminating the need for administrator-level access to the online system.
The migration success rate is increased because:
- Files aren't locked for editing while offline.
- WinPE provides administrator access to files in the offline Windows file system, eliminating the need for administrator-level access to the online system.
- **Ability to recover an unbootable computer.**
- **Ability to recover an from a computer that doesn't boot.**
It might be possible to recover and migrate data from an unbootable computer.
It might be possible to recover and migrate data from a computer that doesn't boot.
## Offline migration options
|Command-Line Option|Definition|
|--- |--- |
|**/offline:** *"path to an Offline.xml file"*|This option is used to define a path to an offline .xml file that might specify other offline migration options, for example, an offline Windows directory or any domain or folder redirection required in your migration.|
|**/offlinewindir:** *"path to a Windows directory"*|This option specifies the offline Windows directory that the `ScanState.exe` command gathers user state from. The offline directory can be Windows.old when you run the `ScanState.exe` command in Windows or a Windows directory when you run the `ScanState.exe` command in WinPE.|
|**/offlinewinold:** *"Windows.old directory"*|This command-line option enables the offline migration mode and starts the migration from the location specified. It's only intended to be used in Windows.old migration scenarios, where the migration is occurring from a Windows.old directory.|
|**/offline:** *"path to an Offline.xml file"*|This option is used to define a path to an offline **.xml** file that might specify other offline migration options. For example, an offline Windows directory or any domain or folder redirection required in the migration.|
|**/offlinewindir:** *"path to a Windows directory"*|This option specifies the offline Windows directory that the `ScanState.exe` command gathers user state from. The offline directory can be **Windows.old** when the `ScanState.exe` command is run in Windows or a Windows directory when the `ScanState.exe` command is run in WinPE.|
|**/offlinewinold:** *"Windows.old directory"*|This command-line option enables the offline migration mode and starts the migration from the location specified. This option is only intended to be used in **Windows.old** migration scenarios, where the migration is occurring from a **Windows.old** directory.|
## 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/><br/>Specifies an .xml file that contains rules that define what user, application, or system state to migrate. You can specify this option multiple times to include all of your .xml files (`MigApp.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. 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 every component, application and setting that can be migrated, you should create this file on a source computer that contains all the components, applications, and settings that will be present on the destination computers. In addition, you should specify the other migration .xml files, using the **/i** option, when you specify this option.<br/><br/>After you create this file, you'll need to make use of it with the `ScanState.exe` command using the **/config** option.<br/><br/>The only options that you can specify with this option are the `/i`, `/v`, and `/l` options. You can't specify *StorePath*, because the `/genconfig` option doesn't create a store. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* will be 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. You can't use 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 *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 you to specify the location of the default .xml files and then begin the migration. If no path is specified, USMT will reference 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. |
| **/targetwindows8** | Optimizes `ScanState.exe` when using USMT 10.0 to migrate a user state to Windows 8 or Windows 8.1 instead of Windows 10. You should use this command-line option in the following scenarios: <ul><li>**To create a `Config.xml` file by using the `/genconfig` option.** Using the `/targetwindows8` option optimizes the `Config.xml` file so that it only contains components that relate to Windows 8 or Windows 8.1.</li><li>**To create a migration store.** Using the `/targetwindows8` option ensures that the **ScanState** tool gathers the correct set of operating system settings. Without the `/targetwindows8` command-line option, some settings can be lost during the migration.</li></ul> |
| **/targetwindows7** | Optimizes `ScanState.exe` when using USMT 10.0 to migrate a user state to Windows 7 instead of Windows 10. You should use this command-line option in the following scenarios: <ul><li>**To create a `Config.xml` file by using the `/genconfig` option.** Using the **/targetwindows7** option optimizes the `Config.xml` file so that it only contains components that relate to Windows 7.</li><li>**To create a migration store.** Using the `/targetwindows7` option ensures that the **ScanState** tool gathers the correct set of operating system settings. Without the `/targetwindows7` command-line option, some settings can be lost during the migration.</li></ul> |
| **/localonly** | Migrates only files that are stored on the local computer, regardless of the rules in the .xml files that you specify on the command line. You should use this option when you want to exclude the data from removable drives on the source computer, such as USB flash drives (UFDs), some external hard drives, and so on, and when there are network drives mapped on the source computer. If the `/localonly` option isn't specified, then the `ScanState.exe` command will copy files from these removable or network drives into the store.<br/><br/>Anything that isn't considered a fixed drive by the OS will be excluded by `/localonly`. 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>|
| **/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 "XML Files" 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. 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>|
## Monitoring options
USMT provides several options that you can use to analyze problems that occur during migration.
USMT provides several options that can be used to analyze problems that occur during migration.
> [!NOTE]
> The **ScanState** log is created by default, but you can specify the name and location of the log with the **/l** option.
>
> The **ScanState** log is created by default, but the name and location of the log can be specified with the **/l** option.
| Command-Line Option | Description |
|-----|-----|
| **/listfiles**:&lt;FileName&gt; | You can use the `/listfiles` command-line option 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/>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 will be created in the current directory. You can use the `/v` option to adjust the amount of output. <br/><br/>If you run the `ScanState.exe` command from a shared network resource, you must specify the `/l` option, or USMT will fail 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:***&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **ScanState** log file. The default value is 0. <br/><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/>`ScanState.exe \server\share\migration\mystore /v:13 /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* will be 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 will continue 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 won't fit in the store, the `ScanState.exe` command will log an error and continue with the migration. In addition, if a file is open or in use by an application, USMT may not be able to migrate the file and will log an error. Without the `/c` option, the `ScanState.exe` command will exit on the first error.<br/><br/>You can use the new &lt;**ErrorControl**&gt; 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 advantage in the `Config.xml` file enables the `/c` command-line option to safely skip all input/output (I/O) errors in your environment. In addition, the /`genconfig` option now generates a sample &lt;**ErrorControl**&gt; section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r:***&lt;TimesToRetry&gt;* | **(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/>While storing the user state, the `/r` option won't be able to 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:***&lt;SecondsBeforeRetry&gt;* | **(Wait)**<br/><br/>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/p:***&lt;pathToFile&gt;* | When the `ScanState.exe` command runs, it will create an .xml file in the path specified. This .xml file includes improved space estimations for the migration store. The following example shows how to create this .xml file:<br/>`ScanState.exe C:\MigrationLocation [additional parameters]`<br/>`/p:"C:\MigrationStoreSize.xml"`<br/><br/>For more information, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md).<br/><br/>To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, you can use the `/p` option, without specifying *&quot;pathtoafile&quot;*, in USMT. If you specify only the `/p` option, the storage space estimations are created in the same manner as with USMT3.x releases. |
| **/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` |
| **/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. |
| **/p:***\<pathToFile\>* | When the `ScanState.exe` command runs, it creates an **.xml** file in the path specified. This **.xml** file includes improved space estimations for the migration store. The following example shows how to create this **.xml** file:<br>`ScanState.exe C:\MigrationLocation [additional parameters]`<br>`/p:"C:\MigrationStoreSize.xml"`<br><br>For more information, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md).<br><br>To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option can be used, without specifying *"pathtoafile"*, in USMT. If only the `/p` option is specified, the storage space estimations are created in the same manner as with USMT 3.x releases. |
| **/?** or **/help** | Displays Help at 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 using the `Config.xml` file. For more information, see [Identify users](usmt-identify-users.md) and [Migrate user accounts](usmt-migrate-user-accounts.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 using the `Config.xml` file. For more information, see [Identify users](usmt-identify-users.md) and [Migrate user accounts](usmt-migrate-user-accounts.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 either 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 specify the `/all` option, you can't also use the `/ui`, `/ue` or `/uel` options. |
| **/ui**:*&lt;DomainName&gt;*&#92;*&lt;UserName&gt;*<br/>or<br/>**/ui**:*&lt;ComputerName&gt;*&#92;*&lt;LocalUserName&gt;* | **(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. 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 you specify a user name that contains spaces, you'll need to surround it 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 will be 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 have been 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 won't be migrated.</li></ul><br/>For more examples, see the descriptions of the `/ue` and `/ui` options in this table. |
| **/uel**:*&lt;NumberOfDays&gt;*<br/>or<br/>**/uel**:*&lt;YYYY/MM/DD&gt;*<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/>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 has signed in to another computer, that sign-in instance isn't considered by USMT. <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 have logged on, or whose accounts have been otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose account has been modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who have 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**:*&lt;DomainName&gt;*&#92;*&lt;UserName&gt;*<br/>-or-<br/><br/>**/ue**:*&lt;ComputerName&gt;*&#92;*&lt;LocalUserName&gt;* | **(User exclude)**<br/><br/>Excludes the specified users from the migration. You can specify multiple `/ue` options. You can't use this option with the `/all` option. *&lt;DomainName&gt;* and *&lt;UserName&gt;* can contain the asterisk (`*`) wildcard character. When you specify a user name that contains spaces, you need to surround it with quotation marks (`"`).<br/><br/>For example:<br/>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \\server\share\migration\mystore /ue:contoso\user1` |
| **/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
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|
|--- |--- |
@ -154,72 +160,75 @@ The following examples apply to both the `/ui` and `/ue` options. You can replac
## 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 specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user will be included in the migration. For example, if you specify `/ui:contoso\* /ue:contoso\user1`, then **User1** will be migrated, because the `/ui` option takes precedence over the `/ue` option.
The `/ui` option has precedence over the `/ue` and `/uel` options. 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. 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 has logged on within the specified time period set by the `/uel` option, that user's profile will be migrated even if they're excluded by using the `/ue` option. For example, if you specify `/ue:fixed\user1 /uel:14`, the User1 will be migrated if they've 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:fixed\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, you'll need to specify the following commands: <ul><li>On the `ScanState.exe` command line, enter:<br/> `/ue:*\* /ui:contoso\*`<br/></li><li>On the `LoadState.exe` command line, 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 commands: <ul><li>On the `ScanState.exe` command line, enter:<br> `/ue:*\* /ui:contoso\*`<br></li><li>On the `LoadState.exe` command line, enter:<br>`/ue:contoso\user1`</li></ul>|
|Include only local (non-domain) users.|`/ue:*\* /ui:%computername%\*`|
## Encrypted file options
You can use the following options to migrate encrypted files. In all cases, by default, USMT fails if an encrypted file is found unless you specify an `/efs` option. To migrate encrypted files, you must change the default behavior.
The following options can be used to migrate encrypted files. In all cases, by default, USMT fails if an encrypted file is found unless the `/efs` option is specified. To migrate encrypted files, the default behavior must be changed.
For more information, see [Migrate EFS Files and Certificates](usmt-migrate-efs-files-and-certificates.md).
> [!NOTE]
> EFS certificates will be migrated automatically when migrating to Windows 7, Windows 8 or Windows 10. Therefore, you should specify the `/efs:copyraw` option with the `ScanState.exe` command to migrate the encrypted files
>
> EFS certificates are migrated automatically during the migration. Therefore, the `/efs:copyraw` option should be specified with the `ScanState.exe` command to migrate the encrypted files.
> [!CAUTION]
> Take caution when migrating encrypted files. If you migrate an encrypted file without also migrating the certificate, end users will not be able to access the file after the migration.
>
> Take caution when migrating encrypted files. If an encrypted file is migrated without also migrating the certificate, end users won't be able to access the file after the migration.
| Command-Line Option | Explanation |
|----|----|
| **/efs:hardlink** | Creates a hard link to the EFS file instead of copying it. Use only with the `/hardlink` and the `/nocompress` options. |
| **/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 will be unencrypted in the migration store, and once you run the `LoadState.exe` command, the file will be copied to the destination computer. |
| **/efs:copyraw** | Causes the `ScanState.exe` command to copy the files in the encrypted format. The files will be inaccessible on the destination computer until the EFS certificates are migrated. EFS certificates will be automatically migrated; however, by default USMT fails if an encrypted file is found, unless you specify an `/efs` option. Therefore you should specify the `/efs:copyraw` option with the `ScanState.exe` command to migrate the encrypted file. Then, when you run the `LoadState.exe` command, the encrypted file and the EFS certificate will be 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 has been removed, the file will be 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: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>|
## Incompatible command-line options
The following table indicates which command-line options aren't compatible with the `ScanState.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 `ScanState.exe` command. If the table entry for a particular combination has a ✔️, 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**|||||
|**/o**|||||
|**/v**|||||
|**/nocompress**||||N/A|
|**/localonly**|||X||
|**/key**|X||X||
|**/encrypt**|Required*|X|X||
|**/keyfile**|N/A||X||
|**/l**|||||
|**/listfiles**|||X||
|**/progress**|||X||
|**/r**|||X||
|**/w**|||X||
|**/c**|||X||
|**/p**|||X|N/A|
|**/all**|||X||
|**/ui**|||X|X|
|**/ue**|||X|X|
|**/uel**|||X|X|
|**/efs**:*&lt;option&gt;*|||X||
|**/genconfig**|||N/A||
|**/config**|||X||
|*&lt;StorePath&gt;*|||X||
|**/i**| ✔️ | ✔️ | ✔️ | ✔️ |
|**/o**| ✔️ | ✔️ | ✔️ | ✔️ |
|**/v**| ✔️ | ✔️ | ✔️ | ✔️ |
|**/nocompress**| ✔️ | ✔️ | ✔️ |N/A|
|**/localonly**| ✔️ | ✔️ | ❌ | ✔️ |
|**/key**| ❌ | ✔️ | ❌ | ✔️ |
|**/encrypt**|Required*| ❌ | ❌ | ✔️ |
|**/keyfile**|N/A| ✔️ | ❌ | ✔️ |
|**/l**| ✔️ | ✔️ | ✔️ | ✔️ |
|**/listfiles**| ✔️ | ✔️ | ❌ | ✔️ |
|**/progress**| ✔️ | ✔️ | ❌ | ✔️ |
|**/r**| ✔️ | ✔️ | ❌ | ✔️ |
|**/w**| ✔️ | ✔️ | ❌ | ✔️ |
|**/c**| ✔️ | ✔️ | ❌ | ✔️ |
|**/p**| ✔️ | ✔️ | ❌ |N/A|
|**/all**| ✔️ | ✔️ | ❌ | ✔️ |
|**/ui**| ✔️ | ✔️ | ❌ | ❌ |
|**/ue**| ✔️ | ✔️ | ❌ | ❌ |
|**/uel**| ✔️ | ✔️ | ❌ | ❌ |
|**/efs**:*\<option\>*| ✔️ | ✔️ | ❌ | ✔️ |
|**/genconfig**| ✔️ | ✔️ |N/A| ✔️ |
|**/config**| ✔️ | ✔️ | ❌ | ✔️ |
|*\<StorePath\>*| ✔️ | ✔️ | ❌ | ✔️ |
> [!NOTE]
> You must specify either the `/key` or `/keyfile` option with the `/encrypt` option.
>
> Either the `/key` or `/keyfile` option must be specified with the `/encrypt` option.
## Related articles
[XML Elements Library](usmt-xml-elements-library.md)
- [XML Elements Library](usmt-xml-elements-library.md).

36
windows/deployment/usmt/usmt-technical-reference.md
View File

@ -1,26 +1,24 @@
---
title: User State Migration Tool (USMT) Technical Reference (Windows 10)
title: User State Migration Tool (USMT) Technical Reference
description: The User State Migration Tool (USMT) provides a highly customizable user-profile migration experience for IT professionals.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# User State Migration Tool (USMT) technical reference
The User State Migration Tool (USMT) is included with the Windows Assessment and Deployment Kit (Windows ADK) for Windows 10. USMT provides a highly customizable user-profile migration experience for IT professionals.
The User State Migration Tool (USMT) is included with the Windows Assessment and Deployment Kit (Windows ADK). USMT provides a highly customizable user-profile migration experience for IT professionals.
Download the Windows ADK [from this website](/windows-hardware/get-started/adk-install).
## USMT support for Microsoft Office
- USMT in the Windows ADK for Windows 10, version 1511 (10.1.10586.0) supports migration of user settings for installations of Microsoft Office 2003, 2007, 2010, and 2013.
- USMT in the Windows ADK for Windows 10, version 1607 (10.1.14393.0) adds support for migration of user settings for installations of Microsoft Office 2016.
The Windows ADK can be downloaded from the [Download and install the Windows ADK](/windows-hardware/get-started/adk-install) website.
USMT includes three command-line tools:
@ -28,25 +26,25 @@ USMT includes three command-line tools:
- LoadState.exe
- UsmtUtils.exe
USMT also includes a set of three modifiable .xml files:
USMT also includes a set of three modifiable **.xml** files:
- MigApp.xml
- MigDocs.xml
- MigUser.xml
Additionally, you can create custom .xml files to support your migration needs. You can also create a `Config.xml` file to specify files or settings to exclude from the migration.
Additionally, custom **.xml** files can be created to support the organization's migration needs. A `Config.xml` file can also be created to specify files or settings to exclude from the migration.
USMT tools can be used on several versions of Windows operating systems, for more information, see [USMT requirements](usmt-requirements.md). For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)).
USMT tools can be used on several versions of Windows operating systems. For more information, see [USMT requirements](usmt-requirements.md). For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)).
## USMT support for Microsoft Office
USMT in the currently supported versions of the Windows ADK supports migration of user settings for installations of Microsoft Office 2013 and 2016.
## In this section
| Link | Description |
|------ |----------- |
|[User State Migration Tool (USMT) overview topics](usmt-topics.md)|Describes what's new in USMT, how to get started with USMT, and the benefits and limitations of using USMT.|
|[User State Migration Tool (USMT) how-to topics](usmt-how-to.md)|Includes step-by-step instructions for using USMT and how-to topics for conducting tasks in USMT.|
|[User State Migration Tool (USMT) overview articles](usmt-topics.md)|Describes what's new in USMT, how to get started with USMT, and the benefits and limitations of using USMT.|
|[User State Migration Tool (USMT) how-to articles](usmt-how-to.md)|Includes step-by-step instructions for using USMT and how-to articles for conducting tasks in USMT.|
|[User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md)|Provides answers to frequently asked questions and common issues in USMT and a reference for return codes used in USMT.|
|[User State Migration Toolkit (USMT) reference](usmt-reference.md)|Includes reference information for migration planning, migration best practices, command-line syntax, using XML, and requirements for using USMT.|
## Related articles
- [Windows Assessment and Deployment Kit](/previous-versions/windows/it-pro/windows-8.1-and-8/dn247001(v=win.10))

42
windows/deployment/usmt/usmt-test-your-migration.md
View File

@ -1,35 +1,49 @@
---
title: Test Your Migration (Windows 10)
description: Learn about testing your migration plan in a controlled laboratory setting before you deploy it to your entire organization.
title: Test The Migration
description: Learn about testing the migration plan in a controlled laboratory setting before deploying it to the entire organization.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# Test your migration
# Test the migration
Always test your migration plan in a controlled laboratory setting before you deploy it to your entire organization. In your test environment, you need at least one computer for each type of operating system from which you're migrating data.
Always test the migration plan in a controlled laboratory setting before deploying it to the entire organization. In the test environment, at least one computer is needed for each type of operating system from which data is being migrated.
After you've thoroughly tested the entire migration process on a single computer running each of your source operating systems, conduct a pilot migration with a small group of users. After migrating a few typical user states to the intermediate store, note the space required and adjust your initial calculations accordingly. For details about estimating the space needed for your migration, see [Estimate migration store size](usmt-estimate-migration-store-size.md). You might also need to adjust the registry-setting and file-location information in your migration-rule files. If you make changes, test the migration again. Then verify that all data and settings have migrated as expected. A pilot migration also gives you an opportunity to test your space estimates for the intermediate store.
Once the entire migration process is tested on a single computer running each of the organization source operating systems, conduct a pilot migration with a small group of users. After migrating a few typical user states to the intermediate store, note the space required and adjust the initial calculations accordingly. For details about estimating the space needed for the migration, see [Estimate migration store size](usmt-estimate-migration-store-size.md). Registry-setting and file-location information might need to be adjusted in the migration-rule files. If changes are made, test the migration again and verify that all data and settings migrated as expected. A pilot migration also gives the opportunity to test the space estimates for the intermediate store.
If your test migration encounters any errors, examine the **ScanState** and **LoadState** logs to obtain the exact User State Migration Tool (USMT) 10.0 return code and associated error messages or Windows application programming interface (API) error message. For more information about USMT return codes and error messages, see [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes). You can obtain more information about any listed **Windows** system error codes by typing in a command prompt window `net.exe helpmsg <error_number>` where *<error_number>* is the error code number generated by the error message. For more information about System Error Codes, see [System Error Codes (0-499)](/windows/win32/debug/system-error-codes--0-499-).
If the test migration encounters any errors, examine the **ScanState** and **LoadState** logs to obtain the exact User State Migration Tool (USMT) return code and associated error messages or Windows application programming interface (API) error message. For more information about USMT return codes and error messages, see [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes). More information can be obtained about any listed **Windows** system error codes by typing in the following at a command prompt window:
In most cases, the **ScanState** and **LoadState** logs indicate why a USMT migration is failing. We recommend that you use the `/v:5` option when testing your migration. This verbosity level can be adjusted in a production migration. Reducing the verbosity level might make it more difficult to diagnose failures that are encountered during production migrations. You can use a higher verbosity level if you want the log files output to go to a debugger.
```cmd
net.exe helpmsg <error_number>
```
where *<error_number>* is the error code number generated by the error message. For more information about System Error Codes, see [System Error Codes (0-499)](/windows/win32/debug/system-error-codes--0-499-).
In most cases, the **ScanState** and **LoadState** logs indicate why a USMT migration is failing. Microsoft recommends using the `/v:5` option when testing the migration. This verbosity level can be adjusted in a production migration. Reducing the verbosity level might make it more difficult to diagnose failures that are encountered during production migrations. Higher verbosity levels can be used if the log files need to output to go to a debugger.
> [!NOTE]
> Running the **ScanState** and **LoadState** tools with the `/v:5` option creates a detailed log file. Although this option makes the log file large, it is helpful in determining where migration errors occurred.
>
> Running the **ScanState** and **LoadState** tools with the `/v:5` option creates a detailed log file. Although this option makes the log file large, it's helpful in determining where migration errors occurred.
After you've determined that the pilot migration successfully migrated the specified files and settings, you're ready to add USMT to the server that is running Microsoft Configuration Manager, or a non-Microsoft management technology. For more information, see [Manage user state in Configuration Manager](/configmgr/osd/get-started/manage-user-state).
After the pilot migration is verified that it successfully migrated the specified files and settings, USMT is ready to be used in the environment to migrate data. For example, using USMT with Microsoft Configuration Manager. For more information, see [Manage user state in Configuration Manager]/(mem/configmgr/osd/get-started/manage-user-state).
> [!NOTE]
> For testing purposes, you can create an uncompressed store using the `/hardlink /nocompress` option. When compression is disabled, the **ScanState** tool saves the files and settings to a hidden folder named **File** at `<StorePath>\USMT`. You can use the uncompressed store to view what USMT has stored or to troubleshoot a problem, or you can run an antivirus utility against the files. Additionally, you can also use the `/listfiles` command-line option and the diagnostic log to list the files that were gathered and to troubleshoot problems with your migration.
>
> For testing purposes, an uncompressed store using the `/hardlink /nocompress` option can be created. When compression is disabled, the **ScanState** tool saves the files and settings to a hidden folder named **File** at `<StorePath>\USMT`. The uncompressed store can be used to view what USMT stored or to troubleshoot a problem. An antivirus utility can also be run against the files. Additionally, the following items can be used to troubleshoot problems with the migration:
>
> - The `/listfiles` command-line option.
> - The diagnostic log that lists the files that were gathered.
## Related articles
[Plan your migration](usmt-plan-your-migration.md)
[Log files](usmt-log-files.md)
- [Plan the migration](usmt-plan-your-migration.md).
- [Log files](usmt-log-files.md).

20
windows/deployment/usmt/usmt-topics.md
View File

@ -1,18 +1,22 @@
---
title: User State Migration Tool (USMT) Overview Topics (Windows 10)
title: User State Migration Tool (USMT) Overview Articles
description: Learn about User State Migration Tool (USMT) overview articles that describe USMT as a highly customizable user-profile migration experience for IT professionals.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# User State Migration Tool (USMT) overview topics
# User State Migration Tool (USMT) overview articles
The User State Migration Tool (USMT) 10.0 provides a highly customizable user-profile migration experience for IT professionals. USMT includes three command-line tools: `ScanState.exe`, `LoadState.exe`, and `UsmtUtils.exe`. USMT also includes a set of three modifiable .xml files: `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`. Additionally, you can create custom .xml files to support your migration needs. You can also create a `Config.xml` file to specify files or settings to exclude from the migration.
The User State Migration Tool (USMT) provides a highly customizable user-profile migration experience for IT professionals. USMT includes three command-line tools: `ScanState.exe`, `LoadState.exe`, and `UsmtUtils.exe`. USMT also includes a set of three modifiable .xml files: `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`. Additionally, custom **.xml** files can be created to support the organization's migration needs. A `Config.xml` file can also be created to specify files or settings to exclude from the migration.
## In this section
@ -20,10 +24,10 @@ The User State Migration Tool (USMT) 10.0 provides a highly customizable user-pr
|------ |----------- |
|[User State Migration Tool (USMT) overview](usmt-overview.md)|Describes the benefits and limitations of using USMT.|
|[Getting started with the User State Migration Tool (USMT)](getting-started-with-the-user-state-migration-tool.md)|Describes the general process to follow to migrate files and settings, and provides links to more information.|
|[Windows upgrade and migration considerations](../upgrade/windows-upgrade-and-migration-considerations.md)|Discusses the Microsoft® tools you can use to move files and settings between installations and special considerations for performing an upgrade or migration.|
|[Windows upgrade and migration considerations](../upgrade/windows-upgrade-and-migration-considerations.md)|Discusses the Microsoft tools that can be used to move files and settings between installations and special considerations for performing an upgrade or migration.|
## Related articles
- [User State Migration Tool (USMT) how-to topics](usmt-how-to.md)
- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md)
- [User State Migration Toolkit (USMT) reference](usmt-reference.md)
- [User State Migration Tool (USMT) how-to articles](usmt-how-to.md).
- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md).
- [User State Migration Toolkit (USMT) reference](usmt-reference.md).

25
windows/deployment/usmt/usmt-troubleshooting.md
View File

@ -1,18 +1,22 @@
---
title: User State Migration Tool (USMT) Troubleshooting (Windows 10)
description: Learn about topics that address common User State Migration Tool (USMT) 10.0 issues and questions to help troubleshooting.
title: User State Migration Tool (USMT) Troubleshooting
description: Learn about articles that address common User State Migration Tool (USMT) issues and questions to help troubleshooting.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# User State Migration Tool (USMT) troubleshooting
The following table describes articles that address common User State Migration Tool (USMT) 10.0 issues and questions. These articles describe tools that you can use to troubleshoot issues that arise during your migration.
The following table describes articles that address common User State Migration Tool (USMT) issues and questions. These articles describe tools that can be used to troubleshoot issues that arise during the migration.
## In this section
@ -20,16 +24,13 @@ The following table describes articles that address common User State Migration
|--- |--- |
|[Common Issues](/troubleshoot/windows-client/deployment/usmt-common-issues)|Find troubleshooting solutions for common problems in USMT.|
|[Frequently Asked Questions](usmt-faq.yml)|Find answers to questions about how to use USMT.|
|[Log Files](usmt-log-files.md)|Learn how to enable logging to help you troubleshoot issues in USMT.|
|[Log Files](usmt-log-files.md)|Learn how to enable logging to help troubleshoot issues in USMT.|
|[Return Codes](/troubleshoot/windows-client/deployment/usmt-return-codes)|Learn how to use return codes to identify problems in USMT.|
|[USMT Resources](usmt-resources.md)|Find more information and support for using USMT.|
## Related articles
[USMT best practices](usmt-best-practices.md)
[User State Migration Tool (USMT) overview topics](usmt-topics.md)
[User State Migration Tool (USMT) how-to topics](usmt-how-to.md)
[User State Migration Toolkit (USMT) reference](usmt-reference.md)
- [USMT best practices](usmt-best-practices.md).
- [User State Migration Tool (USMT) overview articles](usmt-topics.md).
- [User State Migration Tool (USMT) how-to articles](usmt-how-to.md).
- [User State Migration Toolkit (USMT) reference](usmt-reference.md).

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

@ -1,26 +1,30 @@
---
title: UsmtUtils Syntax (Windows 10)
description: Learn about the syntax for the utilities available in User State Migration Tool (USMT) 10.0 through the command-line interface.
title: UsmtUtils Syntax
description: Learn about the syntax for the utilities available in User State Migration Tool (USMT) through the command-line interface.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 01/09/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# UsmtUtils Syntax
This article describes the syntax for the utilities available in User State Migration Tool (USMT) 10.0 through the command-line interface. These utilities:
This article describes the syntax for the utilities available in User State Migration Tool (USMT) through the command-line interface. These utilities:
- Improve your ability to determine cryptographic options for your migration.
- Improve the ability to determine cryptographic options for the migration.
- Help removing hard-link stores that can't otherwise be deleted due to a sharing lock.
- Verify whether the catalog file or any of the other files in the compressed migration store have become corrupted.
- Verify whether the catalog file or any of the other files in the compressed migration store are corrupted.
- Extract files from the compressed migration store when you migrate files and settings to the destination computer.
- Extract files from the compressed migration store created when files and settings are migrated to the destination computer.
## UsmtUtils.exe
@ -28,30 +32,30 @@ The following table lists command-line options for `UsmtUtils.exe`. The sections
The syntax for `UsmtUtils.exe` is:
> UsmtUtils.exe \[/ec | /rd *&lt;storeDir&gt;* | /verify *&lt;filepath&gt;* \[options\] | /extract *&lt;filepath&gt;* *&lt;destinationPath&gt;* \[options\]\]
> UsmtUtils.exe \[/ec | /rd *\<storeDir\>* | /verify *\<filepath\>* \[options\] | /extract *\<filepath\>* *\<destinationPath\>* \[options\]\]
|Command-line Option|Description|
|--- |--- |
|**/ec**|Returns a list of supported cryptographic algorithms (AlgIDs) on the current system. You can use this option on a destination computer to determine which algorithm to use with the `/encrypt` command before you run the **ScanState** tool on the source computer.|
|**/rd** *&lt;storeDir&gt;* |Removes the directory path specified by the *&lt;storeDir&gt;* argument on the computer. You can use this command 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, it will be deleted from all of these volumes. <br/><br/>For example:<br/>`UsmtUtils.exe /rd D:\MyHardLinkStore`|
|**/y**|Overrides the accept deletions prompt when used with the `/rd` option. When you use the `/y` option with the `/rd` option, you won't be prompted 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`.|
|**/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`|
|**/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 options
Use the `/verify` option when you want to determine whether a compressed migration store is intact or whether it contains corrupted files or a corrupted catalog. For more information on how to use the `/verify` option, see [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md).
Use the `/verify` option to determine whether a compressed migration store is intact or whether it contains corrupted files or a corrupted catalog. For more information on how to use the `/verify` option, see [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md).
The syntax for `/verify` is:
> UsmtUtils.exe /verify\[:*&lt;reportType&gt;*\] *&lt;filePath&gt;* \[/l:*&lt;logfile&gt;*\] \[/v:*VerbosityLevel*\] \[/decrypt \[:*&lt;AlgID&gt;*\] {/key:*&lt;keystring&gt;* | /keyfile:*&lt;filename&gt;*}\]
> UsmtUtils.exe /verify\[:*\<reportType\>*\] *\<filePath\>* \[/l:*\<logfile\>*\] \[/v:*VerbosityLevel*\] \[/decrypt \[:*\<AlgID\>*\] {/key:*\<keystring\>* | /keyfile:*\<filename\>*}\]
| Command-line Option | Description |
|-----|--------|
| *&lt;reportType&gt;* | 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/>*&lt;logfilePath&gt;* | Specifies the location and name of the log file. |
| **/v:** *&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br/><br/>You can set the *VerbosityLevel* 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** *&lt;AlgID&gt;* **/**:*&lt;KeyString&gt;*<br/>or<br/>**/decrypt** *&lt;AlgID&gt;* **/**:*&lt;"Key String"&gt;*<br/>or<br/>**/decrypt:** *&lt;AlgID&gt;* **/keyfile**:*&lt;FileName&gt;* | 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>*&lt;AlgID&gt;* 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/>*&lt;AlgID&gt;* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li> `/key:` *&lt;KeyString&gt;* specifies the encryption key. If there's a space in *&lt;KeyString&gt;*, you must surround the argument with quotation marks.</li><li> `/keyfile`: *&lt;FileName&gt;* 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) |
| *\<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 "OK" if the catalog file is intact and **LoadState** can open the migration store and "CORRUPTED" 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. |
| **/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). |
Some examples of `/verify` commands:
@ -65,21 +69,21 @@ Some examples of `/verify` commands:
## Extract options
Use the `/extract` option to recover files from a compressed USMT migration store if it will not restore normally with **LoadState**. For more information on how to use the `/extract` option, see [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md).
Use the `/extract` option to recover files from a compressed USMT migration store if it doesn't restore normally with **LoadState**. For more information on how to use the `/extract` option, see [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md).
The syntax for `/extract` is:
> /extract *&lt;filePath&gt;* *&lt;destinationPath&gt;* \[/i:*&lt;includePattern&gt;*\] \[/e: *&lt;excludePattern&gt;*\] \[/l: *&lt;logfile&gt;*\] \[/v: *VerbosityLevel&gt;*\] \[/decrypt\[:*&lt;AlgID&gt;*\] {key: *&lt;keystring&gt;* | /keyfile: *&lt;filename&gt;*}\] \[/o\]
> /extract *\<filePath\>* *\<destinationPath\>* \[/i:*\<includePattern\>*\] \[/e: *\<excludePattern\>*\] \[/l: *\<logfile\>*\] \[/v: *VerbosityLevel\>*\] \[/decrypt\[:*\<AlgID\>*\] {key: *\<keystring\>* | /keyfile: *\<filename\>*}\] \[/o\]
| Command-line Option | Description |
|-------|-----|
| *&lt;filePath&gt;* | Path to the USMT migration store. <br/><br/>For example:<br/>`D:\MyMigrationStore\USMT\store.mig` |
| *&lt;destinationPath&gt;* | Path to the folder where the tool puts the individual files. |
| **/i**:*&lt;includePattern&gt;* | Specifies a pattern for files to include in the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use `/i`: *&lt;includePattern&gt;* and `/e`: *&lt;excludePattern&gt;* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |
| **/e**:*&lt;excludePattern&gt;* | Specifies a pattern for files to omit from the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use `/i`: *&lt;includePattern&gt;* and `/e`: *&lt;excludePattern&gt;* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |
| **/l**:*&lt;logfilePath&gt;* | Specifies the location and name of the log file. |
| **/v:***&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br/><br/>You can set the *VerbosityLevel* 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***&lt;AlgID&gt;***/key**:*&lt;KeyString&gt;*<br/>or<br/>**/decrypt***&lt;AlgID&gt;***/**:*&lt;"Key String"&gt;*<br/>or<br/>**/decrypt:***&lt;AlgID&gt;***/keyfile**:*&lt;FileName&gt;* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, you must also specify the `/key` or `/keyfile` option as follows:<br/><ul><li>*&lt;AlgID&gt;* 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/>*&lt;AlgID&gt;* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li>`/key`: *&lt;KeyString&gt;* specifies the encryption key. If there's a space in *&lt;KeyString&gt;*, you must surround the argument with quotation marks.</li><li>`/keyfile`:*&lt;FileName&gt;* specifies 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). |
| *\<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. |
| **/l**:*\<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\>***/key**:*\<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, the `/key` or `/keyfile` option must also be specified 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 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). |
| **/o** | Overwrites existing output files. |
Some examples of `/extract` commands:
@ -94,6 +98,5 @@ Some examples of `/extract` commands:
## Related articles
[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md)
[Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes)
- [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md).
- [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes).

203
windows/deployment/usmt/usmt-what-does-usmt-migrate.md
View File

@ -1,28 +1,32 @@
---
title: What does USMT migrate (Windows 10)
description: Learn how User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language.
title: What does USMT migrate
description: Learn how User State Migration Tool (USMT) is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language.
ms.reviewer: kevinmi,warrenw
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/23/2022
ms.date: 01/18/2024
ms.topic: article
ms.technology: itpro-deploy
appliesto:
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
- ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 10</a>
---
# What does USMT migrate?
## Default migration scripts
The User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language. USMT provides the following sample scripts:
The User State Migration Tool (USMT) is designed so that an IT engineer can precisely define migrations using the USMT **.xml** scripting language. USMT provides the following sample scripts:
- **MigApp.XML** - Rules to migrate application settings.
- **MigDocs.XML** - Rules that use the **MigXmlHelper.GenerateDocPatterns** helper function, which can be used to automatically find user documents on a computer without the need to author extensive custom migration .xml files.
- **MigDocs.XML** - Rules that use the **MigXmlHelper.GenerateDocPatterns** helper function, which can be used to automatically find user documents on a computer without the need to author extensive custom migration **.xml** files.
- **MigUser.XML** - Rules to migrate user profiles and user data.
`MigUser.xml` gathers everything in a user's profile and then does a file extension- based search of most of the system for other user data. If data doesn't match either of these criteria, the data won't be migrated. Usually, this file describes a core migration.
`MigUser.xml` gathers everything in a user's profile and then does a file extension- based search of most of the system for other user data. If data doesn't match either of these criteria, the data isn't migrated. Usually, this file describes a core migration.
The following data doesn't migrate with `MigUser.xml`:
@ -33,28 +37,29 @@ The User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can
This section describes the user data that USMT migrates by default, using the `MigUser.xml` file. It also defines how to migrate access control lists (ACLs).
- **Folders from each user profile.** When you specify the `MigUser.xml` file, USMT migrates everything in a user's profiles including the following items:
- **Folders from each user profile.** When the `MigUser.xml` file is specified, USMT migrates everything in a user's profiles including the following folder items:
- My Documents
- Documents.
- My Video
- Videos.
- My Music
- Music.
- My Pictures
- Pictures.
- Desktop files
- Desktop files.
- Start menu
- Start menu.
- Quick Launch settings
- Quick Launch settings.
- Favorites
- Favorites.
> [!IMPORTANT]
> Starting in Windows 10, version 1607 the USMT does not migrate the Start menu layout. To migrate a user's Start menu, you must export and then import settings using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](/troubleshoot/windows-client/deployment/usmt-common-issues#usmt-doesnt-migrate-the-start-layout).
>
> USMT doesn't migrate the Start menu layout. To migrate a user's Start menu, settings must be exported and then imported using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](/troubleshoot/windows-client/deployment/usmt-common-issues#usmt-doesnt-migrate-the-start-layout).
- **Folders from the All Users and Public profiles.** When you specify the `MigUser.xml` file, USMT also migrates the following from the **Public** profile in Windows Vista, Windows 7, Windows 8, or Windows 10:
- **Folders from the All Users and Public profiles.** When the `MigUser.xml` file is specified, USMT also migrates the following from the **Public** profile in Windows:
- Shared Documents
@ -70,161 +75,120 @@ This section describes the user data that USMT migrates by default, using the `M
- Shared Favorites
- **File types.** When you specify the `MigUser.xml` file, the **ScanState** tool searches the fixed drives, collects, and then migrates files with any of the following file extensions:
- **File types.** When the `MigUser.xml` file is specified, the **ScanState** tool searches the fixed drives, collects, and then migrates files with any of the following file extensions:
`.accdb`, `.ch3`, `.csv`, `.dif`, `.doc*`, `.dot*`, `.dqy`, `.iqy`, `.mcw`, `.mdb*`, `.mpp`, `.one*`, `.oqy`, `.or6`, `.pot*`, `.ppa`, `.pps*`, `.ppt*`, `.pre`, `.pst`, `.pub`, `.qdf`, `.qel`, `.qph`, `.qsd`, `.rqy`, `.rtf`, `.scd`, `.sh3`, `.slk`, `.txt`, `.vl*`, `.vsd`, `.wk*`, `.wpd`, `.wps`, `.wq1`, `.wri`, `.xl*`, `.xla`, `.xlb`, `.xls*`
> [!NOTE]
>
> The asterisk (`*`) stands for zero or more characters.
> [!NOTE]
>
> The OpenDocument extensions (`*.odt`, `*.odp`, `*.ods`) that Microsoft Office applications can use aren't migrated by default.
- **Access control lists.** USMT migrates access control lists (ACLs) for specified files and folders from computers running both Windows® XP and Windows Vista. For example, if you migrate a file named `File1.txt` that is **read-only** for **User1** and **read/write** for **User2**, these settings will still apply on the destination computer after the migration.
- **Access control lists.** USMT migrates access control lists (ACLs) for specified files and folders from computers running Windows. For example, if a file named `File1.txt` that is **read-only** for **User1** and **read/write** for **User2** is migrated, these settings will still apply on the destination computer after the migration.
> [!IMPORTANT]
> To migrate ACLs, you must specify the directory to migrate in the MigUser.xml file. Using file patterns like \*.doc will not migrate a directory. The source ACL information is migrated only when you explicitly specify the directory. For example, `<pattern type="File">c:\test docs</pattern>`.
>
> To migrate ACLs, the directory to migrate must be specified in the `MigUser.xml` file. Using file patterns like \*.doc won't migrate a directory. The source ACL information is migrated only when the directory is explicitly specified. For example, `<pattern type="File">c:\test docs</pattern>`.
## Operating-system components
USMT migrates operating-system components to a destination computer from computers running Windows 7 and Windows 8
USMT migrates operating-system components to a destination computer. The following components are migrated by default using the manifest files:
The following components are migrated by default using the manifest files:
- Accessibility settings.
- Accessibility settings
- Address book.
- Address book
- Command-prompt settings.
- Command-prompt settings
- Desktop wallpaper. **¹**
- Desktop wallpaper **¹**
- EFS files.
- EFS files
- Favorites.
- Favorites
- Folder options.
- Folder options
- Fonts.
- Fonts
- Group membership. USMT migrates users' group settings. To view what groups a user belongs to:
- Group membership. USMT migrates users' group settings. The groups to which a user belongs can be found by right-clicking **My Computer** on the Start menu and then selecting **Manage**. When running an offline migration, the use of a **&lt;ProfileControl&gt;** section in the `Config.xml` file is required.
1. Right-clicking on the Start menu and then selecting **Computer Management**.
1. In the **Computer Management** console, expand **System tools** > **Local Users and Groups** > **Groups**.
1. Inspect the individual groups in the results pane to see what users belong to what groups.
The use of a **\<ProfileControl\>** section in the `Config.xml` file is required when running an offline migration.
- Windows Internet Explorer® settings **¹**
- Microsoft Open Database Connectivity (ODBC) settings.
- Microsoft® Open Database Connectivity (ODBC) settings
- Mouse and keyboard settings.
- Mouse and keyboard settings
- Network drive mapping.
- Network drive mapping
- Network printer mapping. **¹**
- Network printer mapping **¹**
- Offline files. **¹**
- Offline files **¹**
- Phone and modem options. **¹**
- Phone and modem options **¹**
- RAS connection and phone book (.pbk) files.
- RAS connection and phone book (.pbk) files
- Regional settings. **¹**
- Regional settings **¹**
- Remote Access.
- Remote Access
- Taskbar settings. **¹**
- Taskbar settings **¹**
- User personal certificates (all).
- User personal certificates (all)
- Windows Mail.
- Windows Mail
- Windows Media Player. **¹**
- Windows Media Player **¹**
- Windows Rights Management
- Windows Rights Management.
**¹** These settings aren't available for an offline migration. For more information, see [Offline migration reference](offline-migration-reference.md).
> [!IMPORTANT]
> This list may not be complete. There may be additional components that are migrated.
>
> This list might not be complete. There might be additional components that are migrated.
> [!NOTE]
> Some settings, such as fonts, aren't applied by the **LoadState** tool until after the destination computer has been restarted. For this reason, restart the destination computer after you run the **LoadState** tool.
>
> Some settings, such as fonts, aren't applied by the **LoadState** tool until after the destination computer is restarted. For this reason, restart the destination computer after running the **LoadState** tool.
## Supported applications
Even though it's not required for all applications, it's good practice to install all applications on the destination computer before restoring the user state. Installing applications before migrating settings helps to ensure that migrated settings aren't overwritten by the application installers.
Even though it isn't required for all applications, it's good practice to install all applications on the destination computer before restoring the user state. Installing applications before migrating settings helps to ensure application installers don't overwrite settings that were migrated.
> [!NOTE]
> The versions of installed applications must match on the source and destination computers. USMT does not support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office.
>
> The versions of installed applications must match on the source and destination computers. USMT doesn't support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office.
> [!NOTE]
> USMT migrates only the settings that have been used or modified by the user. If there is an application setting on the source computer that was not touched by the user, the setting may not migrate.
>
> USMT only migrates settings that are modified on the source computer. If an application setting isn't modified from the default on the source computer, the setting might not migrate.
When you specify the `MigApp.xml` file, USMT migrates the settings for the following applications:
|Product|Version|
|--- |--- |
|Adobe Acrobat Reader|9|
|AOL Instant Messenger|6.8|
|Adobe Creative Suite|2|
|Adobe Photoshop CS|8, 9|
|Adobe ImageReady CS||
|Apple iTunes|6, 7, 8|
|Apple QuickTime Player|5, 6, 7|
|Apple Safari|3.1.2|
|Google Chrome|beta|
|Google Picasa|3|
|Google Talk|beta|
|IBM Lotus 1-2-3|9|
|IBM Lotus Notes|6, 7, 8|
|IBM Lotus Organizer|5|
|IBM Lotus WordPro|9.9|
|Intuit Quicken Deluxe|2009|
|Money Plus Business|2008|
|Money Plus Home|2008|
|Mozilla Firefox|3|
|Microsoft Office|2003, 2007, 2010|
|Microsoft Office Access®|2003, 2007, 2010|
|Microsoft Office Excel®|2003, 2007, 2010|
|Microsoft Office FrontPage®|2003, 2007, 2010|
|Microsoft Office OneNote®|2003, 2007, 2010|
|Microsoft Office Outlook®|2003, 2007, 2010|
|Microsoft Office PowerPoint®|2003, 2007, 2010|
|Microsoft Office Publisher|2003, 2007, 2010|
|Microsoft Office Word|2003, 2007, 2010|
|Opera Software Opera|9.5|
|Microsoft Outlook Express|(only mailbox file)|
|Microsoft Project|2003, 2007|
|Microsoft Office Visio®|2003, 2007|
|RealPlayer Basic|11|
|Sage Peachtree|2009|
|Skype|3.8|
|Windows Live Mail|12, 14|
|Windows Live Messenger|8.5, 14|
|Windows Live MovieMaker|14|
|Windows Live Photo Gallery|12, 14|
|Windows Live Writer|12, 14|
|Windows Mail|(Windows 7 and 8)|
|Microsoft Works|9|
|Yahoo Messenger|9|
|Microsoft Zune™ Software|3|
When the `MigApp.xml` file is specified, USMT migrates the settings for specific applications defined in the `MigApp.xml` file. Consult the `MigApp.xml` file for applications are supported.
## What USMT doesn't migrate
The following items are settings that USMT doesn't migrate. If you're having a problem that isn't listed here, see [Common issues](/troubleshoot/windows-client/deployment/usmt-common-issues).
The following items are settings that USMT doesn't migrate. If having a problem that isn't listed here, see [Common issues](/troubleshoot/windows-client/deployment/usmt-common-issues).
### Application settings
USMT doesn't migrate the following application settings:
- Settings for Microsoft Store applications.
- Settings from earlier versions of an application. The versions of each application must match on the source and destination computers. USMT doesn't support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office. USMT can migrate from an earlier version of Microsoft Office to a later version.
- Application settings and some operating-system settings when a local account is created. For example, if you run `/lac` to create a local account on the destination computer, USMT will migrate the user data, but only some of the operating-system settings, such as wallpaper and screensaver settings, and no application settings will migrate.
- Application settings and some operating-system settings when a local account is created. For example, if `/lac` is specified to create a local account on the destination computer, USMT migrates the user data, but doesn't migrate:
- Microsoft Project settings, when migrating from Office 2003 to Office 2007 system.
- ICQ Pro settings, if ICQ Pro is installed in a different location on the destination computer. To successfully migrate the settings of ICQ Pro, you must install ICQ Pro in the same location on the destination computer as it was on the source computer. Otherwise, after you run the **LoadState** tool, the application won't start. You may encounter problems when:
- You change the default installation location on 32-bit destination computers.
- You attempt to migrate from a 32-bit computer to a 64-bit computer. Attempting to migrate settings between different architectures doesn't work because the ICQ Pro default installation directory is different on the two types of computers. When you install ICQ Pro on a 32-bit computer, the default location is `C:\Program Files\...`. The ICQ Pro default installation directory on an x64-based computer, however, is `C:\Program Files (x86)\...`.
- Some operating system settings - Only some operating-system settings, such as wallpaper and screensaver settings, are migrated.
- Application settings.
### Operating-System settings
@ -232,28 +196,29 @@ USMT doesn't migrate the following operating-system settings.
- Local printers, hardware-related settings, drivers, passwords, application binary files, synchronization files, DLL files, or other executable files.
- Permissions for shared folders. After migration, you must manually re-share any folders that were shared on the source computer.
- Permissions for shared folders. After migration, any folders that were shared on the source computer must be manually re-shared.
- Files and settings migrating between operating systems with different languages. The operating system of the source computer must match the language of the operating system on the destination computer.
- Customized icons for shortcuts may not migrate.
- Customized icons for shortcuts might not migrate.
You should also note the following items:
Also note the following items:
- You should run USMT from an account with administrative credentials. Otherwise, some data won't migrate. When running the **ScanState** and **LoadState** tools, you must run the tools in Administrator mode from an account with administrative credentials. If you don't run USMT in Administrator mode, only the user profile that is logged on will be included in the migration.
- Run USMT from an account with administrative credentials. Otherwise, some data doesn't migrate. When the **ScanState** and **LoadState** tools are run, the tools must be run in Administrator mode from an account with administrative credentials. If USMT isn't run in Administrator mode, only the user profile that is logged on is included in the migration.
- You can use the `/localonly` option to exclude the data from removable drives and network drives mapped on the source computer. For more information about what is excluded when you specify `/localonly`, see [ScanState syntax](usmt-scanstate-syntax.md).
- Use the `/localonly` option to exclude the data from removable drives and network drives mapped on the source computer. For more information about what is excluded when `/localonly` is specified, see [ScanState syntax](usmt-scanstate-syntax.md).
### Start menu layout
Starting in Windows 10, version 1607 the USMT doesn't migrate the Start menu layout. To migrate a user's Start menu, you must export and then import settings using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](/troubleshoot/windows-client/deployment/usmt-common-issues#usmt-doesnt-migrate-the-start-layout).
<a name='user-profiles-from-active-directory-to-azure-active-directory'></a>
USMT doesn't migrate the Start menu layout. To migrate a user's Start menu, settings must be exported and then imported using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](/troubleshoot/windows-client/deployment/usmt-common-issues#usmt-doesnt-migrate-the-start-layout).
### User profiles from Active Directory to Microsoft Entra ID
USMT doesn't support migrating user profiles from Active Directory to Microsoft Entra ID.
- USMT doesn't support migrating user profiles from Active Directory domain joined devices to Microsoft Entra joined devices.
- USMT doesn't support migrating user profiles from Microsoft Entra joined devices to Active Directory domain joined devices.
- USMT doesn't support migrating user profiles between Microsoft Entra joined devices.
- USMT might work when migrating user profiles between Microsoft Entra hybrid joined devices or between Active Directory domain joined devices and Microsoft Entra hybrid joined devices, but it's not a tested scenario so therefore unsupported.
## Related articles
[Plan your migration](usmt-plan-your-migration.md)
- [Plan the migration](usmt-plan-your-migration.md).

Some files were not shown because too many files have changed in this diff Show More