Merge pull request #13825 from GitHubber17/415544-e

410544 - MSBuild error article updates

Author: v-regandowner

docs/msbuild/errors/msb3721.md

@@ -1,7 +1,7 @@
 ---
-title: "MSB3721: The command 'command' exited with code 'error-code'"
-description: "This error occurs when a command launched in the build process exits with a non-zero error code."
-ms.date: "04/30/2021"
+title: MSB3721 diagnostic code
+description: Learn about the possible causes of the MSB3721 build error and get troubleshooting tips.
+ms.date: 04/15/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3721
@@ -16,14 +16,30 @@ ms.author: ghogen
 manager: mijacobs
 ms.subservice: msbuild
 ---
-# MSB3721: The command 'command' exited with code 'error-code'
+# MSB3721
 
-This error occurs when a command launched in the build process exits with a non-zero error code.
+This article describes the MSB3721 error code.
 
-To investigate the error, check the build output or build log to see if the custom build step produced an error with information about the problem. If not, try running it separately to check for any problems or unexpected behavior.
+## Message text
 
-If you can't see the exact command-line that failed, you can change the verbosity of the build output to show more detail. The MSBuild command-line option is `-verbosity:{level}` or `-V:{level}`, where `{level}` is one of `q[uiet]`, `m[inimal]`, `n[ormal]` (the default), `d[etailed]`, or `diag[nostic]`. See [MSBuild command line reference](../msbuild-command-line-reference.md). For bigger output logs on large projects, consider using the binary log (`-bl` command-line switch) and the [MSBuild Structured Log Viewer](https://msbuildlog.com/) to view the output more easily.
+`MSB3721: The command 'command' exited with code 'error-code'.`
 
