Skip to content

debug-console-app.md

Latest commit

 

History

History
437 lines (233 loc) · 22.6 KB

debug-console-app.md

File metadata and controls

437 lines (233 loc) · 22.6 KB
title Debug a .NET console application
description Learn how to debug a .NET console app using Visual Studio, Visual Studio Code, or GitHub Codespaces.
ms.date 03/03/2026
ai-usage ai-assisted
zone_pivot_groups code-editor-set-one
dev_langs
csharp
vb

Tutorial: Debug a .NET console application

::: zone pivot="visualstudio"

This tutorial introduces the debugging tools available in Visual Studio.

Important

All of the keyboard shortcuts are based on the defaults from Visual Studio. Your keyboard shortcuts may vary, for more information see Keyboard shortcuts in Visual Studio.

::: zone-end

::: zone pivot="vscode"

This tutorial introduces the debugging tools available in Visual Studio Code for working with .NET apps.

::: zone-end

::: zone pivot="codespaces"

This tutorial introduces the debugging tools available in GitHub Codespaces for working with .NET apps.

::: zone-end

Prerequisites

This tutorial works with the console app that you create in Create a .NET console application.

::: zone pivot="visualstudio"

Use Debug build configuration

Debug and Release are Visual Studio's built-in build configurations. You use the Debug build configuration for debugging and the Release configuration for the final release distribution.

In the Debug configuration, a program compiles with full symbolic debug information and no optimization. Optimization complicates debugging, because the relationship between source code and generated instructions is more complex. The release configuration of a program has no symbolic debug information and is fully optimized.

By default, Visual Studio uses the Debug build configuration, so you don't need to change it before debugging.

  1. Start Visual Studio.

  2. Open the project that you created in Create a .NET console application.

    The current build configuration is shown on the toolbar. The following toolbar image shows that Visual Studio is configured to compile the Debug version of the app:

    :::image type="content" source="./media/debug-console-app/use-debug-configuration.png" alt-text="Visual Studio toolbar with debug highlighted":::

::: zone-end

Set a breakpoint

A breakpoint temporarily interrupts the execution of the application before the line with the breakpoint is run.

::: zone pivot="visualstudio"

  1. Set a breakpoint on the line that displays the name, date, and time, by clicking in the left margin of the code window on that line. The left margin is to the left of the line numbers. Other ways to set a breakpoint are by placing the cursor in the line of code and then pressing F9 or choosing Debug > Toggle Breakpoint from the menu bar.

    As the following image shows, Visual Studio indicates the line on which the breakpoint is set by highlighting it and displaying a red dot in the left margin.

    :::image type="content" source="./media/debug-console-app/set-breakpoint.png" alt-text="Visual Studio Program window with breakpoint set":::

  2. Press F5 to run the program in Debug mode. Another way to start debugging is by choosing Debug > Start Debugging from the menu.

  3. Enter a string in the console window when the program prompts for a name, and then press Enter.

  4. Program execution stops when it reaches the breakpoint and before the Console.WriteLine method executes. The Locals window displays the values of variables that are defined in the currently executing method.

    :::image type="content" source="./media/debug-console-app/breakpoint-hit.png" alt-text="Screenshot of a breakpoint in Visual Studio":::

::: zone-end

::: zone pivot="vscode"

  1. Start Visual Studio Code.

  2. Open the folder of the project that you created in Create a .NET console application.

  3. Open the Program.cs file.

  4. Set a breakpoint on the line that displays the name, date, and time, by clicking in the left margin of the code window. The left margin is to the left of the line numbers. Other ways to set a breakpoint are by pressing F9 or choosing Run > Toggle Breakpoint from the menu while the line of code is selected.

    Visual Studio Code indicates the line on which the breakpoint is set by displaying a red dot in the left margin.

    :::image type="content" source="media/debug-console-app/breakpoint-set.png" alt-text="Breakpoint set":::

::: zone-end

::: zone pivot="codespaces"

  1. Open your GitHub Codespace that you created in Create a .NET console application.

  2. Open the HelloWorld.cs file.

  3. Set a breakpoint on the line that displays the name, date, and time, by clicking in the left margin of the code window. The left margin is to the left of the line numbers. You can also set a breakpoint are by pressing F9 while the line of code is selected.

    :::image type="content" source="media/debug-console-app/codespaces-breakpoint-set.png" alt-text="Breakpoint set":::

::: zone-end

Start debugging

::: zone pivot="visualstudio"

Program execution stops when it reaches the breakpoint, as described in the previous section. The Locals window displays the values of variables that are defined in the currently executing method.

::: zone-end

::: zone pivot="vscode"

