.png?width=667&height=667&ext=.png)
Debug the Kentico.Kontent.Delivery Source Code Like a Pro
Introduction
Being able to efficiently debug through source code is a critical aspect / skillset to performing the day to day duties of a .Net developer. Typically, using Visual Studio or Visual Studio Code makes this task very easy, however, for awhile now there has been a bit of a loophole to debugging through a full project. That loophole comes to light when a project has different dependencies that were referenced as NuGet packages. That's where traditional debugging stops (since those packages are compiled binaries and not true source code on a local machine).
However, did you know there is actually a better way to handle this for certain NuGet packages? The answer my friends is SourceLink, a technology that allows you solve this issue. I recently had a chance to check this out first hand using the KenticoCloud.Delivery NuGet package since this package recently became SourceLink enabled. I mean why not, as I was doing a little maintenance on my headless CMS project anyways.
The Setup
The setup is rather simple on this one. You must have the following scenario:
- A project created with a dependency that relies on a NuGet package with SourceLink and your Visual Studio version must be 15.3 or higher.
- The NuGet package must be hosted on public GitHub repo, or a secure repo hosted on VSTS / Azure Dev Ops / Whatever Microsoft renamed it to recently.
- I'm pretty sure it works with both the full .Net Framework and .Net Core
- Visual Studio configured with the correct options (see below)
How to Enable SourceLink
The total set of instructions are actually documented well at the Kentico Cloud Delivery SDK project site, so this is a bit more of a walkthrough. It is not actually that hard to get this all to work. The first step for me was to update my solution with the latest build of the KenticoCloud.Delivery package as I mentioned. This was pretty easy, but I did jump from version 4.14.0 to 6.0.0.
This update got me a version of the package that supported SourceLink. It also contained a few other small updates. One of those updates was around the ICustomTypeProvider that I did not expect and caused a compile error.
This error was due to an improvement that the Kentico Cloud team has made to the Kentico Cloud model generator for .Net utility and it's new requirement of this C# type that it generates. That utility is an excellent code gen tool that you can use to model your Headless CMS content in Kentico Cloud and then have it pretty much just work in your .Net solution as structured types. But that whole situation is a blog post topic for another time. If you don't want to regenerate your models, you can simply go with the stubbed out empty implementation and worry about the actual GetCodeName method later. It's not important for SourceLink support.
Once you are up to date, the next step is to change your options in Visual Studio to not just Debug through your own code. As the documentation states, un-check that and then check the Enable SourceLink support box.
Don't be confused with the Enable source server support box, I am an idiot so I actually checked that one first. That's not what we are doing here. Once you then save the options dialog, you only have one step left.
That step is to copy the PDB files from the KenticoCloud.Delivery NuGet package into the bin folder next to your own project PDB files. This is a specific step to Kentico Cloud and not required for all packages, but it is required based on the way Kentico has it setup. If you are not sure where to grab these files you can download the NuGet package from the site, rename the download to have a .zip extension and then extract the files. In the filesystem you should see them in the either the netstandard2.0 directory or net45 directory (choose the correct one for your project):
Now go ahead and start debugging your site. Try to find a breakpoint that would step you into code that is in a dll. For me I went with the ImageUrlBuilder code that I used to generate a responsive image url. I blogged about that previously in my Leveling up a Kentico Cloud project mini series this summer. When the debugger runs you should see this pop-up happen. If you don't see it, something is not setup correctly.
Now one thing that the documentation does not mention is you may see a warning immediately after that looks like this:
This happened to me based on where I placed the breakpoint. I have been clicking Yes on this message to make sure I still know about it this event, however it really is just a decision that is a reminder that you can basically step into one place or the other in the code using the right click menu on that line of code in Visual Studio. For me it looked like this (click the image to see the larger version):
Again, if you see all these popups, that means that SourceLink is working correctly. That's a good thing.
The Results
When it all is working, the final result looks like the following screenshot:
It's actually kind of nice to be able to step through the helper that generates the images.
In case you had any issues setting this up here are two good links on the topic of setting up SourceLink.
- https://www.hanselman.com/blog/ExploringNETCoresSourceLinkSteppingIntoTheSourceCodeOfNuGetPackagesYouDontOwn.aspx
- https://www.meziantou.net/2018/07/09/how-to-debug-nuget-packages-using-sourcelink
Conclusion
I hope there comes a day where GitHub actually mandates that all NuGet packages require SourceLink. I'd also like to thank the Kentico Cloud team for pushing out a new build that includes SourceLink support. As always, the team over there at Kentico is highly concerned with the developer experience of using the Kentico Cloud SDKs and APIs. This is just another way it actually shows.
Have you had a chance to play around with SourceLink, does it work well? Not work well? Let me know via the comments in this blog post. Thanks!
