Drafts created

Author: ghogen

docs/msbuild/common-msbuild-project-properties.md

@@ -1,7 +1,7 @@
 ---
 title: Common MSBuild Project Properties
 description: Learn about common MSBuild project properties that can be defined or used in project files or included in .targets files that MSBuild provides.
-ms.date: 01/18/2018
+ms.date: 4/17/2025
 ms.topic: reference
 dev_langs:
 - VB
@@ -191,6 +191,7 @@ When setting property values, keep in mind that common properties may be set, re
 | FrameworkPathOverride | Visual Basic | Specifies the location of *mscorlib.dll* and *microsoft.visualbasic.dll*. This parameter is equivalent to the `/sdkpath` switch of the *vbc.exe* compiler. |
 | GenerateDocumentationFile | .NET | A boolean parameter that indicates whether documentation is generated by the build. If `true`, the build generates documentation information and puts it in an *.xml* file together with the name of the executable file or library that the build task created. |
 | GenerateFullPaths | C# | Generate full paths for filenames in output by using the [-fullpaths](/dotnet/csharp/language-reference/compiler-options/fullpaths-compiler-option) compiler option. |
+| GenerateResourceUsePreserializedResources | .NET | When MSBuild reads `.resx` files and generates `.resources` files, indicates whether to use the preserialized resources instead of deserializing and then reserializing each resource (for backward compatibility with .NET Framework). |
 | GenerateSerializationAssemblies | .NET | Indicates whether XML serialization assemblies should be generated by *SGen.exe*, which can be set to on, auto, or off. This property is used for assemblies that target .NET Framework only. To generate XML serialization assemblies for .NET Standard or .NET Core assemblies, reference the *Microsoft.XmlSerializer.Generator* NuGet package. |
 
 | Property or parameter name | Project types | Description |

docs/msbuild/errors/msb1004.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB1004 diagnostic code"
 description: "Specify the name of the target."
-ms.date: 01/14/2025
+ms.date: 04/17/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB1004
@@ -36,6 +36,20 @@ MSB1004: Specify the name of the target.
       following the switch, as in "msbuild.exe -target:blah".
       LOCALIZATION: The prefix "MSBUILD : error MSBxxxx:" should not be localized.
 -->
