Merge pull request #10832 from MicrosoftDocs/main638856938425303435sync_temp

For protected branch, push strategy should use PR and merge to target branch method to work around git push error

Author: learn-build-service-prod[bot]

docs/debugger/using-dump-files.md

@@ -1,7 +1,7 @@
 ---
 title: "Use dump files in the debugger"
 description: A dump file is a snapshot of an executing app and loaded modules. Consider creating a dump file for situations where you don't have debug access to the app.
-ms.date: "06/27/2024"
+ms.date: "06/09/2025"
 ms.topic: "conceptual"
 f1_keywords:
   - "vs.debug.crashdump"
@@ -84,8 +84,9 @@ With [Just-In-Time Debugging](../debugger/just-in-time-debugging-in-visual-studi
 1. Under **Actions**:
 
    - To set symbol loading locations, select **Set symbol paths**.
-   - To start debugging, select **Debug with Managed Only**, **Debug with Mixed**, **Debug with Native Only**, or **Debug Managed Memory**. To analyze managed memory, see [Managed type reports](../profiling/memory-usage-without-debugging2.md#managed-types-reports).
-   - To get memory analysis on the dump, select **Run Diagnostic Analysis** and see [Debug a managed memory dump with .NET Diagnostic Analyzers](../debugger/how-to-debug-managed-memory-dump.md).
+   - To start debugging, select **Debug with Managed Only**, **Debug with Mixed**, **Debug with Native Only**.
+   - To analyze managed memory, select **Debug Managed Memory** and see [Managed type reports](../profiling/memory-usage-without-debugging2.md#managed-types-reports).
+   - To run a memory analyzer on the dump, select **Run Diagnostic Analysis** and see [Debug a managed memory dump with .NET Diagnostic Analyzers](../debugger/how-to-debug-managed-memory-dump.md).
 
 ## <a name="BKMK_Find_binaries__symbol___pdb__files__and_source_files"></a> Find .exe, .pdb, and source files
 

docs/extensibility/adding-an-lsp-extension.md

@@ -368,7 +368,7 @@ When tracing is turned on the content is written to a file in the *%temp%\Visual
 
 ### Custom messages
 
-There are APIs in place to facilitate passing messages to and receiving messages from the language server that are not part of the standard Language Server Protocol. To handle custom messages, implement [ILanguageClientCustomMessage2](/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage2) interface in your language client class. [VS-StreamJsonRpc](https://github.com/Microsoft/vs-streamjsonrpc/blob/main/doc/index.md) library is used to transmit custom messages between your language client and language server. Since your LSP language client extension is just like any other Visual Studio extension, you can decide to add additional features (that are not supported by the LSP) to Visual Studio (using other Visual Studio APIs) in your extension through custom messages.
+There are APIs in place to facilitate passing messages to and receiving messages from the language server that are not part of the standard Language Server Protocol. To handle custom messages, implement [ILanguageClientCustomMessage2](/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage2) interface in your language client class. [VS-StreamJsonRpc](https://github.com/microsoft/vs-streamjsonrpc/blob/main/docfx/index.md) library is used to transmit custom messages between your language client and language server. Since your LSP language client extension is just like any other Visual Studio extension, you can decide to add additional features (that are not supported by the LSP) to Visual Studio (using other Visual Studio APIs) in your extension through custom messages.
 
 #### Receive custom messages
 
@@ -409,7 +409,7 @@ internal class MockCustomLanguageClient : MockLanguageClient, ILanguageClientCus
 
 #### Send custom messages
 
-To send custom messages to the language server, implement the [AttachForCustomMessageAsync](/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage2.attachforcustommessageasync) method on [ILanguageClientCustomMessage2](/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage2). This method is invoked when your language server is started and ready to receive messages. A [JsonRpc](https://github.com/Microsoft/vs-streamjsonrpc/blob/main/src/StreamJsonRpc/JsonRpc.cs) object is passed as a parameter, which you can then keep to send messages to the language server using [VS-StreamJsonRpc](https://github.com/Microsoft/vs-streamjsonrpc/blob/main/doc/index.md) APIs. Example below:
+To send custom messages to the language server, implement the [AttachForCustomMessageAsync](/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage2.attachforcustommessageasync) method on [ILanguageClientCustomMessage2](/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage2). This method is invoked when your language server is started and ready to receive messages. A [JsonRpc](https://github.com/Microsoft/vs-streamjsonrpc/blob/main/src/StreamJsonRpc/JsonRpc.cs) object is passed as a parameter, which you can then keep to send messages to the language server using [VS-StreamJsonRpc](https://github.com/microsoft/vs-streamjsonrpc/blob/main/docfx/index.md) APIs. Example below:
 
 ```csharp
 internal class MockCustomLanguageClient : MockLanguageClient, ILanguageClientCustomMessage2

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

@@ -22,7 +22,7 @@ This article lists all the common project items defined in MSBuild itself. Items
 
 ## `Reference`
 
-Represents an assembly (managed) reference in the project.
+Represents a .NET assembly (managed) reference in the project.
 
 |Item metadata name|Description|
 |---------------|-----------------|
@@ -33,9 +33,14 @@ Represents an assembly (managed) reference in the project.
 |Aliases|Optional string. Any aliases for the reference.|
 |Private|Optional boolean. Specifies whether the reference should be copied to the output folder. This attribute matches the **Copy Local** property of the reference that's in the Visual Studio IDE.|
 
+> [!NOTE]
+> The `Reference` item type can also be use to reference pregenerated wrapper assemblies for native COM objects, for example, if you used [`tlbimp.exe`](/dotnet/framework/tools/tlbimp-exe-type-library-importer) to generate a PIA (Primary Interop Assembly). This type of reference is an appropriate choice when you want to pregenerate the COM wrapper assemblies yourself with known inputs, instead of relying on MSBuild's algorithm to generate COM wrappers at build time, which introduces a dependency on the state of the system registry on the build machine where MSBuild is run. 
+
 ## COMReference
 
-Represents a COM (unmanaged) component reference in the project. This item applies only to .NET projects.
+Represents a COM (unmanaged) component reference in the project. This item is used by the [ResolveComReference task](./resolvecomreference-task.md), which generates the wrapper assemblies, or, if `EmbedInteropTypes` is used, embeds the interop types in your assembly. Using this type of reference introduces a dependency on the system registry on the build machine, which is used to look up the referenced COM object. COM artifacts and COM entries in the registry can change when products are installed, updated, or uninstalled on the machine (or when you run the same build on a different machine), potentially producing a different wrapper assembly even if the build logic hasn't changed.
+
+This item doesn't apply to non-.NET projects.
 
 |Item metadata name|Description|
 |---------------|-----------------|
@@ -50,7 +55,9 @@ Represents a COM (unmanaged) component reference in the project. This item appli
 
 ## COMFileReference
 
-Represents a list of type libraries that are passed to the `TypeLibFiles` parameter of the [ResolveComReference](resolvecomreference-task.md) target. This item applies only to .NET projects.
+Represents a list of type libraries to reference by file path, instead of using the system registry. This type of reference can be a good alternative to COMReference in cases where you want to avoid a dependency on the build machine's registry, either because the account that runs the build doesn't have elevated privileges to edit the registry on the build server, or you don't want the build to have a dependency on the state of the registry. If you use `COMFileReference` to reference an artifact on a system path, then your build has a dependency on the system state. If the system artifact changes due to a change in the state of the system, such as when products are installed, updated, or uninstalled (or if you run the same build on a different machine), then the wrapper assembly can change, even if the build logic hasn't changed. To ensure a consistent build result, you can cache a known copy of the COM artifact in a place you control, such as under your project or solution folder, and reference that instead of the system artifact.
+
+This item doesn't apply to non-.NET projects.
 
 |Item metadata name|Description|
 |---------------|-----------------|

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::: -->