Improve docs on debugging ASP.NET Core product source in VS 2019

[billti]

Opening a new issue, as dotnet/aspnetcore#9350 is closed, but it is in line with what @Sebazzz was trying to achieve I believe. (I guess it related to dotnet/aspnetcore#27380 also).

The docs/wiki aren't that clear on how to set up a local environment for running and debugging the ASP.NET Core source (preferably without running an installer which results in non-local changes). This is really helpful not just as a learning aid, but also for developing and debugging the product.

I spent a while trying to get this set up the past couple of days, and ended up with a simple / productive workflow. I wrote up what I ended up doing at https://ticehurst.com/2021/04/06/debugging-asp-net.html . If this looks roughly right, I'm happy to contribute to a wiki page or markdown file to help others. (And if it isn't quite right, happy to fix it up and then contribute).

@natemcmaster mentioned he was trying to make debugging the source easier, and @Pilchie had some suggestions for working with NuGet packages (which was my biggest pain), so tagging here to see if they have input.

The docs are great, but it really clicked for me after being able to seamlessly step through the code for some of the more complex or nuanced stuff. Let me know how I can help! Thx.

[Pilchie]

This is great - thanks for the writeup @billti. I would welcome a PR to contribute it.

I am curious though - did you actually need to modify source from the ASP.NET Core repo, or did you just want to debug through it? If the latter that should work pretty seamlessly in VS without needing to build locally - all of our symbols should be indexed on the public symbol server, and the pdbs include SourceLink information which should mean that sources get fetched automatically.

@Rick-Anderson - To me this feels like something repo focused enough that we would just leave it as an md in this repo, and not put on docs.microsoft.com. What are your thoughts?

[Rick-Anderson]

I've got links splattered throughout the docs to Debugging .NET Core and ASP.NET Core sources dotnet/aspnetcore#4155

Perhaps I need more links to that issue.

[billti]

To @Pilchie 's question... yes, I mention in the write-up that due to indexing of source & symbols it does mostly work. The issue is with release binaries I often see things like variables being optimized away and unavailable, methods not be available in the "Step into specific..." if they've been inlined or optimized away, other awkward stepping behavior (e.g. not stepping linearly, or just landing me in the Task machinery on occasion for some reason).

The below image shows an example (which I'm sure you're familiar with). I literally just stepped over the line that assigned to target (in "src\Security\Authentication\Core\src\AuthenticationHandler.cs"), but the debugger can't show me its value. With a local Debug build the debugger works awesome, and obviously if I was making changes and wanted to verify them in a running project after I made them this would be helpful too.

I'd note in the issue I referenced (#9350) @Sebazzz opens with pretty much the same need, namely "I'm trying to troubleshoot why I'm having authentication issues. For this I need to debug inside the ASP.NET Core libraries. Source link does not suffice because I need to go through many small inlined methods or async methods and the debugger can't make head or tails of the locals in each method or skips method calls altogether. So I need debug libraries and not the consumable release binaries."

If you have feedback on where and how (i.e. any style guidelines) you'd want a contribution, happy to write it up. Thanks.

[Pilchie]

Ah - right. I wonder how much of that would go away if the JIT knew it was operating under the debugger. @jeffschwMSFT is there a way to get the JIT to ignore R2R data and JIT more debuggable code for things like ASP.NET Core runtime packages? (Something like the old COMPLUS_ZapDisable environment variable?) If so, I wonder how we could make it clearer to users as an option?

[jeffschwMSFT]

We have an equivalent setting for r2r: https://docs.microsoft.com/en-us/dotnet/core/run-time-config/compilation#readytorun.

[Pilchie]

So, for optimal debugging, would you set:

set COMPlus_ReadyToRun=0
set COMPlus_TieredCompilation=0
set COMPlus_TC_QuickJit=1
set COMPlus_TC_QuickJitForLoops=1

or does having a debugger attached mean that the the last 4 aren't needed?

[jeffschwMSFT]

The goal is to have reasonable debugging without having to set any configuration. That set of configs is a balance of performance and debuggability. Adding some folks to validate that the degraded debugging experience is not unintentional.

cc @JulieLeeMSFT @mangod9 @tommcdon

[JulieLeeMSFT]

