Merge pull request #13993 from ghogen/msbuild-errors-june2025

Add details for more error messages

Author: Stacyrch140

docs/msbuild/errors/msb3025.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3025 diagnostic code"
 description: Learn about the possible causes of the MSB3025 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3025
@@ -27,14 +27,24 @@ This article describes the MSB3025 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3025: The source file 'value' is actually a directory.  The 'Copy' task does not support copying directories.`
+`MSB3025: The source file 'path' is actually a directory.  The 'Copy' task does not support copying directories.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3025: The source file "{0}" is actually a directory.  The "Copy" task does not support copying directories. -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3025: "}
 -->
+## Description
+
+This error occurs when the [Copy task](../copy-task.md) is provided a path to a directory in the `SourceFiles` parameter. Since the MSBuild `Copy` task doesn't support copying directories, this is an error.
+
+## Resolution
+
+If you control the build logic where the `Copy` task is used, check your logic that creates the inputs for the `SourceFiles` parameter to see whether the paths you're providing are the ones you intended. If your intention is to copy the contents of a directory, the `SourceFiles` parameter of the `Copy` task should be an item that includes the files in the directory.
+
+This situation can easily occur in a build system if the folder structure changes and what was a path to a file is now a path to a folder. Update path inputs such as environment variables, command lines, and MSBuild properties to account for the new folder structure.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb3052.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3052 diagnostic code"
 description: Learn about the possible causes of the MSB3052 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3052
@@ -27,14 +27,24 @@ This article describes the MSB3052 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3052: The parameter to the compiler is invalid, ''value''value'' will be ignored.`
+`MSB3052: The parameter to the compiler is invalid, ''switch''value'' will be ignored.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3052: The parameter to the compiler is invalid, '{0}{1}' will be ignored. -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3052: "}
 -->
