Document MTP v1 to v2 migration

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/unit-testing-mstest-migration-v3-v4.md

@@ -6,7 +6,7 @@ ms.author: ygerges
 ms.date: 07/22/2025
 ---
 
-# Migrate from MSTest v3 to MSTest v4
+# Migrate from MSTest v3 to v4
 
 The preview version MSTest v4 is now available. This migration guide explores what's changed in MSTest v4 and how you can migrate to this version.
 

docs/navigate/devops-testing/toc.yml

@@ -71,12 +71,14 @@ items:
             items:
               - name: Overview
                 href: ../../core/testing/unit-testing-mstest-intro.md
-              - name: Migrate MSTest from v1 to v3
+              - name: Migrate from MSTest v1 to v3
                 href: ../../core/testing/unit-testing-mstest-migration-from-v1-to-v3.md
-              - name: Migrate from MSTest v3 to MSTest v4
+              - name: Migrate from MSTest v3 to v4
                 href: ../../core/testing/unit-testing-mstest-migration-v3-v4.md
               - name: Microsoft.Testing.Platform support (MSTest runner)
                 href: ../../core/testing/unit-testing-mstest-runner-intro.md
+              - name: Migrate from Microsoft.Testing.Platform v1 to v2
+                href: ../../core/testing/microsoft-testing-platform-migration-from-v1-to-v2.md
               - name: Getting started
                 items:
                   - name: Overview