-You can also set the `MSBuildDebugEngine` environment variable to 1 to get all possible logs. See [Building MSBuild for the .NET Framework - Logs](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Building-Testing-and-Debugging-on-Full-Framework-MSBuild.md#logs).
+## Description
 
-In Visual Studio, you can change the verbosity in **Tools** > **Options**, **Projects and Solutions**, **Build and Run**. See [How to: View, save, and configure build log files](../../ide/how-to-view-save-and-configure-build-log-files.md#specify-data-verbosity-for-build-logs).
+This error occurs when a command launched in the build process exits with a nonzero error code.
+
+## Resolution
+
+Check the build output or build log to see if the custom build step produced an error with information about the problem. If not, try running the step separately to check for any problems or unexpected behavior.
+
+If you can't see the exact command-line that failed, you can change the verbosity of the build output to show more detail.
+
+The MSBuild command-line option is `-verbosity:{level}` or `-V:{level}`, where `{level}` is one of `q[uiet]`, `m[inimal]`, `n[ormal]` (the default), `d[etailed]`, or `diag[nostic]`. For more information, see [MSBuild command line reference](../msbuild-command-line-reference.md). For longer output logs on large projects, consider using the binary log `-bl` command-line switch with the [MSBuild Structured Log Viewer](https://msbuildlog.com/) to view the output more easily.
+
+You can also set the `MSBuildDebugEngine` environment variable to 1 to get all possible logs. For more information, see [Building MSBuild for the .NET Framework - Logs](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Building-Testing-and-Debugging-on-Full-Framework-MSBuild.md#logs).
+
+In Visual Studio, you can change the verbosity in **Tools** > **Options**, **Projects and Solutions**, **Build and Run**. For more information, see [View, save, and configure build log files](../../ide/how-to-view-save-and-configure-build-log-files.md#specify-data-verbosity-for-build-logs).
+
+## Applies to
+
+All versions of MSBuild

docs/msbuild/errors/msb3774.md

@@ -1,7 +1,7 @@
 ---
-title: "MSB3774: The SDK 'name' specified could not be found."
-description: "This error occurs when MSBuild couldn't find the SDK referenced in the project file."
-ms.date: "08/15/2022"
+title: MSB3774 diagnostic code
+description: Learn about the possible causes of the MSB3774 build error and get troubleshooting tips.
+ms.date: 04/15/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3774
@@ -18,10 +18,24 @@ ms.subservice: msbuild
 ---
 # MSB3774
 
-This error occurs when MSBuild can't find the SDK referenced in the project file. MSBuild relies on user-extensible SDK resolvers to find SDKs. You get this error when a configured resolver could not find the requested SDK.
+This article describes the MSB3774 error code.
 
-Check the project file and locate the root Project element, and check its `Sdk` attribute. For .NET projects, this value should be `Microsoft.NET.Sdk` or for NuGet, check the spelling of the package or feed name, and version number, and that the referenced NuGet feed is accessible or publicly available.
+## Message text
 
-Check that the SDK is installed correctly. Check with the SDK provider to make sure that you are using the right name to reference the SDK.
+`MSB3774: The SDK 'name' specified could not be found.`
 
-See [How to use Project SDK](../how-to-use-project-sdk.md).
+## Description
+
+This error occurs when MSBuild can't find the SDK referenced in the project file. MSBuild relies on user-extensible SDK resolvers to find SDKs. You get this error when a configured resolver can't find the requested SDK.
+
+## Resolution
+
+In your project file, check the root `Project` element and the `Sdk` attribute. For .NET projects, the attribute value should be `Microsoft.NET.Sdk` or a reference for NuGet. Check the spelling of the package or feed name, and the version number. Confirm the referenced NuGet feed is accessible or publicly available.
+
+Verify that the SDK is installed correctly. Check with the SDK provider to make sure you're using the correct name to reference the SDK.
+
+For more information, see [How to use Project SDK](../how-to-use-project-sdk.md).
+
+## Applies to
+
+All versions of MSBuild

docs/msbuild/errors/msb3821.md

@@ -1,7 +1,7 @@
 ---
-title: "MSB3821: Couldn't process file 'path' due to its being in the Internet or Restricted zone or having the mark of the web on the file"
-description: "This error occurs when MSBuild attempts to process a file downloaded from the web with security restrictions."
-ms.date: "04/30/2021"
+title: MSB3821 diagnostic code
+description: Learn about the possible causes of the MSB3821 build error and get troubleshooting tips.
+ms.date: 04/15/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3821
@@ -16,23 +16,36 @@ ms.author: ghogen
 manager: mijacobs
 ms.subservice: msbuild
 ---
-# MSB3821: Couldn't process file 'path' due to its being in the Internet or Restricted zone or having the mark of the web on the file
+# MSB3821
 
-This error occurs when MSBuild attempts to process a file downloaded from the web (or a cloud drive) with security restrictions.
+This article describes the MSB3821 error code.
 
-When you download web assets such as HTML pages to a Windows device using a browser, the browser inserts a marker called the *mark of the web*, which records the security zone of the site from which the page originated. This is intended to protect from potentially malicious pages and enforce the security level on the original site, even after a page from the site is downloaded. This security check is required due to this security issue: [Visual Studio Remote Code Execution Vulnerability CVE-2018-8172](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2018-8172).
+## Message text
 
- MSBuild respects this security restriction, but if you decide that you trust the content in question, but you can override the restriction by unblocking a single file from File Explorer (open the **Properties** window on the file, and check **Unblock**). To unblock multiple files using a PowerShell script, use the [Unblock-File](/powershell/module/microsoft.powershell.utility/unblock-file) cmdlet.
+`MSB3821: Couldn't process file 'path' due to its being in the Internet or Restricted zone or having the mark of the web on the file.
+Remove the mark of the web if you want to process these files.`
 
-The full message is similar to the following text:
+## Description
 
-```output
-Couldn't process file 'path' due to its being in the Internet or Restricted zone or having the mark of the web on the file.
-Remove the mark of the web if you want to process these files.
-```
+This error occurs when MSBuild attempts to process a file downloaded from the web (or a cloud drive) that has security restrictions.
 
-Visual Studio also includes security restrictions that detect the mark of the web comment. You can customize these settings in the **Tools** > **Options** section **Trust Settings**. See [Configure trust settings for files and folders](../../ide/reference/trust-settings.md).
+When you download web assets like HTML pages to a Windows device by using a browser, the browser inserts a marker called the *mark of the web*, which records the security zone of the site from which the page originated. The mark is intended to help protect from potentially malicious pages and enforce the security level on the original site, even after a page from the site is downloaded. This security check is required due to a specific security issue: [Visual Studio remote code execution vulnerability CVE-2018-8172](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2018-8172).
 
-If you can't fix the error directly in Visual Studio, then close Visual Studio, go to the projects folder in File Explorer, open the **Properties menu** of the file that's giving you the error (keyboard: **Alt** + **Enter**), check the checkbox with the label **Unblock**, then click **Apply** and close the window.  When you reopen Visual Studio and open your project, try building again.
+## Resolution
 
-From PowerShell, you can use the command [Unblock-File](/powershell/module/microsoft.powershell.utility/unblock-file).
+If you decide to trust the content in question, you can override the restriction by unblocking a single file from File Explorer. Open the **Properties** window on the file, and select **Unblock**. You can also unblock multiple files with a PowerShell script and the [Unblock-File](/powershell/module/microsoft.powershell.utility/unblock-file) cmdlet.
+
+Visual Studio also includes security restrictions that detect the *mark of the web* comment. You can customize these settings in the **Tools** > **Options** section **Trust Settings**. For more information, see [Configure trust settings for files and folders](../../ide/reference/trust-settings.md).
+
+In some cases, you can't fix the error directly in Visual Studio. Instead, follow this procedure:
+
+1. Close Visual Studio.
+1. In File Explorer, go to the project folder.
+1. Locate the file that has the MSB3821 error and open the **Properties menu** (**Alt** + **Enter**).
+1. Select the **Unblock** checkbox, and then select **Apply**.
+1. Close the window.
+1. Restart Visual Studio. Open your project, and build the project again.
+
+## Applies to
+
+All versions of MSBuild

docs/msbuild/errors/msb3822.md

@@ -1,7 +1,7 @@
 ---
-title: "MSB3822"
-description: "Non-string resources require the System.Resources.Extensions assembly at runtime, but it was not found in this project's references."
-ms.date: "06/18/2021"
+title: MSB3822 diagnostic code
+description: Learn about the possible causes of the MSB3822 build error and get troubleshooting tips.
+ms.date: 04/15/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3822
@@ -16,10 +16,24 @@ ms.author: ghogen
 manager: mijacobs
 ms.subservice: msbuild
 ---
-# MSB3822: Non-string resources require the System.Resources.Extensions assembly at runtime, but it was not found in this project's references
+# MSB3822
 
-This error occurs when the project file opts into embedding resources using the new `System.Resources.Extensions` mechanism, which is not compatible with old .NET Framework project types unless `System.Resources.Extensions.dll` is available at runtime.
+This article describes the MSB3822 error code.
 
-To resolve this issue, either reference the `System.Resources.Extensions` package, or use the default resource-embedding process (do not specify `GenerateResourceUsePreserializedResources`).
+## Message text
 
-When running on .NET Core or .NET 5.0 or higher, MSBuild supports *only* the new resource-embedding technique. If you wish to use the old default process, you must build with MSBuild.exe or Visual Studio and cannot use `dotnet build`.
+`MSB3822: Non-string resources require the System.Resources.Extensions assembly at runtime, but it was not found in this project's references.`
+
+## Description
+
+This error occurs when the project file opts into embedding resources by using the new `System.Resources.Extensions` mechanism. This mechanism isn't compatible with older .NET Framework project types unless the `System.Resources.Extensions.dll` library is available at runtime.
+
+## Resolution
+
+To resolve this issue, you can reference the `System.Resources.Extensions` package, or use the default resource-embedding process (don't specify the `GenerateResourceUsePreserializedResources` option).
+
+When you run on .NET Core or .NET 5.0 or higher, MSBuild supports *only* the new resource-embedding technique. If you want to use the old default process, you must build with MSBuild.exe or Visual Studio and can't use the `dotnet build` command.
+
+## Applies to
+
+All versions of MSBuild

docs/msbuild/errors/msb3836.md

@@ -1,7 +1,7 @@
 ---
-title: "MSB3836"
-description: "The explicit binding redirect on 'assembly' conflicts with an autogenerated binding redirect. Consider removing it from the application configuration file or disabling autogenerated binding redirects. The build will replace it with: 'binding-redirect'."
-ms.date: "07/07/2021"
+title: MSB3836 diagnostic code
+description: Learn about the possible causes of the MSB3836 build error and get troubleshooting tips.
+ms.date: 04/15/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3836
@@ -18,10 +18,22 @@ ms.subservice: msbuild
 ---
 # MSB3836
 
-This error occurs when you explicitly specify a binding redirect, but a conflicting binding redirect was already automatically generated for that assembly.
+This article describes the MSB3836 error code.
 
-Learn more about binding redirects at [Redirect assembly versions](/dotnet/framework/configure-apps/redirect-assembly-versions).
+## Message text
 
-Check for a [bindingredirect element](/dotnet/framework/configure-apps/file-schema/runtime/bindingredirect-element) in the application configuration file (for example, *app.config*) to check if your code explicitly specifies a binding redirect.
+`MSB3836: The explicit binding redirect on 'assembly' conflicts with an autogenerated binding redirect. Consider removing it from the application configuration file or disabling autogenerated binding redirects. The build will replace it with: 'binding-redirect'.`
 
-To disable autogenerated binding redirects, see [How to: Enable or disable automatic binding redirection](/dotnet/framework/configure-apps/how-to-enable-and-disable-automatic-binding-redirection).
+## Description
+
+This error occurs when you explicitly specify a binding redirect, but a conflicting binding redirect is already automatically generated for the assembly. For more information about binding redirects, see [Redirect assembly versions](/dotnet/framework/configure-apps/redirect-assembly-versions).
+
+## Resolution
+
+Look for a [bindingredirect element](/dotnet/framework/configure-apps/file-schema/runtime/bindingredirect-element) in the application configuration file (for example, *app.config*). The presence of this element can help you determine if your code explicitly specifies a binding redirect.
+
+To disable autogenerated binding redirects, see [Enable or disable automatic binding redirection](/dotnet/framework/configure-apps/how-to-enable-and-disable-automatic-binding-redirection).
+
+## Applies to
+
+All versions of MSBuild

docs/msbuild/errors/msb3884.md

@@ -1,7 +1,7 @@
 ---
-title: "MSB3884: Could not find rule set file 'filename'."
-description: "This error occurs when MSBuild couldn't find a ruleset file needed by Code Analysis."
-ms.date: "07/07/2021"
+title: MSB3884 diagnostic code
+description: Learn about the possible causes of the MSB3884 build error and get troubleshooting tips.
+ms.date: 04/15/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3884
@@ -16,8 +16,22 @@ ms.author: ghogen
 manager: mijacobs
 ms.subservice: msbuild
 ---
-# MSB3884: Could not find rule set file 'filename'
+# MSB3884
 
-This error occurs when MSBuild couldn't find a ruleset file needed by Code Analysis. Code Analysis uses ruleset files that determine which rules are active. Ensure that the specified file exists and your MSBuild process has the right permissions to read it.
+This article describes the MSB3884 error code.
 
-See [Using rule sets to group code analysis rules](../../code-quality/using-rule-sets-to-group-code-analysis-rules.md).
+## Message text
+
+`MSB3884: Could not find rule set file 'filename'.`
+
+## Description
+
+This error occurs when MSBuild can't find a ruleset file required for Code Analysis. Code Analysis uses ruleset files to determine which rules are active.
+
+## Resolution
+
+Verify the specified file exists. Confirm your MSBuild process can read the file (correct access permissions). For more information, see [Use rule sets to group code analysis rules](../../code-quality/using-rule-sets-to-group-code-analysis-rules.md).
+
+## Applies to
+
+All versions of MSBuild

docs/msbuild/errors/msb3971.md

@@ -1,7 +1,7 @@
 ---
-title: "MSB3971"
-description: "The reference assemblies for 'framework-version' were not found. You might be using an older .NET SDK to target .NET 5.0 or higher. Update Visual Studio and/or your .NET SDK."
-ms.date: 2/5/2025
+title: MSB3971 diagnostic code
+description: Learn about the possible causes of the MSB3971 build error and get troubleshooting tips.
+ms.date: 04/15/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3971
@@ -16,12 +16,22 @@ ms.author: ghogen
 manager: mijacobs
 ms.subservice: msbuild
 ---
-# MSB3971 diagnostic code
+# MSB3971
 
-The full error is:
+This article describes the MSB3971 error code.
 
-```output
-The reference assemblies for 'framework-version' were not found. You might be using an older .NET SDK to target .NET 5.0 or higher. Update Visual Studio and/or your .NET SDK.
-```
+## Message text
 
-This error occurs when you're building for .NET 5 or later, but you're using an older version of the .NET SDK. This issue can usually be resolved by upgrading to a newer version of your build tools. To install a newer version of the .NET SDK, see [Download .NET](https://dotnet.microsoft.com/download).
+`MSB3971: The reference assemblies for 'framework-version' were not found. You might be using an older .NET SDK to target .NET 5.0 or higher. Update Visual Studio and/or your .NET SDK.`
+
+## Description
+
+This error occurs when you're building for .NET 5 or later, but you're using an older version of the .NET SDK.
+
+## Resolution
+
+This issue can usually be resolved by upgrading to a newer version of your build tools. To install a newer version of the .NET SDK, see [Download .NET](https://dotnet.microsoft.com/download).
+
+## Applies to
+
+All versions of MSBuild