Add a documentation to your ASP.NET WebApi in 3 simple steps

A well documented API is a welcome part of every software project. Everyone wants a great documentation, bot nobody really wants to write one. Especially when creating an API which many different people should use, this aspect becomes very important. Furthermore many Scrum teams’ acceptance criteras contain a documentation requirement.

Your luck, that ASP.NET 4.5 comes with a build in API-Documentation functionality that you can implement in three very easy steps:

1. Add build-in ASP.NET WebApi Documentation

Microsoft provides a build-in documentation functionality with its WebApi. When creating a new WebApi Project in Visual Studio, the template already contains a documentation implementation. If you created the WebApi project from scratch, you can add it by loading the NuGet package Microsoft.AspNet.WebApi.HelpPage into your project.

Both ways will create an Areas/HelpPage folder, which contains a bunch of methods and classes that will do the documentation work for you. From now on you can access your documentation at the {YOUR_URL}/Help page.

2. Document your code properly

The smartest way to document your methods and classes in C# is the XML-Documentation approach, that comes with .NET 4.5. This documentation style looks like this in your code:

Hint: You can generate this XML-Documentation header by typing three slashes /// above a method or class.

By using this way of documentation, you do not only create a documentation for your Help page. This information is also used inside of Visual Studio to describe a method and its parameters when using code completion and Intelly Sense.

3. Enable documentation access

To give your Help page access to this documentation you need to enable the XML-Documentation output. By doing this, every time you build your project an XML file is generated that contains your documentation comments. To enable this, you need to select the proper checkbox in the project properties, that you can find at the Build tab.


Hint: By enabling the XML-Documentation output, the compiler will send you a warning for every method or class that is undocumented. If you want to avoid that, add 1591 to the suppressed warnings as you can see in the screenshot above.

Now you only need to tell your HelpPage that you do have such a file and where it is located. To do so, open the HelpPageConfig.cs file, uncomment the following line and edit the MapPath:

Now you are ready to enjoy a fully featured documentation of your ASP.NET WebApi at the {YOUR_URL}/Help page.

Use expressions to build variable names in Angular.js

When working with HTML and JavaScript you sometimes have to do weird things to achieve a specific purpose. In my case one of these things was building a variable name with Angular expressions.

While generating a form via ng-repeat, I also had to generate the name of the input element. For verification, I wanted to add a CSS class to the input whenever it gets marked as invalid. To access it, I had to use the form.element pattern wherefore I wrote something like this, trying to generate the variable name with an expression.


The code above does not only cause errors, it also is invalid HTML so I had to find another way. The solution is replacing the double curly braces with simple square brackets so that the final code looked like this:


This works perfectly and is also valid HTML code. I hope that helps and spares your nerves. If you are looking for another working example, you can take a look at this JSFiddle repository, where I created a tiny demo project to play around with.

Hey Git, why don’t you ignore my recently added .gitignore paths?

In projects with a Git source control you often need to tell your repository to ignore changes to specific files that you don’t want to upload to the server and spread them over to other team members. Typical examples are usually IDE related settings or publish information. For this approach, Git provides the .gitignore file where users can enter paths to those files they want to have ignored by the repository. But sometimes this does not seem to work.

In most cases the .gitignore does not work for the same reason: The files you want to ignore have already been added to the repository once. Since then, Git watches about their changes, no matter if they have been added to the .gitignore afterwards or not. To ignore already added files afterwards we need to help ourselves by using a trick.

The shortest way to archive this is removing all files from the git repository and adding them immediately afterwards. This sounds like a huge intervention but is is not that heavy as it seems.

Important: Please commit all outstanding changes to the repository before doing this. Otherwise they will get lost.

Now your .gitignore is working as it should be and you get rid of unwanted files and folders in your repository.

Get rid of cables and Remote Debug your Android device!

Cables are a companion of our everyday life but a necessary evil. I personally avoid using them wherever it is possible and even charge my phone wireless. As a mobile developer you always have a bunch of cables in you bag but the time may come where we do not need them anymore. Remote Debugging could be one step into this direction.

Since Android Lollypop it is possible to deploy your apps via Wifi to your device and debug them there. It can look like magic, when your phone gets remote controlled and states app by his own but is is definately not.

Important: To archive this, your development machine and Android device need to be in the same local network, of course!

Prepare your phone

set_remote_debuggingdeveloper_settingsTo enable Remote Debugging on your phone, you need at least Android 5.0. Go to Settings, select Developer Options and enable the Android Debugging and ADB over network options. That’s it! All you need to do is remember the displayed IP Address, we will need it later.

Setup your PC

Using a Windows Machine you first have to add the location of your Android Platform Tools to the PATH environment variable. These platform tools come with the Android SDK so the path to add ususally looks like this C:\Program Files (x86)\Android\android-sdk\platform-tools.