cc @BruceForstall if he has comments.
Not specificaly related to this issue, but yesterday I had discussion with @BruceForstall on improving debugging experience in general for Release build, which can be our future work area.

[tommcdon]

Visual Studio has some existing documentation on debugging pre-compiled framework code: https://docs.microsoft.com/visualstudio/debugger/jit-optimization-and-debugging?view=vs-2019#limitations-of-the-suppress-jit-optimization-option. In my experience setting COMPLUS_ReadyToRun=0 and check boxing Debug->Options->Suppress JIT optimization on module load resolves most .NET core framework debugging issues.

[davidfowl]

Can't we make this automatic?

[tommcdon]

setting COMPLUS_ReadyToRun=0 and check boxing Debug->Options->Suppress JIT optimization on module load resolves most .NET core framework debugging issues.
Can't we make this automatic?

I've opened internal devdiv bug 1310497 to track the request

[dougbu]

@tommcdon where would the fix for 1310497 likely be done❔ I'm considering marking this bug as external but don't wanna do that if the fix would be in this repo 😃

[tommcdon]

@tommcdon where would the fix for 1310497 likely be done❔ I'm considering marking this bug as external but don't wanna do that if the fix would be in this repo 😃

The work will be in Visual Studio, and so marking the issue "external" is correct.

[dougbu]

Suspect 1310497 isn't planned for immediate work. If that's the case (@tommcdon❔), we should move this issue to one of the docs repos. The specific request would be to document

set COMPlus_ReadyToRun=0
set COMPlus_TieredCompilation=0
set COMPlus_TC_QuickJit=1
set COMPlus_TC_QuickJitForLoops=1

or "setting COMPLUS_ReadyToRun=0 and check boxing Debug->Options->Suppress JIT optimization on module load".

If we go w/ the second option, which is the right repo @Rick-Anderson❔

[Rick-Anderson]

If we go w/ the second option, which is the right repo @Rick-Anderson❔

https://github.com/dotnet/AspNetCore.Docs/issues

I can fix this next week.

@tommcdon I'll show all approaches but it seems like for Visual Studio, runtimeconfig.json and the project file are the easiest. For those who want to set it once, use setx COMPlus_ReadyToRun=0

[dougbu]

Transferred issue though @tommcdon may push for a change in VS to make things easier. Later comments make the action @Rick-Anderson expects to do more clear.

[tommcdon]

Suspect 1310497 isn't planned for immediate work. If that's the case (@tommcdon❔), we should move this issue to one of the docs repos...

Transferred issue though @tommcdon may push for a change in VS to make things easier. Later comments make the action @Rick-Anderson expects to do more clear.

I think it is reasonable to document in the asp.net docs repo. The workaround would be to:

1. Set COMPlus_ReadyToRun=0 in the project system to disable Ready to Run
2. Enable Suppress JIT optimization on module load in the debugger to JIT the framework code as debuggable

The Visual Studio project system provides mechanisms for setting environment variables in the project system. Adding @tmeschter who might know where that is documented.

[billti]

I will note, I found it interesting that the VS Code extension does document some of these settings for launching its debugger. Might want to align guidance there. See https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger-launchjson.md#suppress-jit-optimizations

[Rick-Anderson]

The Visual Studio project system provides mechanisms for setting environment variables in the project system. Adding @tmeschter who might know where that is documented.

It's documented here

cc @vancem

[tmeschter]

It's documented here

That shows you how to turn on Suppress JIT optimization on module load. To set the COMPlus_ReadyToRun environment variable, you need to update the launch profile that will be used on F5/Ctrl+F5.

Open the drop down menu on the "Start" button, like so:

and then update "Environment variables":

Note we're working on bringing back the grid we used to have for environment variables in the old UI, but for the moment you'll need to edit them as text.

These settings all get saved to the launchSettings.json file associated with the project and are also available when using the dotnet cli.

[Rick-Anderson]

It's documented here
but it was badly out of day, two versions out of date so I PR'd it just now.

These settings all get saved to the launchSettings.json file associated with the project and are also available when using the dotnet cli.

That's my PR fix, just add the settings to the launchSettings.json file. Much easier and when the UI changes, no need to update the doc.