Skip to content

VS Mac .NET Core tutorials #18819

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 22 commits into from
Jun 10, 2020
Merged

VS Mac .NET Core tutorials #18819

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
ee7cf55
draft
tdykstra Jun 3, 2020
95e894e
draft
tdykstra Jun 3, 2020
51b8b00
draft
tdykstra Jun 4, 2020
13c3f52
draft
tdykstra Jun 4, 2020
0e188e2
draft
tdykstra Jun 4, 2020
e088475
draft
tdykstra Jun 4, 2020
3aee193
draft
tdykstra Jun 5, 2020
91754bb
draft
tdykstra Jun 5, 2020
ba3f819
add missing image
tdykstra Jun 5, 2020
7cc1709
make create app tutorials consistent
tdykstra Jun 8, 2020
b787bc9
make debug tutorials consistent
tdykstra Jun 8, 2020
3f0e77f
make publish tutorials consistent
tdykstra Jun 8, 2020
a08d5dd
make library tutorials consistent
tdykstra Jun 8, 2020
b3ef48f
make testing tutorials consistent
tdykstra Jun 8, 2020
9f6e90c
markdownlint
tdykstra Jun 8, 2020
e3361a2
fix add ref steps
tdykstra Jun 8, 2020
8a9a767
proofread pass
tdykstra Jun 9, 2020
8245c3b
proofread pass
tdykstra Jun 9, 2020
2c72cf2
reformat ctrl-click
tdykstra Jun 9, 2020
d70aeca
standardize keyboard formatting
tdykstra Jun 9, 2020
904b225
change key representations
tdykstra Jun 10, 2020
8afd4a2
more key representations
tdykstra Jun 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .openpublishing.redirection.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,6 +466,14 @@
"source_path": "docs/core/tutorials/target-dotnetcore-with-msbuild.md",
"redirect_url": "/dotnet/core/tools/cli-msbuild-architecture"
},
{
"source_path": "docs/core/tutorials/using-on-mac-vs.md",
"redirect_url": "/dotnet/core/tutorials/with-visual-studio-mac"
},
{
"source_path": "docs/core/tutorials/using-on-mac-vs-full-solution.md",
"redirect_url": "/dotnet/core/tutorials/library-with-visual-studio-mac"
},
{
"source_path": "docs/core/tutorials/using-on-macos.md",
"redirect_url": "/dotnet/core/tutorials/library-with-visual-studio-code"
Expand Down
28 changes: 20 additions & 8 deletions docs/core/toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,13 +114,13 @@
displayName: tutorials, visual studio code, vs code
- name: Publish an app
href: tutorials/publishing-with-visual-studio-code.md
displayName: tutorials, visual studio, vs
displayName: tutorials, visual studio code, vs code
- name: Create a library
href: tutorials/library-with-visual-studio-code.md
displayName: tutorials, visual studio, vs
displayName: tutorials, visual studio code, vs code
- name: Unit test a library
href: tutorials/testing-library-with-visual-studio-code.md
displayName: tutorials, visual studio, vs
displayName: tutorials, visual studio code, vs code
- name: Install and use a package
href: /nuget/quickstart/install-and-use-a-package-using-the-dotnet-cli
displayName: tutorials, cli
Expand All @@ -130,13 +130,25 @@
- name: Use Visual Studio for Mac
items:
- name: Create a console app
href: tutorials/using-on-mac-vs.md
displayName: tutorials
- name: Create a library and unit test it
href: tutorials/using-on-mac-vs-full-solution.md
displayName: tutorials
href: tutorials/with-visual-studio-mac.md
displayName: tutorials, visual studio for mac, vs for mac, cli
- name: Debug an app
href: tutorials/debugging-with-visual-studio-mac.md
displayName: tutorials, visual studio for mac, vs for mac
- name: Publish an app
href: tutorials/publishing-with-visual-studio-mac.md
displayName: tutorials, visual studio for mac, vs for mac
- name: Create a library
href: tutorials/library-with-visual-studio-mac.md
displayName: tutorials, visual studio for mac, vs for mac
- name: Unit test a library
href: tutorials/testing-library-with-visual-studio-mac.md
displayName: tutorials, visual studio for mac, vs for mac
- name: Install and use a package
href: /nuget/quickstart/install-and-use-a-package-in-visual-studio-mac
displayName: tutorials, visual studio for mac, vs for mac
- name: Create and publish a package
href: /nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli
displayName: tutorials
- name: Advanced topics
items:
Expand Down
46 changes: 23 additions & 23 deletions docs/core/tutorials/debugging-with-visual-studio-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Debug a .NET Core console application with Visual Studio Code
description: Learn how to debug a .NET Core console app with Visual Studio Code.
title: Debug a .NET Core console application using Visual Studio Code
description: Learn how to debug a .NET Core console app using Visual Studio Code.
ms.date: 05/26/2020
---
# Tutorial: Debug a .NET Core console application using Visual Studio Code
Expand All @@ -13,25 +13,25 @@ This tutorial introduces the debugging tools available in Visual Studio Code for

## Use Debug build configuration

*Debug* and *Release* are two of .NET Core's build configurations. You use the Debug build configuration for debugging and the Release configuration for the final release distribution.
*Debug* and *Release* are .NET Core'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 Code uses the Debug build configuration, so you don't need to change it before debugging.
By default, Visual Studio Code launch settings use the Debug build configuration, so you don't need to change it before debugging.

## Set a breakpoint
1. Start Visual Studio Code.

A breakpoint temporarily interrupts the execution of the application *before* the line with the breakpoint is executed.
1. Open the folder of the project that you created in [Create a .NET Core console application in Visual Studio Code](with-visual-studio-code.md).

1. Open Visual Studio Code.
## Set a breakpoint

1. Open the *HelloWorld* project folder that you created in [Create a .NET Core console application in Visual Studio Code](with-visual-studio-code.md).
A *breakpoint* temporarily interrupts the execution of the application before the line with the breakpoint is executed.

1. Open the *Program.cs* file.

1. 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. Another way to set a breakpoint is by placing the cursor in the line of code and then pressing <kbd>F9</kbd>.
1. 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 <kbd>F9</kbd> or selecting **Run** > **Toggle Breakpoint** from the menu while the line of code is selected.

As the following image shows, Visual Studio Code indicates the line on which the breakpoint is set by displaying a red dot in the left margin.
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/debugging-with-visual-studio-code/breakpoint-set.png" alt-text="Breakpoint set":::

Expand Down Expand Up @@ -63,7 +63,7 @@ The breakpoint is located after a `Console.ReadLine` method call. The **Debug Co

:::image type="content" source="media/debugging-with-visual-studio-code/select-debug-pane.png" alt-text="Open the Debug tab in Visual Studio Code":::

1. Start debugging by selecting the green arrow at the top of the pane, next to **.NET Core Launch (console)**. Another way to start debugging is by pressing <kbd>F5</kbd>.
1. Select the green arrow at the top of the pane, next to **.NET Core Launch (console)**. Another way to start the program in debugging mode is by choosing **Run** > **Start Debugging** from the menu.

:::image type="content" source="media/debugging-with-visual-studio-code/start-debugging.png" alt-text="Start debugging":::

Expand All @@ -77,7 +77,7 @@ The breakpoint is located after a `Console.ReadLine` method call. The **Debug Co

:::image type="content" source="media/debugging-with-visual-studio-code/breakpoint-hit.png" alt-text="Breakpoint hit, showing Locals":::

## Change variable values
## 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.

Expand Down Expand Up @@ -107,7 +107,7 @@ The **Debug Console** window lets you interact with the application you're debug

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*.

1. Right-click (<kbd>Ctrl</kbd>+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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just curious, what is the reason not to use <kbd> here? I ask because I use it everywhere and now I'm wondering if I shouldn't.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ctrl-click seems to be a special case mixing keyboard and mouse, so I decided to leave it the way it was in the Mac tutorials as they already existed. I'm happy to change if you've seen Mac tutorials using <kbd>Ctrl</kbd>-click

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ping @BillWagner on how best to render control-click for macOS in tutorials

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm. I don't have a clear recommendation. I think the <kbd>Ctrl</kbd>-click is best.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A related issue: given that Macs have keyboard labels all in lowercase (enter, control, option, command, etc., should those keys be represented by, e.g., <kbd>command</kbd> or <kbd>Command</kbd>

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As with the earlier question, I don't have an answer here. I think we will set the standard.

My weakly held proposal: go with lower case to match the keyboard labels.

1. Right-click (<kbd>Ctrl</kbd>-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/debugging-with-visual-studio-code/breakpoint-context-menu.png" alt-text="Breakpoint context menu":::

Expand All @@ -121,7 +121,7 @@ The program displays the string that the user enters. What happens if the user d

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 executed a specified number of times, or a *filter condition*, which interrupts program execution based on such attributes as a thread identifier, process name, or thread name.
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.

1. Start the program with debugging by pressing <kbd>F5</kbd>.

Expand All @@ -143,7 +143,7 @@ The program displays the string that the user enters. What happens if the user d

1. Select the **Terminal** tab, and press any key to exit the program and stop debugging.

1. Clear the breakpoint by clicking on the dot in the left margin of the code window. Another way to clear a breakpoint is by pressing <kbd>F9</kbd> while the line of code is selected.
1. 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 <kbd>F9</kbd> or choosing **Run > Toggle Breakpoint** from the menu while the line of code is selected.

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

Expand All @@ -159,37 +159,37 @@ Visual Studio Code also allows you to step line by line through a program and mo

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

1. Select **Step Into** or press <kbd>F11</kbd>.
1. Select **Run** > **Step Into** or press <kbd>F11</kbd>.

:::image type="content" source="media/debugging-with-visual-studio-code/step-into.png" alt-text="Step-Into button":::

Visual Studio Code highlights the next line.

1. Select **Step Into** or press <kbd>F11</kbd>.
1. Select **Run** > **Step Into** or press <kbd>F11</kbd>.

Visual Studio Code executes 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.

1. Select **Step Into** or press <kbd>F11</kbd>.
1. Select **Run** > **Step Into** or press <kbd>F11</kbd>.

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

1. Respond to the prompt by entering a string in the Terminal tab and pressing <kbd>Enter</kbd>.

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

1. Select **Step Into** or press <kbd>F11</kbd>.
1. Select **Run** > **Step Into** or press <kbd>F11</kbd>.

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

1. Select **Step Into** or press <kbd>F11</kbd>.
1. Select **Run** > **Step Into** or press <kbd>F11</kbd>.

The **Variables** window shows the value of the `date` variable after the assignment from the <xref:System.DateTime.Now?displayProperty=nameWithType> property.

1. Select **Step Into** or press <kbd>F11</kbd>.
1. Select **Run** > **Step Into** or press <kbd>F11</kbd>.

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.

1. Select **Step Out** or press <kbd>Shift</kbd>+<kbd>F11</kbd>.
1. Select **Run** > **Step Out** or press <kbd>Shift</kbd>+<kbd>F11</kbd>.

:::image type="content" source="media/debugging-with-visual-studio-code/step-out.png" alt-text="Step-Out button":::

Expand All @@ -199,7 +199,7 @@ Visual Studio Code also allows you to step line by line through a program and mo

1. Press any key to exit the program.

## Select Release build configuration
## 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 affect the behavior of an application. For example, compiler optimizations that are designed to improve performance can create race conditions in multithreaded applications.

Expand Down
Loading