Afterwards you should be able to access the ADB via command line. To test this, you can simply type adb version. If this works you can connect your device by hitting adb connect followed by the IP Address that your device displayes inside the debug options.

Now you are ready to debug over network and should now see your device listed in the debug target selection of your development environment. Have fun debugging you apps on a real device without any cables and remember to switch debugging off at your phone when you are finished. Otherwise it will kill your battery.

Introduction to UI Tests with Xamarin

One of the things one should never say when delivering an app to a customer- “It was working fine on my device”. To avoid such embarrassment and to make sure the users see what was planned for them to see, test should be written.
I wrote a simple Buzzword Bingo App, called “Bullshit Bingo”, to try and demonstrate how easy it is to write an Acceptance Test with Xamarin.UITests.

About the app:

Bullshit Bingo is game with one simple objective – collect 5 phrases either in a row or in a column. It has 2 Activities – a MainActivity, that holds the controls to start the game, and a GameActivity, that shows the actual bingo card the user interacts with.


When I created my Xamarin.Android Solution, it came with two projects – BullshitBingo and BullshitBingo.UITests. In UITests there is a sample Tests.cs file, where the magic happens.

Each UI test should follow 3 simple steps: Arrange, Act, Assert:

  1. Setup your test, initialize things needed at a later point
  2. Do some actions, interact with the app
  3. Make sure you got the right result.

In order for Xamarin.UITests to know what to run in the project, the classes need to be annotated as [TestFixture] and the methods as [Test].

For this demo, I wanted to test only the winning conditions of the app, so I had to make sure the tests were autonomous. To do that, I defined a method, to run Before Each Test to reset the app to it’s original state:

REPL is a great tool to explore the UI and view details about all elements displayed in the current view. It helps to generate a sequence of actions to be used in the test later.


So my test for the horizontal winning condition looked like this:

I found out, that when it comes to switching between activities, it’s better to wait until the elements from the new activity are loaded with app.WaitForElement() and not rely on UITest to do that for me. In 5 out of 10 runs the test tried to tap on an element that didn’t exist.

TL,DR: Test are important, use Xamarin.UITest, it’s very easy, see the Introduction to UITest for a reference to all possible user interface interactions IApp has to offer.

Upload your UI Tests to the Xamarin Test Cloud

Whenever app development gets more serious and your code becomes more complex, testing your application automatically is a step you need to go to survive. Xamarin provides two neat ways to write UI Tests for your applications. Calabash is a framework you can write tests in Ruby with and Xamarin.UITests provides everything you need to build test cases in C# the NUnit way. Whichever framework you choose, you can write tests for your application very easily and run them on an emulator or local device.

With both ways you can cover a managable range of devices which might not be enough to test how your applications perform in the real world. Especially when developing for Android, fragmentation is your daily companion and is not to be underestimated. Your application may run fine on all of your test devices and emulators but crashes on 80% of the rest.

Xamarin Test Cloud

This is, where Xamarin Test Cloud comes into play. It provides you a way to upload your app and tests to a huge farm of more than 1000 real devices and let them run there. Afterwards you will get a detailed test report of every single device including screenshots and Stack Traces for a comprehensive overview of which devices run your application nicely and which don’t.

I will not cover how to create these test cases in this blog post. If you are interested in the tests, take a look at the sample code at GitHub. What I want to show you today is how to upload your tests to the Xamarin Test Cloud and test your app on tons of devices in minutes.


To use the Xamarin Test Cloud you need at least version 5.9 of Xamarin Studio and a Test Cloud subscription. If you already subscribe to one of the Xamarin Platform plans you can start immediately due all of theminclude 60 monthly device minutes which should be enough for our demo. If you have neither, you can at least take a look at the demo accout.

Uploading your test

To upload your project to the Xamarin Test Cloud, simply right click on the tests and select “Run in Test Cloud”. The following steps run almost automatically and your application and tests are going to be uploaded into the cloud.


Important: Make sure, that you have changed your build configuration to Release and that it does not use the shared Mono runtime and supports the x86 ABI.

As soon as this is finished, your browser pops up and asks you to define your test environment. Basically this is where you can select the devices that should run your test. You can sure between several filters and pre-selections here. I personally liked the “Top 20 devices” option that selects the devices with most market share for you. Make sure that you also add some low end devices to test your application under extreme conditions.


Warning: Keep an eye on your remaining test hours! By selecting 30 devices and letting the tests run for only two minutes, your 60 device minutes that come with your Xamarin Platform subscription are already burned. When creating serious test scenarios, you should consider buying a dedicated Test Cloud subscription.

When all tests have finished you can take a look at the results dashboard where you can see how the tests performed on each device. For every single device you can follow each test and the screenshots that have been taken. This provides you insights of how your design works on the device. If a test fails you can also take a look at the Stack Trace and find out, why it crashed.


