Add test debugging instructions, tasks, and launch profiles (#6062)

.gitignore

@@ -13,7 +13,9 @@ artifacts/
 .vs/
 
 # Visual Studio Code cache/options directory
-.vscode/
+.vscode/*
+!.vscode/tasks.json
+!.vscode/launch.json
 
 # Test files
 *.trx

.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+    // Launch configurations documentation: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Attach .NET Debugger",
+            "type": "coreclr",
+            "request": "attach"
+        },
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,98 @@
+{
+    // Tasks documentation: https://go.microsoft.com/fwlink/?LinkId=733558
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Generate Dockerfiles",
+            "type": "shell",
+            "command": "pwsh ./eng/dockerfile-templates/Get-GeneratedDockerfiles.ps1",
+            "group": "build",
+            "problemMatcher": [
+                {
+                    "owner": "generate-dockerfiles",
+                    "fileLocation": [
+                        "relative",
+                        "${workspaceFolder}"
+                    ],
+                    "pattern": [
+                        {
+                            "regexp": "^(?: )*Template parsing error in file (.*):(.*)(?: )*$",
+                            "file": 1,
+                            "location": 2
+                        },
+                        {
+                            "regexp": "^(?: )*Message: (.*)$",
+                            "message": 1
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "label": "Generate Readmes",
+            "type": "shell",
+            "command": "pwsh ./eng/readme-templates/Get-GeneratedReadmes.ps1",
+            "group": "build",
+            "problemMatcher": [
+                {
+                    "owner": "generate-readmes",
+                    "fileLocation": [
+                        "relative",
+                        "${workspaceFolder}"
+                    ],
+                    "pattern": [
+                        {
+                            "regexp": "^(?: )*Template parsing error in file (.*):(.*)(?: )*$",
+                            "file": 1,
+                            "location": 2
+                        },
+                        {
+                            "regexp": "^(?: )*Message: (.*)$",
+                            "message": 1
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "label": "Test with debugger",
+            "type": "process",
+            "isBackground": true,
+            "command": "dotnet",
+            "args": [
+                "test",
+                "--filter",
+                "\"Category=runtime-deps|Category=runtime|Category=aspnet|Category=sdk|Category=monitor|Category=aspire-dashboard\"",
+
+                // Filter by fully qualified test name:
+                // "--filter",
+                // "\"VerifyFxDependentAppScenario&(Category=runtime|Category=aspnet)\"",
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}/tests/Microsoft.DotNet.Docker.Tests",
+                "env":
+                {
+                    "IMAGE_ARCH": "amd64",
+                    "SOURCE_BRANCH": "nightly",
+                    "SOURCE_REPO_ROOT": "${workspaceFolder}",
+                    "VSTEST_HOST_DEBUG": "1",
+                    "DOTNET_CLI_TELEMETRY_OPTOUT": "1",
+                    "DOTNET_SKIP_FIRST_TIME_EXPERIENCE": "1",
+                    "DOTNET_MULTILEVEL_LOOKUP": "0",
+
+                    // Uncomment to specify optional environment variables:
+                    // "DOCKERFILE_PATHS": "*",
+                    // "PULL_IMAGES": "true",
+                }
+            },
+            "group": "test",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "shared"
+            },
+            "problemMatcher": []
+        },
+    ]
+}

CONTRIBUTING.md

@@ -39,9 +39,7 @@ However, if you'd still like to implement it yourself, you can request the issue
 
 When making PRs, all source code changes (e.g. Dockerfiles, tests, and infrastructure) should be made in the [nightly branch](https://github.com/dotnet/dotnet-docker/tree/nightly). Only changes to the samples and documentation will be accepted against the [main branch](https://github.com/dotnet/dotnet-docker/tree/main).
 
-### Workflow Instructions
-
-#### Building
+### Building
 
 The [`build-and-test.ps1`](https://github.com/dotnet/dotnet-docker/blob/main/build-and-test.ps1) script will build and test the .NET Docker images. Given the matrix of supported .NET versions, distros, and architectures there are numerous Dockerfiles and building can take a while. To make this manageable, the script supports several options for filtering down what images get built and tested.
 
@@ -69,15 +67,15 @@ The [`build-and-test.ps1`](https://github.com/dotnet/dotnet-docker/blob/main/bui
     > ./build-and-test.ps1 -Version 9.0 -OS noble -Mode Test
     ```
 
-#### Editing Dockerfiles
+### Editing Dockerfiles
 
 The [Dockerfiles](https://github.com/search?q=repo%3Adotnet%2Fdotnet-docker+path%3Asrc%2F**%2FDockerfile&type=code&ref=advsearch) contained in this repo are generated from a set of [Cottle](https://cottle.readthedocs.io/en/stable/page/01-overview.html) based [templates](https://github.com/dotnet/dotnet-docker/tree/main/eng/dockerfile-templates). A single template generates the set of Dockerfiles that are similar (e.g. all Windows sdk Dockerfiles for a particular .NET version).  This ensures consistency across the various Dockerfiles and eases the burden of making changes to the Dockerfiles.  Instead of editing the Dockerfiles directly, the templates should be updated and then the Dockerfiles should get regenerated by running the [generate Dockerfiles script](https://github.com/dotnet/dotnet-docker/blob/main/eng/dockerfile-templates/Get-GeneratedDockerfiles.ps1).
 
-#### Editing READMEs
+### Editing READMEs
 
 The [READMEs](https://github.com/search?q=repo%3Adotnet%2Fdotnet-docker+path%3A**%2FREADME*+-path%3Aeng+-path%3Asamples&type=code&ref=advsearch&p=1) contained in this repo are used as the descriptions for the Docker repositories the images are published to.  Just like the Dockerfiles, the READMEs are generated from a set of [Cottle](https://cottle.readthedocs.io/en/stable/page/01-overview.html) based [templates](https://github.com/dotnet/dotnet-docker/tree/main/eng/readme-templates).  This ensures consistency across the various READMEs and eases the burden of making changes.  Instead of editing the READMEs directly, the templates should be updated and then the READMEs should get regenerated by running the [generate READMEs script](https://github.com/dotnet/dotnet-docker/blob/main/eng/readme-templates/Get-GeneratedReadmes.ps1).
 
-#### Tests
+### Tests
 
 There are two basic types of [tests](https://github.com/dotnet/dotnet-docker/tree/main/tests) for each of the images produced from this repo.
 
@@ -86,7 +84,32 @@ There are two basic types of [tests](https://github.com/dotnet/dotnet-docker/tre
 
 When editing Dockerfiles, please ensure the appropriate test changes are also made.
 
-#### Metadata Changes
+#### Debugging Tests Using VS Code
+
+This repo comes with VS Code Task and Launch Profiles to help you debug tests.
+
+To start, open [tasks.json](.vscode/tasks.json) and find the "Test with debugger" task.
+Check the `args` and `env` settings to filter down to the exact image you want to test.
+
+To filter tests to a specific image, use the `DOCKERFILE_PATHS` environment variable.
+For example, to test only Alpine 3.20 ASP.NET images, you could set the `DOCKERFILE_PATHS` to `src/aspnet/9.0/alpine3.20/amd64`.
+To run specific individual tests, you can use [Xunit test filtering](https://learn.microsoft.com/dotnet/core/testing/selective-unit-tests?pivots=xunit) arguments to filter by fully qualified test name and test category.
+
+To start debugging, open the VS Code command palette and type "Tasks: Run Task", then choose the "Test with debugger" task. The terminal will open and print a process ID:
+
+```console
+Host debugging is enabled. Please attach debugger to testhost process to continue.
+Process Id: 19972, Name: testhost
+Waiting for debugger attach...
+```
+
+From the "Run and Debug" sidebar panel, run the "Attach .NET Debugger" launch configuration (once it's selected, you can quickly run it again by pressing F5).
+VS Code will prompt you for a process ID to attach to.
+Type in the PID that was printed to the terminal earlier.
+Now, VS Code is attached to the .NET Debugger.
+You can press F5 (Continue) to start test execution.
+
+### Metadata Changes
 
 The [`manifest.json`](https://github.com/dotnet/dotnet-docker/blob/main/manifest.json) contains metadata used by the engineering infrastructure to build and publish the images.  It includes information such as:
 
@@ -99,7 +122,7 @@ The [`manifest.json`](https://github.com/dotnet/dotnet-docker/blob/main/manifest
 
 When adding or removing Dockerfiles, it is important to update the `manifest.json` accordingly.
 
-#### Updating Product Versions
+### Updating Product Versions
 
 Updating the product versions (e.g. .NET runtime, ASP.NET runtime, PowerShell, etc.) contained within the images is typically performed by automation. All of the product version information is stored in the [`manifest.versions.json`](https://github.com/dotnet/dotnet-docker/blob/main/manifest.versions.json) file. The Dockerfile templates reference the product versions numbers and checksums from this file. Updating a product version involves updating the `manifest.versions.json` and regenerating the Dockerfiles. If there are cases where you need to update a product version, you can use the [update-dependencies](https://github.com/dotnet/dotnet-docker/tree/main/eng/update-dependencies) tool.  The tool will do the following: