Document azure-dev.commands.getDotEnvFilePath for use in VS Code configurations

ext/vscode/README.md

@@ -5,6 +5,9 @@ This extension makes it easier to run, create Azure Resources, and deploy Azure
 ## What It Does
 For more information about Azure Developer CLI and this VS Code extension, please [see the documentation](https://aka.ms/azure-dev/vscode).
 
+## Extension Documentation
+- [Utility Commands](docs/commands.md) - Documentation for utility commands provided by this extension for use in VS Code configurations.
+
 ## Tell Us What You Think!
 - [Give us a thumbs up or down](https://aka.ms/azure-dev/hats). We want to hear good news, but bad news are even more important!
 - Use [Discussions](https://aka.ms/azure-dev/discussions) to share new ideas or ask questions about Azure Developer CLI and the VS Code extension.

ext/vscode/docs/commands.md

@@ -0,0 +1,66 @@
+# Azure Developer CLI VS Code Extension Commands
+
+This document describes utility commands provided by the Azure Developer CLI Visual Studio Code extension.
+
+## Utility Commands
+
+The following utility commands are provided for use in VS Code configurations but are not directly available in the command palette.
+
+### azure-dev.commands.getDotEnvFilePath
+
+This command retrieves the path to the `.env` file for a specified Azure Developer CLI environment or for the default environment if none is specified. This is useful for VS Code configurations where you need to access environment variables from an Azure Developer CLI environment.
+
+#### Usage in launch.json
+
+One common use case is to configure a debug session to use environment variables from an Azure Developer CLI environment's `.env` file. To do this, add the following to your `launch.json` file:
+
+```json
+{
+  "configurations": [
+    {
+      // Your debug configuration
+      "envFile": "${input:dotEnvFilePath}"
+    }
+  ],
+  "inputs": [
+    {
+      "id": "dotEnvFilePath",
+      "type": "command",
+      "command": "azure-dev.commands.getDotEnvFilePath"
+    }
+  ]
+}
+```
+
+This configuration will use the `.env` file from the default Azure Developer CLI environment. If you want to use a specific environment, you can pass its name as an argument:
+
+```json
+{
+  "inputs": [
+    {
+      "id": "dotEnvFilePath",
+      "type": "command",
+      "command": "azure-dev.commands.getDotEnvFilePath",
+      "args": ["my-environment-name"]
+    }
+  ]
+}
+```
+
+#### Parameters
+
+The command accepts the following optional parameters as an array:
+
+1. `environmentName` (optional): The name of the environment to use. If not provided, the default environment will be used.
+2. `workingDir` (optional): The working directory to use when looking for environments. If not provided, the first workspace folder will be used.
+
+#### Error Handling
+
+The command will throw an error if:
+
+- No working directory can be determined
+- No Azure Developer environments are found
+- The specified environment does not exist
+- There is no default environment when none is specified
+
+These errors will be shown to the user when the debug session starts or when the command is executed.

ext/vscode/src/commands/getDotEnvFilePath.ts

@@ -5,6 +5,33 @@ import { IActionContext } from "@microsoft/vscode-azext-utils";
 import * as vscode from 'vscode';
 import { getEnvironments, EnvironmentInfo } from "./cmdUtil";
 
+/**
+ * Get the path to the .env file for an Azure developer environment.
+ * 
+ * This can be used in launch.json to provide environment variables to VS Code tasks:
+ * ```json
+ * {
+ *   "configurations": [
+ *     {
+ *       "envFile": "${input:azdDotenv}"
+ *     }
+ *   ],
+ *   "inputs": [
+ *     {
+ *       "id": "azdDotenv",
+ *       "type": "command",
+ *       "command": "azure-dev.commands.getDotEnvFilePath"
+ *     }
+ *   ]
+ * }
+ * ```
+ * 
+ * @param context - The VS Code extension action context
+ * @param args - Optional array containing [environmentName, workingDir]
+ *               - environmentName: Name of the environment to use (uses default if not provided)
+ *               - workingDir: Working directory to find environments (uses first workspace folder if not provided)
+ * @returns Path to the .env file for the specified environment
+ */
 export async function getDotEnvFilePath(context: IActionContext, args: string[] | undefined): Promise<string> {
     const [environmentName, workingDir] = args ?? [];