If you've heard of SourceLink already you know what is coming and how this will boost your productivity. If you haven't heard of it yet, no worries! In this post I will tell you what it is and how to get started with it for Xamarin.Forms. Since the Forms 4.3-pre1 package is out now, you can enjoy all of this; today!
What is SourceLink?
There are countless times where I wondered: "what am I doing wrong? What am I missing?" While developing an application. Developing apps with Xamarin.Forms is no exception to that. Whenever some strange behavior popped up, you would try to work around it and simultaneously ask yourself: is this something I am doing wrong? Or is this maybe a bug in the Xamarin.Forms framework?
Because of who I am I typically tend to think it's just me. But at Xamarin, Microsoft or anywhere, we're also just humans. That is until the AI takes over... But what that means is that bugs happen! Mistakes happen! We try to do everything we can to not let it happen, but it happens. And that is why SourceLink can help boost your productivity.
With SourceLink you are able to debug a libraries code. In this case: you are able to debug Xamarin.Forms right from your own code 🤯. That means, whenever you are in doubt if something is a bug on "your" side or "our" side, this will make it much easier to detect. You can simply step into the Xamarin.Forms framework code and see what is going on under the hood. The debug experience will be the exact same as it is for your local code.
What Does This Solve?
Excellent question. There are multiple scenarios that you could think of. The most basic one is the one I just described above: see if the Xamarin.Forms framework behaves the way you expect it to.
Another scenario could be one where you want to open an issue on the Xamarin.Forms repo and want to provide detailed info. With SourceLink you can easily step through both your and the Xamarin.Forms code and provide all the details needed for a quick solution. No need to hook up your app to self fabricated NuGets or the actual Xamarin.Forms repo clone. Just remember we would still very much appreciate a small reproduction project 😉
How Does SourceLink Work?
For the end-user it is pretty simple. Whenever you run into an exception or you step into a method that belongs to Xamarin.Forms (or any other library that supports SourceLink), you will simply get a dialog asking you what you want to do. You can see an example below.
You can see that you can acknowledge that you want to download the external source (straight from GitHub!) and start debugging from there. You can also check the box to remember this setting and not having to accept each time. In your Visual Studio for Mac preferences you will also find some new settings where you can (re)set this preference.
From there, debugging and stepping through the code and inspecting values, etc. works like you would debug your local code.
Under the hood what basically happened is that the NuGet package now holds a reference to the hosting repository (can be other than GitHub as well!) and correct commit. That is why the IDE now knows where to go look for the code. Then when you step into library code, the right file is downloaded into a cache and you can step through it. Very much simplified that is what's happening.
If you need to clean or inspect the cache for some reason, on Mac you can find it here: ~/Library/Caches/VisualStudio/8.0/Symbols. From there you should find the name of the manufacturer and the libraries that you are using, etc.
How to use SourceLink, today?
For SourceLink to work there are a couple of things that need to align. First, the debugger should have support. While the regular debugger on Windows does have support for a while, the Mono debugger did not. Until the Visual Studio for Mac 8.3 preview was released. Jason Imison (and team) did a great job implementing the bits for the debugger and Visual Studio. Notice that I am only writing about Mac for now. Visual Studio on Windows does have support for the most part, I think only the debugger for Xamarin is lacking support at the time of writing. I'm not completely up-to-date on the timeline, but I think it should follow soon.
In addition, the NuGet package that you want to consume needs to support it as well. To add the support is pretty simple, but necessary. That is exactly what we have done for Xamarin.Forms. In the video below you can see what happens if you step into the Label's constructor when using all the bits mentioned above.
This is an amazing piece of technology, right?! Hopefully a lot of other libraries will implement this as well now that it is supported from Visual Studio for Mac. This can be really helpful for both parties: library authors and consumers.
For Xamarin.Forms I hope this will help you debug your code and see what is going on more transparent than ever. With this new power comes new responsibility. I personally hope that this will also help you report issues to the Xamarin.Forms repository. With SourceLink you should be able to pinpoint the cause of a certain behavior pretty accurate, which is really valuable information to us. This can really help speed up the process from triaging the issue to fixing it.
Together with Hot Reload, you will now be an unstoppable Xamarin.Forms developer! I'm very curious to hear your thoughts on all of this, so don't hesitate to reach out.
Hero image designed by rawpixel.com / Freepik