Today we are releasing our first experimental preview of debugging for the new ASP.NET Core CLI toolset in Visual Studio Code. Before I continue it’s important to note a few things:
- This support is for the new prerelease .NET Core CLI toolset; it does not work for the existing DNX experience (see the ASP.NET teams Q&A blog post to understand the changes).
- VS Code’s IntelliSense does not yet work with the .NET CLI tools. So if you want to try out debugging, IntelliSense won’t be available for the CLI project type.
With this first release you get breakpoints, stepping, variable inspection, and call stacks.
However, given the very early stage of .NET Core and the debugging experience there will be some features you might be used to in the Visual Studio IDE that we don’t have in VS Code yet. These include:
- No separate console window is created when you start debugging, all program output appears in the Debug Console of VS Code. This means that to use Console.ReadLine in a console application during debugging you have to start the application with dotnet run outside of VS Code and then attach the debugger.
- No Edit & Continue (the ability to modify code and have the changes applied while debugging)
- Cannot edit the value of variables during debugging
- No TracePoints or Conditional breakpoints
- Set Next Statement is not supported
We are very interested in your feedback to help us prioritize addressing these as covered at the end of this post.
Getting started
To get started you will need to do a few things (see our GitHub page for complete instructions)
- Install (or upgrade to) Visual Studio Code version 0.10.10 or greater
- Install the .NET CLI tools
- Install the C# extension
- Open any .cs file in VS Code to load the extension and complete the installation (view progress in the Output pane)
- Install mono
Things you get while debugging
- Breakpoints– set breakpoints with one click (or via F9)from the editor
- Watches– define expressions that you want to keep an eye on
- Locals– see the value of local variables automatically
- Call Stack– find information on method calls on the stack
- Debug Console– shows you all debug messages (show and hide this pane using Ctrl+Shift+Y or Cmd+Shift+Y on a Mac)
- Current values– hover over variables to see the value
- All panes show coordinated values – whenever you click an entry in the Call Stack you automatically jump to the corresponding line in the editor and watches and locals are updated
What else can you configure for debugging?
Once you install and configure the extension you will have the basic debugging experience describe above, but there is much more you can configure using the launch.json file.
Stop at Entry
Setting the stopAtEntry flag will cause the debugger to break immediately on the entry point to the application. This allows you to start stepping through your code without setting breakpoints.
Configure debugging for ASP.NET applications
Besides the default debug configuration there’s a configuration called .NET Core Launch (web) which is a good starting point for debugging ASP.NET applications. It contains an additional section “launchBrowser” that is used to open up a WebBrowser on your development machine whenever you start debugging. Per default it is configured to use the default browser but you can specify alternative browsers if you modify the commands in file accordingly. To get started and to give ASP.NET a try just download the ASP.NET CLI samples from Github .
Here’s what a configuration of launch.json would look like if you configure it to open a page with Opera.
…
"osx": {
"command" : "open",
"args" : "-a opera ${auto-detect-url}"
}
…Modify launch URL
The URL the browser navigates to is configurable as well. If you stick to the defaults the debugger figures out the URL automatically and targets to the default URL the server listens to. ${auto-detect-url} serves as placeholder to find the URL automatically and you can use it anywhere in the configuration. For a scenario where you’d like to always debug a certain URL path like http://localhost:5000/api/customers/42 , you can overwrite the default value to avoid the manual navigation process.
Attach scenarios
For attach scenarios a third configuration section is integrated. All you have to do here is specify the process name of the application you want to debug. In our case this would be HelloWorld. If you spin up your application from the command line with dotnet run make sure you select the .NET Core Attach configuration first before starting the debugger.
If you have multiple processes running with the same name you can also specify processId instead of the processName. Just make sure you don’t use both properties at the same time.
Hidden configuration properties
There are currently three additional properties that don’t show up in the default configuration. If you wonder how to figure out those properties aside from reading the documentation, here’s a tip: Start typing “o in launch.json (make sure you also type the leading quotation mark) and you’ll get an auto-completion that shows you a list of properties containing an “o”.
While this is very handy when you’re already editing, you might want always up to date documentation. As always the truth is in the code, and if you want to dig a little deeper you can take a look at the installation folder of the extension where you will find a file called package.json . Consider this file as the master template for valid configurations. It gives you a very good overview about configurations possible on your machine for your current version of the extension in easy to understand and human-readable json.
symbolPath
You can use “symbolPath” to specify an array of paths to your debugging symbols. This can be very helpful if your symbols are located on a central server and when you are working across multiple operating systems. Symbols generated on one specific operation system also work cross platform.
A valid configuration of the symbol path is shown below.
“symbolPath”:”[ \”/Volumes/symbols\” , \”/OtherVolume/otherSymbols\” ]”
justMyCode
When you are in a debug session you might not be interested in stepping into framework code or into code of components you haven’t written. This is the reason why we came up with justMyCode. This feature is enabled per default as it seems to be the preferred setting for most debugging situations. However, if you want to debug framework code or external components you can enable this by setting it explicitly to true.
“justMyCode”:true
sourceFileMap
If you want to point the debugger to the corresponding source files for your debugging session you can specify a mapping table using the sourceFileMap property. This property can have any number of entries and will make sure the debugger works with the source code files you want it to work with. A configuration could look like this.
“sourceFileMap”: {
“C:\foo\bar”:”/home/me/foo/bar”
}Send us your feedback
As mentioned at the beginning of this post, the current debugging experience is our first experimental release, so we need your help to make it better. If you are interested in receiving regular updates about our progress and opportunities to provide feedback in developing .NET Core applications in Visual Studio Code join our Visual Studio Code .NET Core Insiders group.
As always we welcome your feedback. Tell us what you like and what you don’t like, tell us which features you are missing and which parts of the workflow work or don’t work for you. You can do this by sending us an email, submitting issues on our Github page or contacting us via Twitter.
About the author
Daniel Meixner is Developer Evangelist at Microsoft in Germany and a strong believer in cross platform approaches. He has experienced his fair share of the good, the bad and the ugly during his career in software development and is familiar with the industry from many different angles. Before he joined Microsoft he was an MVP for Visual Studio ALM, ALM Ranger and consultant and architect for ALM solutions in enterprise environments. Find Daniel’s blog on http://DevelopersDevelopersDevelopersDevelopers.NET or follow him on Twitter.