Debugging and Contributing to MvvmCross

As one of the maintainers of MvvmCross I quite often help triage issues that are raised on GitHub. Issues are a mixed blessing – it’s really important to us that the community logs any issues that they come across so that we have a mechanism to track and resolve them with each release. However, the flipside is that issues become a dumping ground for developers who use MvvmCross, have come across an issue that they want, or need, fixed – they log an issue and assume that other contributors, or the maintainers, will resolve the issue in a timely manner. Before I get into the body of this post which will drill into how to debug MvvmCross, as well as how to proactively contribute to MvvmCross, I want to reiterate the point that open source software, which includes MvvmCross, ships as-is. This means whatever expectations you have of it working, or working a specific way, or any expectations you have on how issues will get resolved, or how quickly they’ll get resolved, are wrong. The only things you really know for certain is that there is source code that’s available for anyone to access and contribute to, and there are some versions of the library that are available via NuGet so that they can be easily consumed by developers. Of course, with this said, the MvvmCross team, like other OSS, do strive to address issues as quickly as they can but we all have day jobs and lives that mean our contribution to OSS is limited. In this post I will be covering what you can do when submitting an issue to make it easy for someone to resolve your issue as quickly as possible.

Debugging with MvvmCross using Source Linking

Note: Source Linking doesn’t work with all platform. If you building a Xamarin.Forms application, it’s worth creating a UWP head just in case you need to debug an MvvmCross issue.

We often get issues raised, either via GitHub, Slack or Stack overflow, that start along the lines of “my application doesn’t start (or crashes) when I do …..” Because the issue often resides within a commercial product that the developer is working on, we don’t typically ask developers to share their solution. Instead what we typically ask is that they use the Playground sample that’s included with the MvvmCross source code and see if they can reproduce the issue.

However, before getting to this point, there is a step that can often help identify the cause of any issue, which is to setup and use source linking to step through the MvvmCross source code. Source Linking is a technique that’s been around for quite some time and is something that MvvmCross has setup to allow developers to easily step from their code, directly into the source code of MvvmCross without any complex setup process.

Getting source linking to work isn’t always as easy as it should be. There are a few websites that cover how to enable source linking (such as this post by Cameron Taggart) and they all basically say the same thing, which is that to enable source linking you need to check the Options >> Debugging >> Enable Source Link support checkbox in Visual Studio.

Update: Whilst you’ve in Options, you can uncheck the “Enable Just My Code” as this setting will mask any internal exceptions that may be thrown during start-up. In the current version (6.1.2) there is an issue whereby exceptions raised during the start-up sequence in the Setup class are swallowed, preventing start-up completing. This will manifest differently on each platform but for a Xamarin.Forms application it may result in a white-screen being displayed on start-up and never proceeding to the first page of the application. Unchecking this option will mean that VS will break each time an exception is raised, allowing you to see the cause of the exception.

However, what’s not covered is what do you do if this doesn’t work. I don’t have a definitive answer either but I did find that after I toggled a few of the options (eg Enable source server support) I was able to get source linking to work.

Once you’ve got Source Linking enabled, how do you use it? There are a couple of options but they amount to the same thing – you need to trigger some debugging action that will allow you to step through the source code. The first option, and one that will work if something is going wrong within MvvmCross that may be triggering an exception that’s handled/swallowed. In this case you’ll need to change your Exception Settings so that all Common Language Runtime Exceptions cause Visual Studio to Break. After changing this setting, if an exception is raised within MvvmCross, you’ll be able to step through the code at the point the Exception is raised.

 

The next option is to put a breakpoint in a method that overrides a method defined within MvvmCross. For example in the ProxyMvxApplication class, which inherits form MvxApplication, we can override the ReigsterSetup method and place a breakpoint in the method.

When the breakpoint is hit, you can see in the call stack that there are methods in the MvvmCross library.

Double-clicking on one of these lines will trigger the source code to be downloaded so that you can then step through the code. However, before the source code is downloaded, you may see the following prompt:

At this point you can opt in or out of source linking for this debugging session. Once you agree to Download Source and Continue Debugging, the cursor will be taken to the appropriate line of code and you can continue your debugging session.

As you can imagine, being able to step through the MvvmCross code means that you can try to identify what might be causing the issue you’re seeing. It’ll also mean that should you need to log a GitHub issue, you can provide us with a much more detailed description of what’s going on.

Contributing to MvvmCross

Contributing to OSS can happen at various levels, mainly depending on the amount of time someone has available and their inclination to help the community. For most developers their first contribution to MvvmCross will be in the form of a new issue. When submitting an issue, it’s important that you select the most appropriate issue template as a starting point.

As a community we welcome all feedback and encourage developers to raise an appropriate issue. Whilst we will respond to “Questions and Help” issues, we’d prefer it if you reached out via Slack or StackOverflow and actually talk to us!

It’s important to remember that in order to follow up on an issue we need as much information as possible. For example, information on how to reproduce an issue is invaluable. Providing a series of steps on how to reproduce an issue is a good starting point, and will help reduce the amount of time it takes to try to work out what’s going on. Alternatively, instead of just listing steps, a better way to demonstrate an issue is to use the Playground sample that’s included within the MvvmCross source code and reproduce the issue there. Once you’re able to reproduce the issue, you can submit a PR for review which may form the basis for resolving the issue.

Quick Steps for Resolving Issues:

• In your solution: enable all exceptions in the Exception Settings window of Visual Studio – this will point out if an internal exception is occurring
• In your solution: enable source linking where possible – this will allow you to step through MvvmCross source to try to work out what’s going wrong
• In the Playground sample app in MvvmCross: attempt to reproduce the issue
• Ask on Slack (or Stackoverflow) for assistance from the MvvmCross community
• Raise an issue on the MvvmCross GitHub
• Submit a PR with the changes to the Playground sample that demonstrates the issue

Note: When submitting a PR, please mark the PR as work in progress by putting [WIP] at the beginning of the title. This will prevent the PR from accidentally being merged. Also, please link the PR to the issue so that it’s easy to understand the purpose of the PR.

You might be asking why I’m asking that you submit a PR. It’s for two reasons:

1) I’m lazy – when I read your issue, it requires quite a bit of effort for me to reproduce the issue. If you provide a PR, I can simply pull your branch, run up the Playground and see the issue for my self. Not only that, I can also commit changes directly on your branch which means I can fix the issue straight away.

2) I want you to join the MvvmCross community – you only really join the community when you start contributing code to the project. By getting you to submit a PR, you’re breaking the ice and getting involved. The PR is a WIP so there’s no judgment from the community; in fact they’ll be impressed that you’re willing to get involved. We’ll often reach out directly to you and discuss the issue.

The upshot is that by submitting a PR you have a much higher chance of getting your issue looked at #NoGuarantees