Merge main into live

docs/core/testing/index.md

@@ -39,9 +39,11 @@ When running tests in .NET, there are two components involved: the test platform
 
 ### Test platforms
 
-The test platform is the engine that runs the tests and acts as a communication channel with IDEs. For example, Visual Studio can send a discovery request to the test platform so that it can display the available tests in Test Explorer. The test platform responds back to the IDE with the tests it found. Similar communication happens for test execution.
+The test platform is the engine that runs the tests and acts as a communication channel with IDEs and CLI. For example, Visual Studio can send a discovery request to the test platform so that it can display the available tests in Test Explorer. The test platform responds back to the IDE with the tests it found. Similar communication happens for test execution.
 
-VSTest has been used for many years in .NET and was the only test platform in the ecosystem. Early in 2024, the first stable version of a new test platform, called [Microsoft.Testing.Platform (MTP)](./microsoft-testing-platform-intro.md), was released.
+VSTest has been used for many years in .NET and was the only test platform in the ecosystem. Early in 2024, the first stable version of a new test platform, called [Microsoft.Testing.Platform (MTP)](./microsoft-testing-platform-intro.md), was released. For more information about migrating from VSTest to Microsoft.Testing.Platform, see [Migration guide from VSTest to Microsoft.Testing.Platform](./migrating-vstest-microsoft-testing-platform.md).
+
+The test platform also provides extensibility APIs so that additional features can be implemented and made available for all test frameworks. There are usually built-in features built on top of the extensibility APIs, such as TRX reporting and hang and crash dumps. The community can also build custom extensions that work for all test frameworks.
 
 ### Test frameworks
 

docs/core/testing/microsoft-testing-platform-migration-from-v1-to-v2.md

@@ -0,0 +1,71 @@
+---
+title: Migrating from Microsoft.Testing.Platform v1 to v2
+description: Learn how to migrate to Microsoft.Testing.Platform v2 and understand the key changes.
+author: Youssef1313
+ms.author: ygerges
+ms.date: 10/08/2025
+---
+
+# Mirate from Microsoft.Testing.Platform v1 to v2
+
+The stable version Microsoft.Testing.Platform v2 is now available. This migration guide explores what's changed in Microsoft.Testing.Platform v2 and how you can migrate to this version.
+
+## Source breaking changes
+
+These are breaking changes that might cause build errors after migration.
+
+### Dropped unsupported target frameworks
+
+Support for target frameworks from .NET Core 3.1 to .NET 7 is dropped. The minimum supported .NET version is .NET 8.
+This change doesn't affect .NET Framework. .NET Framework 4.6.2 continues to be the minimum supported .NET Framework target.
+
+### Removed obsolete types
+
+The following types were marked obsolete in MTP v1. In MTP v2, they are removed completely:
+
+- `ITestApplicationLifecycleCallbacks`: use `ITestHostApplicationLifetime` instead.
+- `TestNodeFileArtifact`: use `FileArtifactProperty` instead.
+- `KeyValuePairStringProperty`: use `TestMetadataProperty` instead.
+- `TestSessionContext.Client`: use `IClientInfo` instead.
+
+This breaking change doesn't affect typical users of test frameworks. It only affects test framework authors and extension authors.
+
+### API signature changes
+
+- A `CancellationToken` parameter was added to <xref:Microsoft.Testing.Platform.OutputDevice.IOutputDevice.DisplayAsync(Microsoft.Testing.Platform.Extensions.OutputDevice.IOutputDeviceDataProducer,Microsoft.Testing.Platform.OutputDevice.IOutputDeviceData)?displayProperty=nameWithType>.
+- Methods in <xref:Microsoft.Testing.Platform.Extensions.TestHost.ITestSessionLifetimeHandler> interface are changed to have an `ITestSessionContext` parameter instead of both <xref:Microsoft.Testing.Platform.TestHost.SessionUid> and <xref:System.Threading.CancellationToken> parameters.
+- `IDataConsumer` is moved from `Microsoft.Testing.Platform.Extensions.TestHost` namespace to `Microsoft.Testing.Platform.Extensions`.
+
+This breaking change doesn't affect typical users of test frameworks. It only affects test framework authors and extension authors.
+
+## Behavior breaking changes
+
+These are breaking changes that might affect the behavior at run time.
+
+### Compatibility with VSTest-based `dotnet test`
+
+The `dotnet test` command has two implementations:
+
+- VSTest-based implementation: this was the only implementation up to .NET 9 SDK.
+- MTP-based implementation: this was added starting in .NET 10 SDK.
+
+Running MTP test projects with .NET 10 SDK now requires opting-in to the MTP-based `dotnet test` and can no longer be run with the VSTest-based implementation, which was previously enabled by `TestingPlatformDotnetTestSupport` MSBuild property in MTP v1.
+
+To opt-in the MTP-based implementation, create global.json in repository or solution root (or update existing global.json if you have one already), to have test runner set as Microsoft.Testing.Platform, as shown in the following example:
+
+```json
+{
+  "test": {
+    "runner": "Microsoft.Testing.Platform"
+  }
+}
+```
+
+Attempting to run the VSTest-based `dotnet test` with MTP v2 will produce the following error:
+
+> Testing with VSTest target is no longer supported by Microsoft.Testing.Platform on .NET 10 SDK and later. If you use dotnet test, you should opt-in to the new dotnet test experience. For more information, see <https://aka.ms/dotnet-test-mtp-error>
+
+### Rename of command-line options
+
+- The `--diagnostic-output-fileprefix` command-line option was renamed to `--diagnostic-file-prefix`.
+- The `--diagnostic-filelogger-synchronouswrite` command-line option was renamed to `--diagnostic-synchronous-write`.