Debug and Release are .NET's built-in build configurations. You use the Debug build configuration for debugging and the Release configuration for the final release distribution.

By default, Visual Studio Code launch settings use the Debug build configuration, so you don't need to change it before debugging.

  1. Open the Debug view by selecting the Debugging icon on the left side menu.

    :::image type="content" source="media/debug-console-app/select-debug-pane.png" alt-text="Open the Debug tab in Visual Studio Code":::

  2. Select Run and Debug. If asked, select C# and then select C#: Launch startup project. Other ways to start the program in debugging mode are by pressing F5 or choosing Run > Start Debugging from the menu.

    :::image type="content" source="media/debug-console-app/start-debugging.png" alt-text="Start debugging":::

  3. If asked to Select Launch Configuration, select C#: Debug Active File.

  4. Select the Debug Console tab to see the "What is your name?" prompt that the program displays before waiting for a response.

    :::image type="content" source="media/debug-console-app/select-debug-console.png" alt-text="Select the Debug Console tab":::

  5. Enter a string in the Debug Console window in response to the prompt for a name, and then press Enter.

    Program execution stops when it reaches the breakpoint and before the Console.WriteLine method runs. The Locals section of the Variables window displays the values of variables that are defined in the currently running method.

    :::image type="content" source="media/debug-console-app/breakpoint-hit.png" alt-text="Breakpoint hit, showing Locals":::

::: zone-end

::: zone pivot="codespaces"

By default, GitHub Codespaces uses the Debug build configuration, so you don't need to change it before debugging.

  1. Open the Debug view by selecting the Debugging icon on the left side menu.

    :::image type="content" source="media/debug-console-app/codespaces-select-debug-pane.png" alt-text="Open the Debug tab in Visual Studio Code":::

  2. Select Run and Debug. If asked, select C# as the debugger and then select C#: Debug Active File as the Launch Configuration.

  3. Select the Debug Console tab to see the "What is your name?" prompt that the program displays before waiting for a response.

  4. Enter a string in the Debug Console window in response to the prompt for a name, and then press Enter.

    Program execution stops when it reaches the breakpoint and before the Console.WriteLine method runs. The Locals section of the Variables window displays the values of variables that are defined in the currently running method.

    :::image type="content" source="media/debug-console-app/codespaces-breakpoint-hit.png" alt-text="Breakpoint hit, showing Locals":::

::: zone-end

::: zone pivot="visualstudio"

Use the Immediate window

The Immediate window lets you interact with the application you're debugging. You can interactively change the value of variables to see how it affects your program.

  1. If the Immediate window is not visible, display it by choosing Debug > Windows > Immediate.

  2. Enter name = "Gracie" in the Immediate window and press the Enter key.

  3. Enter currentDate = DateTime.Parse("2026-02-05T20:25:00Z").ToUniversalTime() in the Immediate window and press the Enter key.

    The Immediate window displays the value of the string variable and the properties of the xref:System.DateTime value. In addition, the values of the variables are updated in the Locals window.

    :::image type="content" source="./media/debug-console-app/locals-immediate-window.png" alt-text="Locals and Immediate Windows in Visual Studio":::

  4. Press F5 to continue program execution. Another way to continue is by choosing Debug > Continue from the menu.

    The values displayed in the console window correspond to the changes you made in the Immediate window.

  5. Press any key to exit the application and stop debugging.

::: zone-end

::: zone pivot="vscode,codespaces"

Use the Debug Console

The Debug Console window lets you interact with the application you're debugging. You can change the value of variables to see how it affects your program.

  1. Select the Debug Console tab.

  2. Enter name = "Gracie" at the prompt at the bottom of the Debug Console window and press Enter.

    :::image type="content" source="media/debug-console-app/change-variable-values.png" alt-text="Change variable values":::

  3. Enter currentDate = DateTime.Parse("2026-01-28T20:54:00Z").ToUniversalTime() at the bottom of the Debug Console window and press Enter.

    The Variables window displays the new values of the name and currentDate variables.

  4. Continue program execution by selecting the Continue button in the toolbar. Another way to continue is by pressing F5.

    :::image type="content" source="media/debug-console-app/continue-debugging.png" alt-text="Continue debugging":::

    The values displayed in the console window correspond to the changes you made in the Debug Console.

    :::image type="content" source="media/debug-console-app/codespaces-changed-variable-values.png" alt-text="Terminal showing the entered values":::

  5. Press Enter to exit the application and stop debugging.

::: zone-end

Set a conditional breakpoint

The program displays the string that the user enters. What happens if the user doesn't enter anything? You can test this with a useful debugging feature called a conditional breakpoint.