+## Description
+
+This error occurs when a command-line input to the [`Csc` task](../csc-task.md) was incorrectly specified, perhaps due to a syntax error, incorrect shell escape character, or missing or incorrect environment variable or property value.
+
+## Resolution
+
+Use verbose diagnostics (`-v:diag`), or generate a binary log and use the [MSBuild Structured Log Viewer](https://msbuildlog.com) to get complete information on the parameters to the `Csc` task that generated this error.
+
+Check syntax and logic involved in the construction of `Csc` parameter values, including the behavior of escape characters or special characters. Check the values of relevant environment variables and property values that are used to construct the parameters to the `Csc` task. Especially check that variables using MSBuild property syntax, such as `$(PROPERTY_NAME)` are resolved, and not passed as literal strings to the compiler.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb3088.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3088 diagnostic code"
-description: Learn about the possible causes of the MSB3088 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+description: Learn about the possible causes of the MSB3088 build message, and get troubleshooting tips.
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3088
@@ -27,14 +27,25 @@ This article describes the MSB3088 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3088: Could not read state file 'value'.`
+`MSB3088: Could not read state file 'file-path'.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3088: Could not read state file "{0}". {1} -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3088: "}
 -->
+## Description
+
+MSBuild uses certain files called state files to cache information between one build session and another. This information is used to avoid repeating analysis done in a previous run, and thereby improve performance. For example, information about referenced assemblies is reused when referenced assemblies haven't changed between builds to avoid having to repeat the same dependency analysis each time you build.
+
+This message is shown when a one of the state files couldn't be read, for any reason. It may be followed by a message from the operating system that gives more information about what the problem was.
+
+## Resolution
+
+This condition doesn't block the build, since MSBuild simply repeats the analysis that was cached, so your project still builds even if this message appears. However, it might mean builds could be faster if the root of the problem is found and fixed.
+
+Look to the error message from the operating system to understand what the root cause of the problem is and how to fix it.
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb3107.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3107 diagnostic code"
 description: Learn about the possible causes of the MSB3107 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3107
@@ -27,14 +27,44 @@ This article describes the MSB3107 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3107: The specified project reference metadata for the reference 'value' is missing or has an invalid value:`
+`MSB3107: The specified project reference metadata for the reference 'referenced-project-name' is missing or has an invalid value:`
 <!-- :::editable-content-end::: -->
 <!-- MSB3107: The specified project reference metadata for the reference "{0}" is missing or has an invalid value: {1} -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3107: "}
 -->
+## Description
+
+This error occurs when there's a problem with a `ProjectReference` in a project file. A `ProjectReference` element in MSBuild indicates a dependency on another project in the solution, for example, when you reference a class library project in a project that uses the library. In C# code, you can often look for the `using` directives in the project to see how it depends on APIs defined in the other project. The following code example shows a `ProjectReference` element that references `Calculator.Library`.
+
+```xml
+  <ItemGroup>
+	  <ProjectReference Include="..\Calculator.Library\Calculator.Library.csproj" />
+  </ItemGroup>
+```
+
+The `ProjectReference` may contain subelements that define metadata that specify details about the reference. Refer to the documentation for the supported metadata elements in [Common MSBuild project items - ProjectReference](../common-msbuild-project-items.md#projectreference).
+
+## Resolution
+
+Review the `ProjectReference` element mentioned in the error message and correct any obvious errors such as spelling errors or typos in the value referenced in the error message, or other values provided in the `ProjectReference`.
+
+If the error relates to a `Project` metadata with a GUID value, you can usually delete the `Project` metadata element and its value. Earlier versions of MSBuild expected a GUID value for the `Project` metadata element used to identify the project. If it is present, the GUID must be the correct project GUID (from the solution file) without any syntax errors. The following example shows the correct syntax with the `Project` metadata element and GUID value.
+
+```xml
+  <ItemGroup>
+	  <ProjectReference Include="..\Calculator.Library\Calculator.Library.csproj">
+		  <Project>{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</Project>
+	  </ProjectReference>
+  </ItemGroup>
+```
+
+You can also delete the `ProjectReference` element from the project file, and add a reference to that project again in the Visual Studio IDE. Adding a new project reference in Visual Studio recreates the elements in the project file with the most up-to-date metadata and values. See [Add or remove references - Projects tab](../../ide/how-to-add-or-remove-references-by-using-the-reference-manager.md#projects-tab).
+
+Check the `ToolsVersion` attribute. It's no longer needed in later versions of MSBuild, so you can try deleting it. If present, it should be `4.0` or later.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb3212.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3212 diagnostic code"
 description: Learn about the possible causes of the MSB3212 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3212
@@ -27,14 +27,21 @@ This article describes the MSB3212 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3212: The assembly 'value' could not be converted to a type library.`
+`MSB3212: The assembly 'assembly-name' could not be converted to a type library.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3212: The assembly "{0}" could not be converted to a type library. {1} -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3212: "}
 -->
+## Description
+
+This error occurs when executing the [RegisterAssembly task](../registerassembly-task.md) in the process of creating a type library when registering a .NET Framework assembly for use as a COM object. This error message is usually followed by text from an underlying tool such as [TlbExp.exe](/dotnet/framework/tools/tlbexp-exe-type-library-exporter) or from the Windows API that gives details of the error that occurred.
+
+## Resolution
+
+Look to the second error message for the cause of the problem and guidance on how to fix it.
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb3217.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3217 diagnostic code"
 description: Learn about the possible causes of the MSB3217 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3217
@@ -27,14 +27,22 @@ This article describes the MSB3217 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3217: Cannot register assembly 'value'.`
+`MSB3217: Cannot register assembly 'assembly-name'.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3217: Cannot register assembly "{0}". {1} -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3217: "}
 -->
+## Description
+
+This error occurs in the [RegisterAssembly task](../registerassembly-task.md) when, for any reason, the assembly could not be registered as a COM object. The error is followed by information from Windows with more details about the issue. See [Registering assemblies with COM](/dotnet/framework/interop/registering-assemblies-with-com).
+
+## Resolution
+
+This error occurs for a wide variety of causes that result in a failure to register an assembly. Registering a COM object requires that the account that runs MSBuild has admin permissions on the machine. 
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb3331.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3331 diagnostic code"
 description: Learn about the possible causes of the MSB3331 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3331
@@ -27,14 +27,26 @@ This article describes the MSB3331 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3331: Unable to apply publish properties for item 'value'.`
+`MSB3331: Unable to apply publish properties for item 'item-name'.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3331: Unable to apply publish properties for item "{0}". -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3331: "}
 -->
+## Description
+
+This error occurs in the [ResolveManifest task](../resolvemanifestfiles-task.md), which collects all the information, artifacts, and resources to generate a ClickOnce manifest. The error occurs when there's a problem with something that was required for the manifest generation.
+
+## Resolution
+
+Turn on verbose diagnostics (`-v:diag`), or generate a binary log and view it in the [Structured Log Viewer](https://msbuildlog.com). Find the place in the log where the `ResolveManifest` task is invoked. Check the input to the     `ResolveManifest` task and verify the correctness and validity of all the inputs.
+
+If you changed the publishing settings in Visual Studio, review them for errors. In .NET Framework projects, go to **Project Properties** > **Publish** > **Application Files**, and review the settings. Try selecting the **Reset All** button to see if the project builds and publishes with default settings.
+
+For more information, see [Specify files to publish](../../deployment/how-to-specify-which-files-are-published-by-clickonce.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb3686.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3686 diagnostic code"
 description: Learn about the possible causes of the MSB3686 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3686
@@ -35,6 +35,16 @@ This article describes the MSB3686 error code.
 <!--
 {StrBegin="MSB3686: "}
 -->
+## Description
+
+The <xref:Microsoft.Build.Tasks.XamlTaskFactory> creates a task at build time from the specified XML. It tries to compile a source file generated from an XML file specified in the `Task` element of the `UsingTask` element and, if the compilation files, this error occurs. It is followed by more specific error information from the compiler.
+
+> [!CAUTION]
+> `XamlTaskFactory` is not recommended for new development. It is not supported in .NET Core and .NET 5 and later.
+
+## Resolution
+
+Look to the following lines in the MSBuild output or log to see what the compilation error is. Identify the source XML file in the `Task` element of the `UsingTask` element. Review the XML input for correctness.
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb4075.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB4075 diagnostic code"
 description: Learn about the possible causes of the MSB4075 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB4075
@@ -27,14 +27,22 @@ This article describes the MSB4075 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB4075: The project file 'value' must be opened in the Visual Studio IDE and converted to the latest version before it can be built by MSBuild.`
+`MSB4075: The project file 'file-path' must be opened in the Visual Studio IDE and converted to the latest version before it can be built by MSBuild.`
 <!-- :::editable-content-end::: -->
 <!-- MSB4075: The project file "{0}" must be opened in the Visual Studio IDE and converted to the latest version before it can be built by MSBuild. -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB4075: "}
 -->
+## Description
+
+This error is given when MSBuild tries to open a project file that is in a format is no longer supported in the current version of Visual Studio and MSBuild. For example, projects with the extension `.vcproj` are not supported in MSBuild.
+
+## Resolution
+
+Open the project in Visual Studio to convert the project to a newer format. For example, in the case of `.vcproj`, Visual Studio upgrades the project and generates a `.vcxproj` file, which you can build on the MSBuild command line, or in Visual Studio.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb4244.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB4244 diagnostic code"
 description: Learn about the possible causes of the MSB4244 build error, and get troubleshooting tips.
-ms.date: 05/16/2025
+ms.date: 6/12/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB4244
@@ -27,14 +27,24 @@ This article describes the MSB4244 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB4244: The SDK resolver assembly 'value' could not be loaded.`
+`MSB4244: The SDK resolver assembly 'assembly-name' could not be loaded.`
 <!-- :::editable-content-end::: -->
 <!-- MSB4244: The SDK resolver assembly "{0}" could not be loaded. {1} -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB4244: "}
 -->
+## Description
+
+An SDK resolver assembly is an assembly that is loaded when an SDK is referenced in a project file. The purpose of the SDK resolver is to find and load the appropriate SDK. If this error occurs, it means that the resolver assembly couldn't be located or loaded.
+
+For general information on SDKs in MSBuild, see [Use MSBuild project SDKs](../how-to-use-project-sdk.md).
+
+## Resolution
+
+This error should never occur if you're using `dotnet build` or Visual Studio to build, but it could occur in a custom tool that uses the MSBuild API to perform a build and doesn't locate the right MSBuild installation files. The recommended way to locate MSBuild is to use <xref:Microsoft.Build.Locator.MSBuildLocator>. For detailed instructions, see [Find and use MSBuild versions](../find-and-use-msbuild-versions.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->