When and how should I file a bug report?

File a bug if...

You have a set of steps you think the engineers will be able to use to reproduce a problem.

OR

You can carefully describe the visible symptoms of the problem, especially if you can also describe some precise circumstances related to the problem.^[1]

Best practices to help address bugs quickly and efficiently

1. Search Visual Studio Developer Community and the web for existing bug reports or usage suggestions that might address the problem directly.^[2][3]

2. Describe the problem as clearly and concisely as possible, including a description of what happened and was expected to happen.

3. Include any relevant stack traces, error message text, or crash logs (if you use the Report a problem feature, these can be included automatically). ^[4]

4. Write down any important error messages that appear in screenshot attachments as plain text too.

5. Include a small, self-contained test case that reproduces the bug with as little code as possible. If you cannot reproduce the problem with a brand new project (created using one of the built-in templates), then please zip up a project that demonstrates the problem and attach it to the bug report. Make the example project as simple as possible before attaching it.^[5][6]

6. Describe the environment where the bug was encountered, including the operating system and versions of Xamarin and any dependencies.

Additional details

1. ^ Ideally the description of the "visible symptoms" should include enough details so that other customers can confirm whether they are seeing the same problem (same error messages, same performance degradation, same stack trace from a crash, etc.). For "precise circumstances", one good example would be if you can say something like: "I normally hit the problem 75% of the time, but if I change this one thing then I can avoid the problem completely." Another similar example of a "precise circumstance" is if downgrading to a previous version of Xamarin stops the problem.

2. ^ As you would expect, snippets of error text (or any other uniquely descriptive text) are usually the best search terms. If the existing bug report is incomplete, then you are welcome to add details or file a new, better bug report.

3. ^ Another good question is whether the same problem has been reported for any Java, Objective-C, or Swift apps. If so, then the problem is very likely part of Android or iOS itself rather than part of Xamarin.

4. ^ A few examples of information to include:

   1. For errors that occur when building a project, please include the complete diagnostic build output on the bug report.

   2. For errors that occur when building or debugging an iOS project from Visual Studio, please run Help > Xamarin > Zip Logs after hitting the error and include the resulting .zip file on the bug report.

   3. For exceptions or crashes in Android or iOS apps, please include the relevant Debug logs for Xamarin.Android and Xamarin.iOS apps.

5. ^ If possible for your particular problem, one option is to recreate the problem by adding a small number of files from your original solution into a brand new solution. The Xamarin team will often be able to investigate problems even on larger test cases (assuming the steps to reproduce are explained clearly), but simpler test cases give the best chance that the bug will be resolved quickly.

6. ^ If it is not possible to reproduce the problem by adding a small number of files to a brand new solution, then you can zip up and attach the whole solution folder for your full app. Please delete the bin, obj, Components, and packages folders to make the zip file smaller. (The IDE and the build process will usually restore or recreate the contents of these folders as needed.) You can also delete as many code and resource files from the project as you like, as long as the resulting solution still demonstrates the original problem.