::: zone pivot="visualstudio"

  1. Right-click on the red dot that represents the breakpoint. In the context menu, select Conditions to open the Breakpoint Settings dialog. Select the box for Conditions if it's not already selected.

    :::image type="content" source="./media/debug-console-app/breakpoint-settings.png" alt-text="Editor showing breakpoint settings panel - C#":::

  2. For the Conditional Expression, enter the following code in the text field.

    string.IsNullOrEmpty(name)
    String.IsNullOrEmpty(name)

    Each time the breakpoint is hit, the debugger calls the String.IsNullOrWhiteSpace(name) method, and it breaks on this line only if the method call returns true.

    Instead of a conditional expression, you can specify a hit count, which interrupts program execution before a statement is executed a specified number of times. Another option is to specify a filter condition, which interrupts program execution based on such attributes as a thread identifier, process name, or thread name.

  3. Select Close to close the dialog.

  4. Start the program with debugging by pressing F5.

  5. In the console window, press the Enter key when prompted to enter your name.

  6. Because the condition you specified (name is either null or xref:System.String.Empty?displayProperty=nameWithType) has been satisfied, program execution stops when it reaches the breakpoint and before the Console.WriteLine method executes.

  7. Select the Locals window, which shows the values of variables that are local to the currently executing method. In this case, Main is the currently executing method. Observe that the value of the name variable is "", or xref:System.String.Empty?displayProperty=nameWithType.

  8. Confirm the value is an empty string by entering the following statement in the Immediate window and pressing Enter. The result is true.

    ? name == String.Empty
    ? String.IsNullOrEmpty(name)

    The question mark directs the immediate window to evaluate an expression.

    :::image type="content" source="./media/debug-console-app/immediate-window-output.png" alt-text="Immediate Window returning a value of true after the statement is executed - C#":::

  9. Press F5 to continue program execution.

  10. Press any key to close the console window and stop debugging.

  11. Clear the breakpoint by clicking on the dot in the left margin of the code window. Other ways to clear a breakpoint are by pressing F9 or choosing Debug > Toggle Breakpoint while the line of code is selected.

::: zone-end

::: zone pivot="vscode,codespaces"

  1. Right-click (Ctrl-click on macOS) on the red dot that represents the breakpoint. In the context menu, select Edit Breakpoint to open a dialog that lets you enter a conditional expression.

    :::image type="content" source="media/debug-console-app/breakpoint-context-menu.png" alt-text="Breakpoint context menu":::

  2. Select Expression in the drop-down, enter the following conditional expression, and press Enter.

    String.IsNullOrEmpty(name)

    :::image type="content" source="media/debug-console-app/conditional-expression.png" alt-text="Enter a conditional expression":::

    Each time the breakpoint is hit, the debugger calls the String.IsNullOrEmpty(name) method, and it breaks on this line only if the method call returns true.

    Instead of a conditional expression, you can specify a hit count, which interrupts program execution before a statement is run a specified number of times. Another option is to specify a filter condition, which interrupts program execution based on such attributes as a thread identifier, process name, or thread name.

  3. Start the program with debugging by pressing F5.

  4. In the Debug Console tab, press Enter when prompted to enter your name.

    Because the condition you specified (name is either null or xref:System.String.Empty?displayProperty=nameWithType) has been satisfied, program execution stops when it reaches the breakpoint and before the Console.WriteLine method runs.

    The Variables window shows that the value of the name variable is "", or xref:System.String.Empty?displayProperty=nameWithType.

  5. Confirm the value is an empty string by entering the following statement at the Debug Console prompt and pressing Enter. The result is true.

    name == String.Empty

  6. Select the Continue button on the toolbar to continue program execution.

  7. Press Enter to exit the program and stop debugging.

  8. Clear the breakpoint by clicking on the dot in the left margin of the code window. Other ways to clear a breakpoint are by pressing F9 or choosing Run > Toggle Breakpoint from the menu while the line of code is selected.

  9. If you get a warning that the breakpoint condition will be lost, select Remove Breakpoint.

::: zone-end

Step through a program

::: zone pivot="visualstudio"

