Merge pull request #13271 from TylerMSFT/commandlineargs2

draft new command arguments topic

Author: JamesJBarnett

docs/debugger/media/command-line-argument-dropdown-arg1-arg2.png

@@ -119,29 +119,29 @@ You can change the project settings for a C or C++ debug configuration in the **
 
  Each debug property setting is automatically written and saved to the "per-user" file (.vcxproj.user) for your solution when you save your solution.
 
- Specify which debugger to use in the **Debugger to launch** list box, as described in the following table. Your choice will affect which properties are visible.
+ Specify which debugger to use in the **Debugger to launch** list box, as described in the following table. Your choice affects which properties are visible.
 
 ## Configuration Properties folder (Debugging category)
 
 | **Setting** | **Description** |
 | - | - |
 | **Debugger to launch** | Specifies the debugger to run, with the following choices:<br /><br /> -   **Local Windows Debugger**<br />-   **Remote Windows Debugger**<br />-   **Web Browser Debugger**<br />-   **Web Service Debugger** |
-| **Command** (Local Windows Debugger) | Specifies the command for starting the program that you are debugging on the local computer. |
+| **Command** (Local Windows Debugger) | Specifies the command for starting the program that you're debugging on the local computer. |
 | **Remote Command** (Remote Windows Debugger) | The path for the .exe on the remote computer. Enter the path just as you would enter it on the remote machine. |
-| **Command Arguments** (Local Windows Debugger)<br /><br /> **Remote Command Arguments** (Remote Windows Debugger) | -   Specifies arguments for the command specified earlier.<br /><br /> You can use the following redirection operators in this box:<br /><br /> < `file`<br /> Reads stdin from file.<br /><br /> > `file`<br /> Writes stdout to file.<br /><br /> >> `file`<br /> Appends stdout to file.<br /><br /> 2> `file`<br /> Writes stderr to file.<br /><br /> 2>> `file`<br /> Appends stderr to file.<br /><br /> 2> &1<br /> Sends stderr (2) output to same location as stdout (1).<br /><br /> 1> &2<br /> Sends stdout (1) output to same location as stderr (2).<br /><br /> In most cases, these operators are applicable only to console applications. <br /><br />If you need to escape characters in the command, you can use ASCII values, such as %25 to replace %. If you use the **Start Debugging** command, double quotes will escape the preceding commands, such as "<" to replace <.|
+| **Command Arguments** (Local Windows Debugger)<br /><br /> **Remote Command Arguments** (Remote Windows Debugger) | -   Specifies arguments for the program you're debugging. For more information about ways to set command line args, see [Specify command-line arguments](specify-command-line-arguments.md).<br /><br /> You can use the following redirection operators in this box:<br /><br /> < `file`<br /> Reads stdin from file.<br /><br /> > `file`<br /> Writes stdout to file.<br /><br /> >> `file`<br /> Appends stdout to file.<br /><br /> 2> `file`<br /> Writes stderr to file.<br /><br /> 2>> `file`<br /> Appends stderr to file.<br /><br /> 2> &1<br /> Sends stderr (2) output to same location as stdout (1).<br /><br /> 1> &2<br /> Sends stdout (1) output to same location as stderr (2).<br /><br /> In most cases, these operators are applicable only to console applications. <br /><br />If you need to escape characters in the command, you can use ASCII values, such as %25 to replace %. If you use the **Start Debugging** command, double quotes escape the preceding commands, such as "<" to replace <.|
 | **Working Directory** | Specifies the working directory of the program being debugged, relative to the project directory where your EXE is located. If you leave this blank, the working directory is the project directory. For remote debugging, the project directory is on the remote server. |
 | **Attach** (Local Windows Debugger and Remote Windows Debugger) | Specifies whether to start or attach to the application. Default setting is No. |
 | **Remote Server Name** (Remote Windows Debugger) | Specifies the name of a computer (other than yours) on which you want to debug an application.<br /><br /> The RemoteMachine Build macro is set to the value of this property; for more information, see [Macros for build commands and properties](/cpp/build/reference/common-macros-for-build-commands-and-properties). |
 | **Connection** (Remote Windows Debugger) | Allows you to switch between standard and no-authentication connection types for remote debugging. Specify a remote computer name in the **Remote Server Name** box. Connection types include the following:<br /><br /> -   **Remote with Windows Authentication**<br />-   **Remote with No Authentication**<br /><br /> **Note** Remote debugging with No Authentication may leave the remote computer vulnerable to security violations. Windows Authentication mode is more secure.<br /><br /> For more information, see [Remote debugging setup](../debugger/remote-debugging.md). |
