Document AppHost launch path resolution

Author: davidfowl

extension/src/test/aspireDebugConfigurationProvider.test.ts

@@ -17,7 +17,7 @@ suite('AspireDebugConfigurationProvider', () => {
         fs.rmSync(tempDir, { recursive: true, force: true });
     });
 
-    test('resolves launch config C# AppHost source file to containing project file', async () => {
+    test('resolves launch config SDK-style AppHost Program.cs to containing project file', async () => {
         const appHostDirectory = path.join(tempDir, 'AppHost');
         fs.mkdirSync(appHostDirectory);
 
@@ -37,7 +37,7 @@ suite('AspireDebugConfigurationProvider', () => {
         assert.strictEqual(config?.program, projectPath);
     });
 
-    test('leaves launch config single-file C# AppHost source file unchanged', async () => {
+    test('leaves launch config single-file apphost.cs unchanged', async () => {
         const appHostPath = path.join(tempDir, 'apphost.cs');
         fs.writeFileSync(appHostPath, '#:sdk Aspire.AppHost.Sdk\nvar builder = DistributedApplication.CreateBuilder(args);');
 

extension/src/test/aspireEditorCommandProvider.test.ts

@@ -56,7 +56,7 @@ suite('AspireEditorCommandProvider', () => {
         fs.rmSync(tempDir, { recursive: true, force: true });
     });
 
-    test('returns containing project file for active SDK-style C# AppHost source', async () => {
+    test('returns containing project file when active editor is SDK-style AppHost Program.cs', async () => {
         const appHostDirectory = path.join(tempDir, 'AppHost');
         fs.mkdirSync(appHostDirectory);
 
@@ -75,7 +75,7 @@ suite('AspireEditorCommandProvider', () => {
         }
     });
 
-    test('returns source file for active single-file C# AppHost', async () => {
+    test('returns source file when active editor is single-file apphost.cs', async () => {
         const appHostPath = path.join(tempDir, 'apphost.cs');
         fs.writeFileSync(appHostPath, '#:sdk Aspire.AppHost.Sdk\nvar builder = DistributedApplication.CreateBuilder(args);');
         activeEditor = createEditor(appHostPath);

extension/src/utils/appHostLaunchPath.ts

@@ -17,6 +17,10 @@ export async function resolveAppHostLaunchPath(filePath: string): Promise<string
     }
 
     const lines = fileText.split(/\r?\n/);
+
+    // Single-file C# AppHosts are launched directly from source and start with:
+    //   #:sdk Aspire.AppHost.Sdk
+    // The CLI accepts this source file shape, so do not rewrite it to a project path.
     if (lines.some(line => line.startsWith('#:sdk Aspire.AppHost.Sdk'))) {
         return filePath;
     }
@@ -25,8 +29,10 @@ export async function resolveAppHostLaunchPath(filePath: string): Promise<string
         return filePath;
     }
 
-    // The CLI accepts a C# source file only for single-file AppHosts. SDK-style
-    // C# AppHosts need their project file so the AppHost SDK and references load.
+    // SDK-style C# AppHosts usually launch from Program.cs:
+    //   var builder = DistributedApplication.CreateBuilder(args);
+    // The CLI needs the containing .csproj instead of Program.cs so the AppHost SDK
+    // and project references load.
     return await tryFindContainingProjectFile(filePath) ?? filePath;
 }