+## Description
+
+This errors 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. Check for typos in the command-line syntax, and make sure that the desired target name is given after the `-targets` or `-t` switch. 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, and verify any shell expansions, and the correct syntax of escape characters.
+
+Possible targets might be defined in the project file itself. These appear as a `Target Name="MyTarget"` element in the project file. Or, you can specify one of the system-provided target files. These are files 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, you can get a list of available targets by issuing the command `MSBuild -targets`.
+
+For more information, see [MSBuild targets](../msbuild-targets.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 

docs/msbuild/errors/msb1011.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB1011 diagnostic code"
 description: "Specify which project or solution file to use because this folder contains more than one project or solution file."
-ms.date: 01/14/2025
+ms.date: 04/17/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB1011
@@ -26,9 +26,7 @@ This article describes the MSB1011 error code.
 
 ## Message text
 
-```output
-MSB1011: Specify which project or solution file to use because this folder contains more than one project or solution file.
-```
+`MSB1011: Specify which project or solution file to use because this folder contains more than one project or solution file.`
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
@@ -37,6 +35,18 @@ MSB1011: Specify which project or solution file to use because this folder conta
       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 [...]
+
+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::: -->
 

docs/msbuild/errors/msb1060.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB1060 diagnostic code"
 description: "Undefined environment variable passed in as switch."
-ms.date: 01/14/2025
+ms.date: 4/17/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB1060
@@ -27,10 +27,9 @@ This article describes the MSB1060 error code.
 
 ## Message text
 
-```output
-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 name="postOutputDescription"::: -->
 <!--
@@ -42,6 +41,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;MSBxxxx`
+
+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::: -->
 

docs/msbuild/errors/msb3091.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3091 diagnostic code"
-description: "Task failed because 'value' was not found, or the correct Microsoft Windows SDK is not installed. The task is looking for 'value' in the 'bin' subdirectory beneath the location specified in the 'value' value of the registry key 'value'. You may be able to solve the problem by doing one of the following:  1) Install the Microsoft Windows SDK.  2) Install Visual Studio 2010.  3) Manually set the above registry key to the correct location.  4) Pass the correct location into the 'ToolPath' parameter of the task."
-ms.date: 12/06/2024
+description: Learn about the possible causes of the MSB3091 MSBuild error, and get troubleshooting tips.
+ms.date: 4/17/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3091
@@ -26,14 +26,19 @@ This article describes the MSB3091 error code.
 
 ## Message text
 
-```output
-MSB3091: Task failed because 'value' was not found, or the correct Microsoft Windows SDK is not installed. The task is looking for 'value' in the 'bin' subdirectory beneath the location specified in the 'value' value of the registry key 'value'. You may be able to solve the problem by doing one of the following:  1) Install the Microsoft Windows SDK.  2) Install Visual Studio 2010.  3) Manually set the above registry key to the correct location.  4) Pass the correct location into the 'ToolPath' parameter of the task.
-```
+`MSB3091: Task failed because 'file' was not found, or the correct Microsoft Windows SDK is not installed. The task is looking for 'file' in the 'bin' subdirectory beneath the location specified in the 'value' value of the registry key 'key'. You may be able to solve the problem by doing one of the following:  1) Install the Microsoft Windows SDK.  2) Install Visual Studio 2010.  3) Manually set the above registry key to the correct location.  4) Pass the correct location into the 'ToolPath' parameter of the task.`
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {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::: -->
 

docs/msbuild/errors/msb3501.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3501 diagnostic code"
-description: "Could not read lines from file 'value'."
-ms.date: 12/06/2024
+description: Learn about the possible causes of the MSB3501 MSBuild error, and get troubleshooting tips.
+ms.date: 4/17/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3501
@@ -26,14 +26,22 @@ This article describes the MSB3501 error code.
 
 ## Message text
 
-```output
-MSB3501: Could not read lines from file 'value'.
-```
+`MSB3501: Could not read lines from file 'filename'.`
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {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 are the value of the environment variable is correct, especially check shell escape characters and ensuring 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::: -->
 

docs/msbuild/errors/msb3823.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3823 diagnostic code"
-description: "Non-string resources require the property GenerateResourceUsePreserializedResources to be set to true."
-ms.date: 12/06/2024
+description: Learn about the possible causes of the MSB3823 MSBuild error, and get troubleshooting tips.
+ms.date: 4/17/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3823
@@ -26,14 +26,20 @@ This article describes the MSB3823 error code.
 
 ## Message text
 
-```output
-MSB3823: Non-string resources require the property GenerateResourceUsePreserializedResources to be set to true.
-```
+`MSB3823: Non-string resources require the property GenerateResourceUsePreserializedResources to be set to true.`
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3823: "}
 -->
+## Description
+
+There is a difference in how non-string resources are serialized and deserialized between .NET Framework and .NET Core. In .NET Framework applications, resources are both deserialized and then preserialized, which is not 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::: -->
 

docs/msbuild/errors/msb3825.md

@@ -1,8 +1,7 @@
 ---
 title: "MSB3825 diagnostic code"
-description: "Resource 'value' of type 'value' may be deserialized via BinaryFormatter at runtime. BinaryFormatter is deprecated due to known security risks and is removed from .NET 9+. If you wish to continue using it, set property 'GenerateResourceWarnOnBinaryFormatterUse' to false.
-           More information: https://aka.ms/binaryformatter-migration-guide"
-ms.date: 12/06/2024
+description: Learn about the possible causes of the MSBuild warning MSB3825, and get troubleshooting tips.
+ms.date: 4/17/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3825
@@ -22,23 +21,43 @@ 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
 
-```output
-MSB3825: Resource 'value' of type 'value' may be deserialized via BinaryFormatter at runtime. BinaryFormatter is deprecated due to known security risks and is removed from .NET 9+. If you wish to continue using it, set property 'GenerateResourceWarnOnBinaryFormatterUse' to false.
-           More information: https://aka.ms/binaryformatter-migration-guide
-```
+`MSB3825: Resource 'value' of type 'value' may be deserialized via BinaryFormatter at runtime. BinaryFormatter is deprecated due to known security risks and is removed from .NET 9+. If you wish to continue using it, set property 'GenerateResourceWarnOnBinaryFormatterUse' to false. More information: https://aka.ms/binaryformatter-migration-guide`
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3825: "}
 -->
+## Description
+
+This warning occurs with .NET 8 and earlier. The .NET type <xref:BinaryFormatter>, previously commonly used for serializing and deserializing arbitrary .NET types, is not 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 is no issue when using .NET 9.
+
+## Resolution
+
+If you upgrade to .NET 9, you won't get this warning and your app won't be exposed to the security risk if it uses `BinaryFormatter`.
+
+For .NET 8 and earlier, see the [migration guide](https://aka.ms/binaryformatter-migration-guide) for alternatives to `BinaryFormatter`.
+
+You can also 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

docs/msbuild/errors/msb3883.md

@@ -1,7 +1,7 @@
 ---
 title: "MSB3883 diagnostic code"
 description: "Unexpected exception:"
-ms.date: 12/06/2024
+ms.date: 4/17/2025
 ms.topic: "error-reference"
 f1_keywords:
  - MSB3883
@@ -26,14 +26,20 @@ This article describes the MSB3883 error code.
 
 ## Message text
 
-```output
-MSB3883: Unexpected exception:
-```
+`MSB3883: Unexpected exception:` - usually followed by exception-specific text.
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {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::: -->