Merge main into live

docfx.json

@@ -834,7 +834,11 @@
                 "docs/core/porting/github-copilot-app-modernization/**/**.{md,yml}": "ce-skilling-ai-copilot"
             },
             "ms.custom": {
-                "docs/ai/**/**.{md,yml}": "devx-track-dotnet"
+                "docs/ai/**/**.{md,yml}": "devx-track-dotnet",
+                "docs/core/testing/*microsoft-testing-platform*.md": "microsoft-testing-platform",
+                "docs/core/testing/test-platforms-overview.md": "microsoft-testing-platform",
+                "docs/core/testing/unit-testing-with-dotnet-test.md": "microsoft-testing-platform",
+                "docs/core/tools/dotnet-test-mtp.md": "microsoft-testing-platform"
             },
             "ms.update-cycle": {
                 "docs/ai/**/**.{md,yml}": "180-days",

docs/core/sdk/file-based-apps.md

@@ -318,7 +318,7 @@ Enable direct execution of file-based apps on Unix-like systems by using a sheba
 Add a shebang at the top of your file:
 
 ```csharp
-#!/usr/bin/env dotnet
+#!/usr/bin/env -S dotnet --
 #:package Spectre.Console
 
 using Spectre.Console;
@@ -341,6 +341,11 @@ Run directly:
 > [!NOTE]
 > Use `LF` line endings instead of `CRLF` when you add a shebang. Don't include a BOM in the file.
 
+To prevent `dotnet` from consuming arguments that match its own parameters (such as `--help`), the shebang uses `--` as a separator. The `--` separator tells `dotnet` to forward all subsequent command-line arguments directly to your app. The `-S` flag lets `env` split the remaining text into separate arguments so you can include `--` in the shebang.
+
+> [!NOTE]
+> If `-S` isn't supported on your system, use `#!/usr/bin/env dotnet` instead. With this shebang, `dotnet` might consume arguments that match its own CLI parameters.
+
 ## Implicit build files
 
 File-based apps respect MSBuild and NuGet configuration files in the same directory or parent directories. These files affect how the SDK builds your application. Be mindful of these files when organizing your file-based apps.

docs/core/testing/microsoft-testing-platform-intro.md

@@ -1,6 +1,6 @@
 ---
-title: Microsoft.Testing.Platform overview
-description: Learn about Microsoft.Testing.Platform, a lightweight way to run tests without depending on the .NET SDK.
+title: Microsoft.Testing.Platform overview - .NET test runner
+description: Learn about Microsoft.Testing.Platform (MTP), a lightweight and portable .NET test runner and VSTest alternative for running unit tests in CI pipelines, CLI, and IDEs.
 author: Evangelink
 ms.author: amauryleve
 ms.date: 03/17/2024

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

@@ -1,6 +1,6 @@
 ---
 title: Migration guide from VSTest to Microsoft.Testing.Platform (MTP)
-description: Learn how to migrate from VSTest to MTP
+description: Step-by-step guide to migrate from VSTest to Microsoft.Testing.Platform (MTP), including argument mapping, project configuration, and CI pipeline updates.
 author: Youssef1313
 ms.author: ygerges
 ms.date: 09/15/2025

docs/core/testing/test-platforms-overview.md

@@ -1,6 +1,6 @@
 ---
-title: Test platforms overview for .NET
-description: Learn how VSTest and Microsoft.Testing.Platform (MTP) differ, and choose the right test platform for your .NET test projects.
+title: Microsoft.Testing.Platform vs VSTest - .NET test platform comparison
+description: Compare Microsoft.Testing.Platform (MTP) and VSTest to choose the right .NET test platform for your projects, CI pipelines, and IDE integration.
 author: Evangelink
 ms.author: amauryleve
 ms.date: 02/24/2026

docs/csharp/fundamentals/tutorials/file-based-programs.md

@@ -10,6 +10,7 @@ ai-usage: ai-assisted
 # Tutorial: Build file-based C# programs
 
 *File-based apps* are programs contained within a single `*.cs` file that you build and run without a corresponding project (`*.csproj`) file. File-based apps are ideal for learning C# because they have less complexity: The entire program is stored in a single file. File-based apps are also useful for building command line utilities. On Unix platforms, you can run file-based apps by using `#!` (shebang) [directives](../../language-reference/preprocessor-directives.md).
+
 In this tutorial, you:
 
 > [!div class="checklist"]
@@ -80,16 +81,13 @@ On Unix, you can execute file-based apps directly using just the source file nam
 1. Add a shebang (`#!`) directive as the first line of the `AsciiArt.cs` file:
 
    ```csharp
-   #!/usr/local/share/dotnet/dotnet
+   #!/usr/bin/env -S dotnet --
    ```
 
-The location of `dotnet` can be different on different Unix installations. Use the command `which dotnet` to locate the `dotnet` host in your environment.
-
-Alternatively, you can use `#!/usr/bin/env dotnet` to resolve the dotnet path from the PATH environment variable automatically:
+   This shebang uses `env` to find `dotnet` in the PATH environment. The `-S` parameter enables `env` to pass `dotnet` and `--` as separate arguments. The `--` ensures that any arguments a user provides are passed directly to your app, preventing `dotnet` from consuming them by mistake.
 
-```csharp
-#!/usr/bin/env dotnet
-```
+   > [!TIP]
+   > If the previous shebang doesn't work, try `#!/usr/bin/env dotnet` or the exact location of `dotnet`, for example `#!/usr/local/share/dotnet/dotnet --`.
 
 After making these two changes, you can run the program directly:
 

docs/csharp/fundamentals/tutorials/snippets/file-based-programs/AsciiArt.cs

@@ -1,4 +1,4 @@
-#!/usr/bin/env dotnet
+#!/usr/bin/env -S dotnet --
 
 // <ColorfulPackage>
 #:package Colorful.Console@1.2.15

docs/fundamentals/toc.yml

@@ -967,6 +967,8 @@ items:
                 href: ../standard/io/how-to-add-or-remove-access-control-list-entries.md
               - name: "How to: Compress and Extract Files"
                 href: ../standard/io/how-to-compress-and-extract-files.md
+              - name: ZIP and TAR best practices
+                href: ../standard/io/zip-tar-best-practices.md
               - name: Composing Streams
                 href: ../standard/io/composing-streams.md
               - name: "How to: Convert Between .NET Framework Streams and Windows Runtime Streams"

docs/navigate/devops-testing/toc.yml

@@ -32,7 +32,7 @@ items:
             href: ../../devops/dotnet-secure-github-action.md
             displayName: codeql,security,vulnerability,source scan
   - name: Testing
-    displayName: xUnit,NUnit,MSTest,unit test,test,integration test,load test,smoke test, web test
+    displayName: xUnit,NUnit,MSTest,unit test,test,integration test,load test,smoke test,web test,Microsoft.Testing.Platform,MTP,testing platform,test runner
     items:
       - name: Overview
         href: ../../core/testing/index.md
@@ -257,60 +257,88 @@ items:
         items:
           - name: Overview
             href: ../../core/testing/test-platforms-overview.md
+            displayName: MTP vs VSTest,compare test platforms,choose test platform
           - name: Microsoft.Testing.Platform
+            displayName: MTP,testing platform,.NET test runner,VSTest alternative
             items:
               - name: Overview
                 href: ../../core/testing/microsoft-testing-platform-intro.md
+                displayName: MTP,testing platform,test runner,VSTest alternative
               - name: Run and debug tests
                 href: ../../core/testing/microsoft-testing-platform-run-and-debug.md
+                displayName: MTP,run tests,debug tests,dotnet test,CI pipeline
               - name: CLI options reference
                 href: ../../core/testing/microsoft-testing-platform-cli-options.md
+                displayName: MTP,command line,CLI,options,arguments,switches
               - name: Configuration
                 href: ../../core/testing/microsoft-testing-platform-config.md
+                displayName: MTP,testconfig.json,configuration,settings
               - name: Troubleshooting
                 href: ../../core/testing/microsoft-testing-platform-troubleshooting.md
+                displayName: MTP,exit codes,errors,troubleshoot
               - name: Features
+                displayName: MTP features,extensions,NuGet
                 items:
                   - name: Overview
                     href: ../../core/testing/microsoft-testing-platform-features.md
+                    displayName: MTP features,extensions
                   - name: Terminal output
                     href: ../../core/testing/microsoft-testing-platform-terminal-output.md
+                    displayName: MTP,terminal,test reporter,ANSI,progress
                   - name: Test reports
                     href: ../../core/testing/microsoft-testing-platform-test-reports.md
+                    displayName: MTP,TRX,test report,Azure DevOps
                   - name: Code coverage
                     href: ../../core/testing/microsoft-testing-platform-code-coverage.md
+                    displayName: MTP,code coverage,coverage
                   - name: Crash and hang dumps
                     href: ../../core/testing/microsoft-testing-platform-crash-hang-dumps.md
+                    displayName: MTP,crash dump,hang dump,diagnostics
                   - name: OpenTelemetry
                     href: ../../core/testing/microsoft-testing-platform-open-telemetry.md
+                    displayName: MTP,OpenTelemetry,traces,metrics
                   - name: Retry
                     href: ../../core/testing/microsoft-testing-platform-retry.md
+                    displayName: MTP,retry,flaky tests
                   - name: Hot Reload
                     href: ../../core/testing/microsoft-testing-platform-hot-reload.md
+                    displayName: MTP,hot reload,live reload
                   - name: Microsoft Fakes
                     href: ../../core/testing/microsoft-testing-platform-fakes.md
+                    displayName: MTP,fakes,shims,stubs
                   - name: Telemetry
                     href: ../../core/testing/microsoft-testing-platform-telemetry.md
+                    displayName: MTP,telemetry,opt out
               - name: Migration
+                displayName: MTP,migrate,VSTest migration
                 items:
                   - name: Migrate from VSTest
                     href: ../../core/testing/migrating-vstest-microsoft-testing-platform.md
+                    displayName: MTP,VSTest,migration,migrate,switch
                   - name: Migrate from MTP v1 to v2
                     href: ../../core/testing/microsoft-testing-platform-migration-from-v1-to-v2.md
+                    displayName: MTP v2,upgrade,breaking changes
               - name: Create custom extensions
+                displayName: MTP,extensibility,custom extensions
                 items:
                   - name: Overview
                     href: ../../core/testing/microsoft-testing-platform-architecture.md
+                    displayName: MTP,architecture,custom test framework,extensibility
                   - name: Build a test framework
                     href: ../../core/testing/microsoft-testing-platform-architecture-test-framework.md
+                    displayName: MTP,custom test framework,ITestFramework
                   - name: VSTest Bridge
                     href: ../../core/testing/microsoft-testing-platform-extensions-vstest-bridge.md
+                    displayName: MTP,VSTest bridge,backward compatibility
                   - name: Build extensions
                     href: ../../core/testing/microsoft-testing-platform-architecture-extensions.md
+                    displayName: MTP,extensions,in-process,out-of-process
                   - name: Capabilities
                     href: ../../core/testing/microsoft-testing-platform-architecture-capabilities.md
+                    displayName: MTP,capabilities
                   - name: Services
                     href: ../../core/testing/microsoft-testing-platform-architecture-services.md
+                    displayName: MTP,services,IServiceProvider
           - name: VSTest
             href: https://github.com/microsoft/vstest
       - name: Testing with 'dotnet test'

docs/standard/commandline/get-started-tutorial.md

@@ -340,11 +340,10 @@ scl quotes delete --search-terms David "You can do" Antoine "Perfection is achie
 
    :::code language="csharp" source="snippets/get-started-tutorial/csharp/Stage3/Program.cs" id="fileoption" :::
 
-   This code uses <xref:System.CommandLine.Parsing.ArgumentResult> to provide custom parsing, validation, and error handling.
+   This code uses two separate mechanisms:
 
-   Without this code, missing files are reported with an exception and stack trace. With this code just the specified error message is displayed.
-
-   This code also specifies a default value, which is why it sets <xref:System.CommandLine.Option`1.DefaultValueFactory?displayProperty=nameWithType> to custom parsing method.
+   * <xref:System.CommandLine.Option`1.DefaultValueFactory?displayProperty=nameWithType> supplies `sampleQuotes.txt` as the default when you don't provide `--file`. `DefaultValueFactory` doesn't run when you do provide `--file`.
+   * <xref:System.CommandLine.Option`1.CustomParser?displayProperty=nameWithType> runs when you explicitly provide `--file`. It converts the token to a `FileInfo` and validates that the file exists. Without validation, a missing file would cause an unhandled `FileNotFoundException` with a stack trace. With validation, just the specified error message is displayed.
 
 1. After the code that creates `lightModeOption`, add options and arguments for the `add` and `delete` commands:
 

docs/standard/commandline/snippets/get-started-tutorial/csharp/Stage3/Program.cs

@@ -11,24 +11,15 @@ static int Main(string[] args)
         Option<FileInfo> fileOption = new("--file")
         {
             Description = "An option whose argument is parsed as a FileInfo",
-            Required = true,
-            DefaultValueFactory = result =>
+            DefaultValueFactory = _ => new FileInfo("sampleQuotes.txt"),
+            CustomParser = result =>
             {
-                if (result.Tokens.Count == 0)
-                {
-                    return new FileInfo("sampleQuotes.txt");
-
-                }
-                string filePath = result.Tokens.Single().Value;
-                if (!File.Exists(filePath))
+                var file = new FileInfo(result.Tokens.Single().Value);
+                if (!file.Exists)
                 {
                     result.AddError("File does not exist");
-                    return null;
-                }
-                else
-                {
-                    return new FileInfo(filePath);
                 }
+                return file;
             }
         };
         // </fileoption>