-| **HTTP URL** (Web Service Debugger and Web Browser Debugger) | Specifies the URL where the project you are debugging is located. |
+| **HTTP URL** (Web Service Debugger and Web Browser Debugger) | Specifies the URL where the project you're debugging is located. |
 | **Debugger Type** | Specifies the type of debugger to be used: **Native Only**, **Managed Only**, **GPU Only**, **Mixed**, **Auto** (default), or **Script**.<br /><br /> -   **Native Only** is for unmanaged C++ code.<br />-   **Managed Only** is for code that runs under the common language runtime (managed code).<br />-   **Mixed** invokes debuggers for both managed and unmanaged code.<br />-   **Auto** determines the debugger type based on compiler and EXE information.<br />-   **Script** invokes a debugger for scripts.<br />-   **GPU Only** is for C++ AMP code that runs on a GPU device or on the DirectX reference rasterizer. See [Debugging GPU code](../debugger/debugging-gpu-code.md). |
-| **Environment** (Local Windows Debugger and Remote Windows Debugger) | Specifies environment variables for the program that you are debugging. Use standard environment variable syntax (for example, `PATH="%SystemRoot%\..."`). These variables override the system environment or are merged with the system environment, depending on the **Merge Environment** setting. When you click in the right column, an "Edit..." appears. Select that link to open the Property Editor and edit environment variables. To add multiple environment variables, use the [Property Editor](/cpp/build/working-with-project-properties#property_editor) and add one variable per line. |
-| **Merge Environment** (Local Windows Debugger) | Determines whether the variables that are specified in the **Environment** box will be merged with the environment that is defined by the operating system. Default setting is Yes. |
+| **Environment** (Local Windows Debugger and Remote Windows Debugger) | Specifies environment variables for the program that you're debugging. Use standard environment variable syntax (for example, `PATH="%SystemRoot%\..."`). These variables override the system environment or are merged with the system environment, depending on the **Merge Environment** setting. When you click in the right column, an "Edit..." appears. Select that link to open the Property Editor and edit environment variables. To add multiple environment variables, use the [Property Editor](/cpp/build/working-with-project-properties#property_editor) and add one variable per line. |
+| **Merge Environment** (Local Windows Debugger) | Determines whether the variables that are specified in the **Environment** box are merged with the environment that is defined by the operating system. Default setting is Yes. |
 | **SQL Debugging** (all but MPI Cluster Debugger) | Enables debugging of SQL procedures from your Visual C++ application. Default setting is No. |
-| **Debugging Accelerator Type** (GPU debugging only) | Specifies the GPU device to use for debugging. Installing device drivers for compatible GPU devices will add additional options. The default setting is **GPU - Software Emulator**. |
+| **Debugging Accelerator Type** (GPU debugging only) | Specifies the GPU device to use for debugging. Installing device drivers for compatible GPU devices add additional options. The default setting is **GPU - Software Emulator**. |
 | **GPU Default Breakpoint Behavior** (GPU debugging only) | Specifies whether a breakpoint event should be raised for each thread in a SIMD warp. The default setting is to raise the breakpoint event only once per warp. |
 | **Amp Default Accelerator** | Specifies the default AMP accelerator when debugging GPU code. Choose **WARP software accelerator** to investigate if an issue is caused by the hardware or a driver instead of your code. |
-| **Deployment Directory** (Remote Windows Debugger) | Specifies the path on the remote computer where the project output will be copied prior to launch. The path can be a network share on the remote computer, or it can be a path to a folder on the remote computer. The default setting is empty, which means the project output is not copied to a network share. To enable deployment of the files, you must also select the **Deploy** check box in the Configuration Manager dialog box. For more information, see [How to: Create and edit configurations](../ide/how-to-create-and-edit-configurations.md). |
+| **Deployment Directory** (Remote Windows Debugger) | Specifies the path on the remote computer where the project output is copied prior to launch. The path can be a network share on the remote computer, or it can be a path to a folder on the remote computer. The default setting is empty, which means the project output isn't copied to a network share. To enable deployment of the files, you must also select the **Deploy** check box in the Configuration Manager dialog box. For more information, see [How to: Create and edit configurations](../ide/how-to-create-and-edit-configurations.md). |
 | **Additional Files to Deploy** (Remote Windows Debugger) | If the Deployment Directory property is set, this is a semicolon-delimited list of additional folders or files to copy to the deployment directory. The default setting is empty, which means that no additional folders or files are copied to the deployment directory. To copy the contents of a folder to the same folder in the Deployment Directory, specify a folder name. To enable deployment of the files, you must also select the **Deploy** check box in the Configuration Manager dialog box. For more information, see [How to: Create and edit configurations](../ide/how-to-create-and-edit-configurations.md). |
 | **Deploy Visual C++ Debug Runtime Libraries** (Remote Windows Debugger) | If the Deployment Directory property is set, this specifies whether the Visual C++ debug runtime libraries for the current platform should be copied to the network share. The default setting is Yes. |
 
@@ -161,9 +161,9 @@ You can change the project settings for a C or C++ debug configuration in the **
 
 |Setting|Description|
 |-------------|-----------------|
-|**Generate Debug Info** ([/DEBUG](/cpp/build/reference/debug-generate-debug-info))|Tells the linker to include debug information, which will have the format specified by [/Z7, /Zd, Zi, or /ZI](/cpp/build/reference/z7-zi-zi-debug-information-format).|
+|**Generate Debug Info** ([/DEBUG](/cpp/build/reference/debug-generate-debug-info))|Tells the linker to include debug information, which has the format specified by [/Z7, /Zd, Zi, or /ZI](/cpp/build/reference/z7-zi-zi-debug-information-format).|
 |**Generate Program Database File** ([/PDB:name](/cpp/build/reference/pdb-use-program-database))|Specify the name of a program database (PDB) file in this box. You must select ZI or /Zi for Debug Information Format.|
-|**Strip Private Symbols** ([/PDBSTRIPPED:filename](/cpp/build/reference/pdbstripped-strip-private-symbols))|Specify the name of a PDB file in this box if you do not want to include private symbols in the PDB file. This option creates a second PDB file when you build your program image with any of the compiler or linker options that generate a PDB file, such as /DEBUG, /Z7, /Zd. Or /Zi. This second PDB file omits symbols that you would not want to ship to your customers. For more information, see [/PDBSTRIPPED (Strip private symbols)](/cpp/build/reference/pdbstripped-strip-private-symbols).|
+|**Strip Private Symbols** ([/PDBSTRIPPED:filename](/cpp/build/reference/pdbstripped-strip-private-symbols))|Specify the name of a PDB file in this box if you don't want to include private symbols in the PDB file. This option creates a second PDB file when you build your program image with any of the compiler or linker options that generate a PDB file, such as /DEBUG, /Z7, /Zd. Or /Zi. This second PDB file omits symbols that you don't want to ship to your customers. For more information, see [/PDBSTRIPPED (Strip private symbols)](/cpp/build/reference/pdbstripped-strip-private-symbols).|
 |**Generate Map File** ([/MAP](/cpp/build/reference/map-generate-mapfile))|Tells the linker to generate a map file during linking. Default setting is No. For more information, see [/MAP (Generate Mapfile)](/cpp/build/reference/map-generate-mapfile).|
 |**Map File Name** ([/MAP:](/cpp/build/reference/map-generate-mapfile)*name*)|If you choose Generate Map File, you can specify the map file in this box. For more information, see [/MAP (Generate Mapfile)](/cpp/build/reference/map-generate-mapfile).|
 |**Map Exports** ([/MAPINFO:EXPORTS](/cpp/build/reference/mapinfo-include-information-in-mapfile))|Includes exported functions in the map file. Default setting is No. For more information, see [/MAPINFO (Include Information in Mapfile)](/cpp/build/reference/mapinfo-include-information-in-mapfile).|

docs/debugger/media/command-line-argument-dropdown-arg1.png

@@ -0,0 +1,95 @@
+---
+title: "Send command-line arguments while debugging (C++)"
+description: Learn how to send command-line argument to a debuggee using the new command line arguments dropdown.
+ms.date: 10/30/2024
+ms.topic: "conceptual"
+dev_langs:
+  - "C++"
+helpviewer_keywords:
+  - "command-line argument [C++]"
+  - "debugging [C++], enabling debug features"
+author: "TylerMSFT"
+ms.author: "TWhitney"
+manager: coxford
+ms.subservice: debug-diagnostics
+---
+# Pass command-line arguments while debugging (C++)
+
+In Visual C++, use the command-line arguments dropdown to quickly specify or reuse arguments for debugging.
+
+## Prerequisites
+
+- Visual Studio 2022 version 17.12 preview 5 or later.
+- Visual Studio Tools for Unreal Engine. See [Install Visual Studio Tools for Unreal Engine](/visualstudio/gamedev/unreal/get-started/vs-tools-unreal-install)) for installation instructions.
+
+## Specify command-line arguments
+
+The command-line arguments dropdown is available in the **Standard** toolbar. If the **Standard** toolbar isn't visible, from the Visual Studio main menu choose **Tools** > **Customize**. In the **Customize** dialog, choose **Toolbars**. Then select **Standard**.
+
+:::image type="complex" source="./media/select-standard-toolbar.png" alt-text="A screenshot of the Customize dialog.":::
+The Toolbars tab is selected in the Customize dialog. The entry for Standard, meaning the standard toolbar, is selected.
+:::image-end:::
+
+The command-line arguments dropdown follows the **Solutions Platforms** dropdown on the **Standard** toolbar. If no arguments have been specified, the dropdown is empty and the tooltip displays "empty".
+
+:::image type="complex" source="./media/command-line-argument-dropdown-empty.png" alt-text="A screenshot of the command-line arguments dropdown.":::
+The command-line arg dropdown is shown following the Solutions Platforms dropdown on the Standard toolbar. The dropdown is empty. A tooltip reads, "empty".
+:::image-end:::
+
+When you add command-line arguments, the tooltip shows the selected argument list so that you can see all of the arguments.
+
+To add command-line arguments, type them in the dropdown and press **Enter**. The arguments are saved in the order that you enter them and appear in the dropdown for future use. There's a limit of five command lines that you can add before the oldest one is removed to make room for a new one.
+
+In this example, the command-line argument `-arg1` is added to the dropdown:
+
+:::image type="content" source="./media/command-line-argument-dropdown-arg1.png" alt-text="A screenshot of the command-line args dropdown. It contains the value -arg1.":::
+
+Adding another argument, `-arg2`, results in:
+
+:::image type="content" source="./media/command-line-argument-dropdown-arg1-arg2.png" alt-text="A screenshot of the command-line args dropdown. It contains the value -arg1 -arg2.":::
+
+You can use the dropdown to select previously specified command-line arguments to pass to the app you're debugging. Consider the following code:
+
+```cpp
+#include <iostream>
+
+int main(int argc, char* argv[]) 
+{
+    for (int i = 1; i < argc; ++i) // argv[0] is the path of the running program
+    {
+        std::cout << "Argument " << i << ": " << argv[i] << std::endl;
+    }
+    return 0;
+}
+```
+
+In this example, the `-arg1 -arg2` arguments are selected in the command-line arguments dropdown:
+
+:::image type="content" source="./media/command-line-argument-dropdown-selected-args.png" alt-text="A screenshot of the command-line args dropdown. The entry for `-arg1 -arg2` is selected.":::
+
+Which results in this output when the app is run:
+
+```output
+Argument 1: -arg1
+Argument 2: -arg2
+```
+
+The command-line arguments dropdown is a convenient way to specify and reuse command-line arguments. Particularly when you need to quickly switch between different arguments for different scenarios you're testing.
+
+You can also click in the command-line arguments dropdown and press **Ctrl+C** to copy the highlighted command-line to the clipboard.
+
+## Relationship to project settings
+
+Another way to specify command-line arguments is in project settings.
+
+If you right-click the project in the **Solution Explorer** and choose **Properties**, you can specify command-line arguments in **Debugging** > **Command Arguments**.
+
+:::image type="complex" source="./media/debugging-property-page-command-args.png" alt-text="A screenshot of the project property pages debugging options.":::
+The Command Arguments entry is shown and it has the same arguments as the command-line arguments dropdown: -arg1 -arg2.
+:::image-end:::
+
+Command-line arguments specified in the project settings are added to the command-line arguments dropdown. Conversely, if you select arguments in the command-line arguments dropdown, they replace the arguments specified in the project settings. Either way you specify the arguments, they're kept in sync. Both are saved with the project settings, so they're available when you reopen the project.
+
+## Related content
+
+- [Project Settings for a C++ Debug Configuration](../debugger/project-settings-for-a-cpp-debug-configuration.md)

docs/debugger/media/command-line-argument-dropdown-empty.png

@@ -136,6 +136,8 @@
           href: project-settings-for-a-cpp-debug-configuration.md
         - name: Enable debug features in C++ (-D_DEBUG)
           href: enabling-debug-features-in-visual-cpp-d-debug.md
+        - name: Send command-line arguments to a debugee (C++)
+          href: specify-command-line-arguments.md
       - name: Project settings (C#)
         href: project-settings-for-csharp-debug-configurations.md
       - name: Project settings (.NET C#)