Merging changes synced from https://github.com/MicrosoftDocs/visualstudio-docs-pr (branch live)

Learn Build Service GitHub App · Learn Build Service GitHub App · commit eb312e71eb41 · 2025-06-06T06:03:45.000Z
diff --git a/docs/msbuild/common-msbuild-project-properties.md b/docs/msbuild/common-msbuild-project-properties.md
diff --git a/docs/msbuild/errors/msb1004.md b/docs/msbuild/errors/msb1004.md
@@ -37,6 +37,20 @@ This article describes the MSB1004 error code.
       following the switch, as in "msbuild.exe -target:blah".
       LOCALIZATION: The prefix "MSBUILD : error MSBxxxx:" should not be localized.
 -->
+## Description
+
+This error occurs when the MSBuild command line contains a `-targets` or `-t` switch, which is used to request a specific target to build, but no target was specified.
+
+## Resolution
+
+Provide the target name that you want to build by putting it just after the `-t` or `-targets` switch. If that isn't the problem, check for typos in the command-line syntax, such as mismatched quotes or unintended shell escape characters. If you're constructing the MSBuild command line using an environment variable or shell script, check that the environment variable exists, has a value, and is referenced using the correct shell-specific syntax.
+
+Possible targets might be defined in the project file itself. These appear with syntax like `<Target Name="MyTarget">`, which begins the specification of a target in the project file. Or, you can specify a target from of the system-provided target files. These are files, typically with the `.targets` extension, such as `Microsoft.Common.targets`, `Microsoft.Common.CSharp.targets`, and so on in the MSBuild installation folders. If you're using a project SDK (for example, you used the `Sdk="Microsoft.Net.Sdk"` attribute on the `Project` node in the project file), these system `.targets` files are imported implicitly.
+
+If you don't know what the name of your desired target is, or what target you want to build, try issuing the command `MSBuild.exe -targets`, which generates a list of available targets, but doesn't run the build.
+
+For more information, see [MSBuild targets](../msbuild-targets.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb1011.md b/docs/msbuild/errors/msb1011.md
@@ -38,6 +38,18 @@ This article describes the MSB1011 error code.
       fire this error.
       LOCALIZATION: The prefix "MSBUILD : error MSBxxxx:" should not be localized.
 -->
+## Description
+
+If no project or solution file is explicitly specified on the MSBuild.exe command-line, then the engine searches for a project or solution file by looking for `*.*proj` or `*.sln` (or `*.slnx` with MSBuild 17.13 and later). MSBuild searches in the current directory, unless you specify a different working directory by passing a directory name on the command line.
+
+It's not an error to have a folder with a solution file and a single project file with the same name. In that case, the solution file is used for the build. Similarly, if a solution file and multiple project files are found in the same folder, the solution is built. However, if only one project file is found, and it has a different name than a solution file in the same folder (not counting the file extension), then MSBuild issues this error.
+
+## Resolution
+
+If you get this error because your solution contains one project, and the project has a different name than the solution, then MSBuild can't automatically find what you want to build. Instead, specify either the solution file or the project file explicitly on the command line.
+
+Also, check the command line syntax for problems with special characters such as quotes and escape characters, or for issues with shell expansions and missing or undefined environment variables that could result in an empty string for the project or solution file.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb1060.md b/docs/msbuild/errors/msb1060.md
@@ -28,8 +28,8 @@ This article describes the MSB1060 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB1060: Specify one or more warning codes when using the -warnNotAsError switch.
-MSB1060: Undefined environment variable passed in as switch.`
+`MSB1060: Specify one or more warning codes when using the -warnNotAsError switch.`
+`MSB1060: Undefined environment variable passed in as switch.`
 <!-- :::editable-content-end::: -->
 <!-- MSB1060: Specify one or more warning codes when using the -warnNotAsError switch.
 MSB1060: Undefined environment variable passed in as switch. -->
@@ -44,6 +44,22 @@ MSB1060: Undefined environment variable passed in as switch. -->
       UE: This error is shown when a user passes in an environment variable (including from a response file)
       but the environment variable is not defined.
 -->
+## Description
+
+There are two errors that can give this error code. The first relates to the `-warnNotAsError` (or the short form `-noerr`) command-line switch. See [MSBuild command line reference](../msbuild-command-line-reference.md). The error is shown when the `-warnNotAsError` (or `-noerr`) switch is used, but no error codes were given. The switch is expected to be followed by a list of error codes, separated by a semicolon or comma. For example:
+
+`msbuild.exe -err -noerr MSB3187;MSB3243`
+
+The other error condition that gives this code is when a response file (`.rsp` file) contains an environment variable name, but the environment variable didn't exist or has no value.
+
+## Resolution
+
+If you saw the first of the two messages, heck the command line syntax around the option `-warnNotAsError` or `-noerr` and verify that there are no syntax errors, and that it has one or more error codes listed after it. If there is any shell expansion or environment variable that provides the list of codes, check that it has a value.
+
+If you saw the second error message, use a response file for the MSBuild command line, validate the syntax, spelling, existence, and correct values of any environment variables referenced in the file. The correct syntax in the response file is shell-specific. For example, for `cmd.exe` the syntax is `%ENVIRONMENT_VARIABLE%`.
+
+Note that the response file `MSBuild.rsp` is always used if present, regardless of whether you specify it on the command line. Also, `Directory.Build.rsp` is used, if present in the folders above the current folder.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3091.md b/docs/msbuild/errors/msb3091.md
@@ -35,6 +35,13 @@ This article describes the MSB3091 error code.
 <!--
 {StrBegin="MSB3091: "}
 -->
+## Description
+
+This error occurs when a task failed because it depends on the Windows SDK, which was not found or not installed.
+
+## Resolution
+
+Install or reinstall the Windows SDK.
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3178.md b/docs/msbuild/errors/msb3178.md
@@ -21,7 +21,7 @@ ms.subservice: msbuild
 
 <!-- :::ErrorDefinitionDescription::: -->
 <!-- :::editable-content name="introDescription"::: -->
-This article describes the MSB3178 error code.
+This article describes the MSB3178 diagnostic code.
 <!-- :::editable-content-end::: -->
 
 ## Message text
@@ -35,6 +35,26 @@ This article describes the MSB3178 error code.
 <!--
 {StrBegin="MSB3178: "}
 -->
+## Description
+
+This warning occurs when MSBuild tries to process a manifest file, but encountered a file that looks like an assembly that was specified as an ordinary file, instead of using the correct XML structure for an assembly. Assembly manifests used in ClickOnce deployment for .NET applications are XML files that contain an XML-encoded of the contents of an application, which might include assemblies and files. Assemblies are specified using the `assembly` element, which also includes child elements such as `assemblyInformation`; plain files are specified using the `file` element.
+
+In Visual Studio when you generate a ClickOnce manifest using the Publish process, you might get this warning if you specify a DLL or EXE with the `Build Action` set to `Content`. In Visual Studio, `Content` means add something as an ordinary file, not as an assembly. In a project file, `Content` is an item group. If the item group contains files that look like assemblies, you get this warning.
+
+## Resolution
+
+Check the assembly manifest XML file for the assembly given in the text of the error message. For more information, see [Assembly manifest](/dotnet/standard/assembly/manifest). You can generate a binary log to see why a particular file is being passed as an assembly. Use the `-bl` switch on the MSBuild command line, and then use the [MSBuild structured log viewer](https://msbuildlog.com) to open the binary log (`.binlog` file).
+
+If your project file contains an item group `Content` or your Visual Studio project specifies the `Build Action` as `Content` for some files with the DLL or EXE extension, consider whether this is intentional or not. 
+
+If your manifest file was generated by a custom tool or process, check any `file` elements to see if any of them reference files that should be referenced as assemblies instead (look for file extensions such as `.dll` or `.exe`.). If it was generated by a tool or MSBuild task, check the command line syntax, shell expansions, and validate any input files to the tool or task.
+
+You can disable this warning by using the `NoWarn` property:
+
+`<NoWarn>$(NoWarn);MSB3178</NoWarn>`
+
+You should only disable the warning if you've verified that including what appear to be assemblies as ordinary files is valid and intentional in your scenario.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3501.md b/docs/msbuild/errors/msb3501.md
@@ -35,6 +35,16 @@ This article describes the MSB3501 error code.
 <!--
 {StrBegin="MSB3501: "}
 -->
+## Description
+
+This error occurs when your project is using the [`ReadLinesFromFile` task](../readlinesfromfile-task.md), but the specified file wasn't found.
+
+## Resolution
+
+Check the input to the `ReadLinesFromFile` task. You can use the `-v:diag` switch on the MSBuild command line to get more detailed information about the MSBuild execution, such as the values of the input parameters provided to the `ReadLinesFromFile` task. In Visual Studio, in **Tools, Options, Build and Run**, set **Verbosity** to **Diagnostic**.
+
+If the input comes from a property value, check that the property has a value. If it comes from a property set at the command line, check that the syntax of the command line and the value of the environment variable are correct; especially check shell escape characters and ensure proper use of quotes, especially the need for quotes when providing filenames with spaces in the path. If the input file comes from an environment variable, check the spelling of the environment value and verify that it has the expected value.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3823.md b/docs/msbuild/errors/msb3823.md
@@ -35,6 +35,14 @@ This article describes the MSB3823 error code.
 <!--
 {StrBegin="MSB3823: "}
 -->
+## Description
+
+There's a difference in how nonstring resources are serialized and deserialized between .NET Framework and .NET Core. In .NET Framework applications, resources are both deserialized and then preserialized, which isn't efficient, but was meant to handle diverse serialization and deserialization techniques. In .NET Core, the extra steps are avoided. However, you can also opt in to preserialization for .NET Framework projects, by setting the property mentioned in the error message.
+
+## Resolution
+
+If you want to use preserialized resources in a .NET Framework project, you must add a reference to the [System.Resources.Extensions](https://www.nuget.org/packages/System.Resources.Extensions) NuGet package, and also set the property `GenerateResourceUsePreserializedResources` to true.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3825.md b/docs/msbuild/errors/msb3825.md
@@ -21,7 +21,7 @@ ms.subservice: msbuild
 
 <!-- :::ErrorDefinitionDescription::: -->
 <!-- :::editable-content name="introDescription"::: -->
-This article describes the MSB3825 error code.
+This article describes the MSB3825 warning code.
 <!-- :::editable-content-end::: -->
 
 ## Message text
@@ -37,9 +37,30 @@ This article describes the MSB3825 error code.
 <!--
 {StrBegin="MSB3825: "}
 -->
+## Description
+
+This warning occurs with .NET 8 and earlier. The deprecated .NET type <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter>, previously commonly used for serializing and deserializing arbitrary .NET types, isn't considered secure, because it allows arbitrary .NET types to be injected into an assembly via the deserialization process.
+
+.NET 9 handles BinaryFormatter using a secure algorithm, so there's no issue when using .NET 9.
+
+## Resolution
+
+If you upgrade to .NET 9, you won't get this warning for resources, but may have to implement another solution if another part of your code uses `BinaryFormatter`. See the [migration guide](https://aka.ms/binaryformatter-migration-guide) for alternatives to `BinaryFormatter`.
+
+For .NET 8 and earlier, you can suppress the warning either by setting the `GenerateResourceWarnOnBinaryFormatterUse` property to false, as mentioned in the message, or by setting the `$(NoWarn)` property to a property group in your project file, as follows:
+
+```xml
+<PropertyGroup>
+   <!-- other properties -->
+   <GenerateResourceWarnOnBinaryFormatterUse>false<GenerateResourceWarnOnBinaryFormatterUse>
+   <!-- or -->
+   <NoWarn>$(NoWarn);MSB3825</NoWarn>
+</PropertyGroup>
+```
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
 ## Applies to
 
-All versions of MSBuild
+All recent versions of MSBuild
diff --git a/docs/msbuild/errors/msb3883.md b/docs/msbuild/errors/msb3883.md
@@ -35,6 +35,14 @@ This article describes the MSB3883 error code.
 <!--
 {StrBegin="MSB3883: "}
 -->
+## Description
+
+This error is emitted by the [C# compiler task - Csc](../csc-task.md), when an exception occurs in the C# compilation process that wasn't otherwise handled.
+
+## Resolution
+
+This error should never occur during normal operations; if it does occur, you should report it at [Dev Community](https://developercommunity.visualstudio.com/dotnet) or at the [Roslyn](https://github.com/dotnet/roslyn/issues) project at GitHub.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3941.md b/docs/msbuild/errors/msb3941.md
@@ -35,6 +35,18 @@ This article describes the MSB3941 error code.
 <!--
 {StrBegin="MSB3941: "}
 -->
+## Description
+
+This error occurs when your project uses the [`ZipDirectory` task](../zipdirectory-task.md), which takes an input directory and produces a compressed ZIP file, but the input directory could not be found or accessed.
+
+## Resolution
+
+You can use the `-v:diag` switch on the MSBuild command line to get more detailed information about the MSBuild execution, such as the values of the input parameters provided to the `ZipDirectory` task. In Visual Studio, in **Tools, Options, Build and Run**, set **Verbosity** to **Diagnostic**.
+
+Check the spelling and syntax of the input parameters of the ZipDirectory task, which might be called from your project file (it is not called by the MSBuild, C++, or .NET SDK build system), a file that your project imports. Verify that the folder exists and allows read permissions. If your `ZipDirectory` task uses a property value or environment variable in its input, check that the property or environment variable has the expected value. If the property comes from a command line, check the command line for any syntax issues, mismatched quotes, or special shell characters.
+
+Check that the directory allows `Read` permissions to the process that runs MSBuild.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4220.md b/docs/msbuild/errors/msb4220.md
@@ -35,6 +35,15 @@ This article describes the MSB4220 error code.
 <!--
 {StrBegin="MSB4220: "}
 -->
+## Description
+
+This error occurs when you try to stop a build, but a long-running task that is not designed to be cancelable can't be stopped by MSBuild. In such cases, MSBuild's policy is not to cancel the task, because that would leave a project in an undefined state, perhaps with partially written files, that could corrupt subsequent builds.
+
+## Resolution
+
+In current versions, MSBuild built-in tasks generally support clean cancellation. However, this is up to the task author, or the author of the target or the SDK that packages the targets and tasks. If the issue persists, you could try upgrading to the most recent versions of SDKs you're using to see if the task was updated to support cancelability.
+
+If you're the author of the task, consider implementing the <xref:Microsoft.Build.Framework.ICancelableTask> interface, so that your task supports cancellation. If you're consuming a task from an SDK or a third-party provider of a target, then you can contact the owner and ask them to implement `ICancellableTask` in a future version of the task.
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4226.md b/docs/msbuild/errors/msb4226.md
@@ -40,6 +40,14 @@ MSB4226: The imported project "{0}" was not found. Also, tried to find "{1}" in
 
 {StrBegin="MSB4226: "}LOCALIZATION: <Import> should not be localized.
 -->
+## Description
+
+This error occurs when MSBuild tries to import a file, but the file couldn't be found. The fallback paths mentioned in the error text are only relevant for Visual Studio 2015 and earlier. If you're using a newer version of Visual Studio and MSBuild, you can ignore the information about fallback search paths.
+
+## Resolution
+
+See the guidance for [MSB4019](./msb4019.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4249.md b/docs/msbuild/errors/msb4249.md
@@ -35,6 +35,14 @@ This article describes the MSB4249 error code.
 <!--
 {StrBegin="MSB4249: "}
 -->
+## Description
+
+The error occurs when you try to build an ASP.NET project (prior to ASP.NET Core) that targets the .NET Framework, by using the `dotnet` command-line tool. The `dotnet` command-line tool is built for .NET Core (and .NET 5 and later) and doesn't support this legacy project type.
+
+## Resolution
+
+You can use Visual Studio or MSBuild.exe to build legacy ASP.NET projects.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