Visual Studio also allows you to step line by line through a program and monitor its execution. Ordinarily, you'd set a breakpoint and follow program flow through a small part of your program code. Since this program is small, you can step through the entire program.

  1. Set a breakpoint on the line of code that displays the "What is your name?" prompt.

  2. Choose Debug > Step Into. Another way to debug one statement at a time is by pressing F11.

    Visual Studio highlights and displays an arrow beside the next line of execution.

    :::image type="content" source="./media/debug-console-app/step-into-method.png" alt-text="Visual Studio step into method - C#":::

    At this point, the Locals window shows that the args array is empty, and name and currentDate have default values. In addition, Visual Studio has opened a blank console window.

  3. Press F11. Visual Studio highlights the statement that includes the name variable assignment. The Locals window shows that name is null, and the console window displays the string "What is your name?".

  4. Respond to the prompt by entering a string in the console window and pressing Enter. The console is unresponsive, and the string you entered isn't displayed in the console window, but the xref:System.Console.ReadLine*?displayProperty=nameWithType method will nevertheless capture your input.

  5. Press F11. Visual Studio highlights the statement that includes the currentDate variable assignment. The Locals window shows the value returned by the call to the xref:System.Console.ReadLine*?displayProperty=nameWithType method. The console window also displays the string you entered at the prompt.

  6. Press F11. The Locals window shows the value of the currentDate variable after the assignment from the xref:System.DateTime.Now?displayProperty=nameWithType property. The console window is unchanged.

  7. Press F11. Visual Studio calls the xref:System.Console.WriteLine(System.String,System.Object,System.Object)?displayProperty=nameWithType method. The console window displays the formatted string.

  8. Choose Debug > Step Out. Another way to stop step-by-step execution is by pressing Shift+F11.

    The console window displays a message and waits for you to press a key.

  9. Press any key to close the console window and stop debugging.

::: zone-end

::: zone pivot="vscode,codespaces"

Visual Studio Code also allows you to step line by line through a program and monitor its execution. Ordinarily, you'd set a breakpoint and follow program flow through a small part of your program code. Since this program is small, you can step through the entire program.

  1. Set a breakpoint on the line of code that displays the "What is your name?" prompt.

  2. Press F5 to start debugging.

    Visual Studio Code highlights the breakpoint line.

    At this point, the Variables window shows that the args array is empty, and name and currentDate have default values.

  3. Select Step Into from the Debug toolbar or press F11.

    :::image type="content" source="media/debug-console-app/step-into.png" alt-text="Step-Into button":::

    Visual Studio Code highlights the next line.

  4. Visual Studio Code runs the Console.WriteLine for the name prompt and highlights the next line of execution. The next line is the Console.ReadLine for the name. The Variables window is unchanged, and the Terminal tab shows the "What is your name?" prompt.

  5. Select Step Into or press F11.

    Visual Studio Code highlights the name variable assignment. The Variables window shows that name is still null.

  6. Respond to the prompt by entering a string in the Terminal tab and pressing Enter.

    The Debug Console tab might not display the string you enter while you're entering it, but the xref:System.Console.ReadLine*?displayProperty=nameWithType method will capture your input.

  7. Select Step Into or press F11.

    Visual Studio Code highlights the currentDate variable assignment. The Variables window shows the value returned by the call to the xref:System.Console.ReadLine*?displayProperty=nameWithType method. The Terminal tab displays the string you entered at the prompt.

  8. Select Step Into or press F11.

    The Variables window shows the value of the currentDate variable after the assignment from the xref:System.DateTime.Now?displayProperty=nameWithType property.

  9. Select Step Into or press F11.

    Visual Studio Code calls the xref:System.Console.WriteLine(System.String,System.Object,System.Object)?displayProperty=nameWithType method. The console window displays the formatted string.

  10. Select Step Out or press Shift+F11.

    :::image type="content" source="media/debug-console-app/step-out.png" alt-text="Step-Out button":::

    The terminal displays "Press any key to exit..."

  11. Press any key to exit the program.

::: zone-end

Use Release build configuration

Once you've tested the Debug version of your application, you should also compile and test the Release version. The Release version incorporates compiler optimizations that can sometimes negatively affect the behavior of an application. For example, compiler optimizations that are designed to improve performance can create race conditions in multithreaded applications.

::: zone pivot="visualstudio"

To build and test the Release version of your console application, change the build configuration on the toolbar from Debug to Release.

:::image type="content" source="./media/debug-console-app/use-release-configuration.png" alt-text="default Visual Studio toolbar with release highlighted":::

When you press F5 or choose Build Solution from the Build menu, Visual Studio compiles the Release version of the application. You can test it as you did the Debug version.

::: zone-end

::: zone pivot="vscode"

To build and test the Release version of your console application, open the Terminal and run the following command:

dotnet run --configuration Release

::: zone-end

::: zone pivot="codespaces"

To build and test the Release version of your console application, run the following command in the terminal:

dotnet run --configuration Release HelloWorld.cs

::: zone-end

Next steps

In this tutorial, you used debugging tools. In the next tutorial, you publish a deployable version of the app.

[!div class="nextstepaction"] Publish a .NET console application