This is how I found out that my demo Pollen application seems to have a memory leak when loading the list of pollen with their images which causes crashes on weaker devices, which I never recognized when testing on my emulators and local devices.


Summarizing it up, Xamarin Test Cloud provides a really attractive way to test your apps on a wide variety of devices within a few minutes. Mobile developers know the pain of fragmentation and no one loves deploying their tests to dozens of physical devices the manual way. And let’s be honest, buying 50 different physical devices is much more expensive than one of these Test Cloud subscriptions!

I hope I managed to make Xamarin Test Cloud tempting for you. If you already have a Xamarin subscription it is definitely worth a closer look. Try it yourself – it might be the child you always wanted! Please also feel free to take a look at the tests in the sample code!

How to fix Xamarin Android Player in Windows 10

If you have recently updated your PC to Windows 10 you might have noticed that our beloved Xamarin Android Player does not work anymore. Whenever we try to start it, the error message “Could not configure host-only network. Please reboot the computer and try again.” appears. This problem is caused by compatibility problems that VirtualBox 4 seems to have with Microsofts latest operation system. To fix this, we need to reinstall the Xamarin Android Player and configure the Virtual Box properly.

Step 1
Uninstall the Xamarin Android Player and VirtualBox completely. Make sure that there is no XamarinAndPlayer directory under C:\Users\{YOUR_USERNAME}\AppData\Roaming left. If there is one, delete it.

Step 2
Download the Xamarin Android Player and install it. But do not start it yet! We need to do some other work first!

Step 3
Download and install the latest version of VisualBox. It should be version 5 at least. This will update and clean the version that comes with Android Player at the moment to a version that is more compatible with Windows 10.

Step 4
Now we need to configure the fresh installation of VirtualBox. For this, start it and go to the File/Preferences/Networking page and select the Virtual Host Only tab. Klick on the edit icon for the one existing network adapter and make sure the it is set in the following way:

Save your changes and close VirtualBox. Now we can launch the Xamarin Android Player and start installing the virtual machines available for download. It will find the correctly configured host only network adapter now.

I really hope that helps everybody who is frustrated after updating his system to Windows 10. Huge thanks to Danny Pronk from the Xamarin Forums who found that solution.

Adding Drag and Drop to your Android application with Xamarin

Since touchscreens have conquered our everyday life, drag and drop functionality accompanies us on our way through the digital world. The simplicity of this intuitive design pattern is responsible for its success story. This is why you should enhance you applications by implementing it. And this is easier than you might have thought.

Drag and Drop is part of the Android API since Honeycomb and any View element can be dragged, dropped or work as a drop zone for others. To do so, no additional UI work is needed, you just attach the right events and fire the right methods in your code and you are done. But let’ start at the beginning.


The UI Layout

For the demo you can see on the right I have just created two buttons that can be dragged and dropped to the gray drop zone at the top of the page. As mentioned above, every View element can be dragged or work as a drop zone so that the UI plays no special part in it and I won’t go into it. If you need more detailed information about the shown layout, please check the Sample Code.

The Code

Two steps in your code bring you closer to the Drag and Drop implementation: Enabling elements to be dragged and dropped and defining drop zones. We will begin with the former.

First you need to choose an event on which the dragging should start. In my demo this is a long click on one of the buttons. Inside this event you can start the dragging procedure by simply calling the StartDrag() method on your element. It accepts a ClipData element, a DragShadowBuilder instance, a local state and a status flag as parameters, so let’s take a short look at them. While we can forget the last two for the moment, the ClipData and DragShadowBuilder might be important for us.

ClipData is the only way to provide additional information to the dragged element. When the user drops it later, we can not identify which element got dropped. The only thing we can access is the attached data. So it might be clever to add some kind of identifier here.

The DragShadowBuilder is responsible for generating the drag shadow for the current element. By default this is a half translucent copy which should be good enough for most usecases. If you need something else, you can define your own one. You can find further information about that here.

To define a drop zone, you simply need to listen to the drop zone’s Drag event by adding an according event handler to it. Here you can differ between the Drag and Drop actions that can occur:

DragAction.Ended and DragAction.Started mark the begin and end of the dragging process and just need to be marked as handled. DragAction.Entered and DragAction.Exited actions occur whenever a dragged element enters or exits the drop zone. We could do some fancy UI stuff here like showing a drop hint. The one that is clearly most important for us is the DragAction.Drop action. Here we can decide whether to accept the drop and try to get the attached ClipData to do some further actions with it.


It is really fast and super easy to implement a basic Drag and Drop functionality in your Android application which provides a nice way to enhance your user experience where it makes sense. The latter is very important – not only if you want to add Drag and Drop but whenever you plan to add new UI functionality to you application: Make sure that it makes sense at the place where you want to add it and that it brings a benefit to your users.

If you are sure about this, you can implement it a very clean and simple way without much code overhead. And that is all we wanted, isn’t it?

For a working demo feel free to take a look at our Sample Code.