docs/core/testing/microsoft-testing-platform-vs-vstest.md

@@ -53,80 +53,8 @@ You can also go to Preview Features options in Visual Studio and deselect the "U
 
 ## Executables
 
-VSTest ships multiple executables, notably `vstest.console.exe`, `testhost.exe`, and `datacollector.exe`. However, MSTest is embedded directly into your test project and doesn't ship any other executables. The executable your test project compiles to is used to host all the testing tools and carry out all the tasks needed to run tests.
+VSTest ships multiple executables, notably `vstest.console.exe`, `testhost.exe`, and `datacollector.exe`. However, Microsoft.Testing.Platform is embedded directly into your test project and doesn't ship any other executables. The executable your test project compiles to is used to host all the testing tools and carry out all the tasks needed to run tests.
 
-## Migrating from VSTest
+## See also
 
-In addition to the steps specific to your test framework, you need to update your test infrastructure to accommodate to `Microsoft.Testing.Platform`.
-
-### `dotnet test`
-
-Command line options of `dotnet test` are divided into 2 categories: build related arguments and test related ones.
-
-The build related arguments are passed to the `dotnet build` command and as such don't need to be updated for the new platform. Build related arguments are listed below:
-
-- `-a|--arch <ARCHITECTURE>`
-- `--artifacts-path <ARTIFACTS_DIR>`
-- `-c|--configuration <CONFIGURATION>`
-- `-f|--framework <FRAMEWORK>`
-- `-e|--environment <NAME="VALUE">`
-- `--interactive`
-- `--no-build`
-- `--nologo`
-- `--no-restore`
-- `-o|--output <OUTPUT_DIRECTORY>`
-- `--os <OS>`
-- `-r|--runtime <RUNTIME_IDENTIFIER>`
-- `-v|--verbosity <LEVEL>`
-
-The test related arguments are VSTest specific and so need to be transformed to match the new platform. The following table shows the mapping between the VSTest arguments and the new platform:
-
-| VSTest argument | New platform argument |
-|-----------------|-----------------------|
-| `--test-adapter-path <ADAPTER_PATH>` | Not supported |
-| `--blame` | Not supported |
-| `--blame-crash` | `--crashdump` requires [Crash dump extension](./microsoft-testing-platform-extensions-diagnostics.md#crash-dump) |
-| `--blame-crash-dump-type <DUMP_TYPE>` | `--crashdump-type` requires [Crash dump extension](./microsoft-testing-platform-extensions-diagnostics.md#crash-dump) |
-| `--blame-crash-collect-always` | Not supported |
-| `--blame-hang` | `--hangdump` requires [Hang dump extension](./microsoft-testing-platform-extensions-diagnostics.md#hang-dump) |
-| `--blame-hang-dump-type <DUMP_TYPE>` | `--hangdump-type` requires [Hang dump extension](./microsoft-testing-platform-extensions-diagnostics.md#hang-dump) |
-| `--blame-hang-timeout <TIMESPAN>` | `--hangdump-timeout` requires [Hang dump extension](./microsoft-testing-platform-extensions-diagnostics.md#hang-dump) |
-| `--collect <DATA_COLLECTOR_NAME>` | Depends on the data collector |
-| `-d\|--diag <LOG_FILE>` | `--diagnostic` |
-| `--filter <EXPRESSION>` | Depends upon the selected test framework |
-| `-l\|--logger <LOGGER>` | Depends on the logger |
-| `--results-directory <RESULTS_DIR>` | `--results-directory <RESULTS_DIR>` |
-| `-s\|--settings <SETTINGS_FILE>` | Depends upon the selected test framework |
-| `-t\|--list-tests` | `--list-tests` |
-| `-- <RunSettings arguments>` | `--test-parameter` (provided by [VSTestBridge](microsoft-testing-platform-extensions-vstest-bridge.md)) |
-
-> [!IMPORTANT]
-> Before specifying any `Microsoft.Testing.Platform` arguments, you need to add `--` to separate the `dotnet test` arguments from the new platform arguments. For example, `dotnet test --no-build -- --list-tests`.
-
-### `vstest.console.exe`
-
-If you are using `vstest.console.exe` directly, we recommend replacing it with the `dotnet test` command.
-
-### Test Explorer
-
-When using Visual Studio or Visual Studio Code Test Explorer, you might need to enable the support for the new test platform.
-
-#### Visual Studio
-
-Visual Studio Test Explorer supports the new test platform starting with version 17.14. If you are using an earlier version, you might need to update your Visual Studio to the latest version.
-
-#### Visual Studio Code
-
-Visual Studio Code with C# DevKit supports the new test platform.
-
-### Azure DevOps
-
-When using Azure DevOps tasks, you might need to update your pipeline to use the new test platform.
-
-#### VSTest task
-
-If you're using the [VSTest task](/azure/devops/pipelines/tasks/reference/vstest-v3) in Azure DevOps, you can replace it with the [.NET Core task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2).
-
-#### .NET Core task
-
-If you're using the [.NET Core task](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2), no changes are needed.
+- [Migration guide from VSTest to Microsoft.Testing.Platform](./migrating-vstest-microsoft-testing-platform.md)