Getting ready for Xamarin University with Windows

Welcome to Xamarin University! This guide is to help you get your Windows development environment setup and ready to go before working through any of the Xamarin University materials. This will likely take at least an hour to complete so give yourself plenty of time to setup and validate your system.

If you have any trouble, the final half of XAM101 - Orientation and Welcome is devoted to 1:1 time with a trainer to solve setup issues. Just enroll in one of the upcoming classes and then you can get specific help from an expert.

In addition, we have a XAM101 FAQ which answers some common questions about setup and Xamarin University.

Hardware

Any development-class machine capable of running Windows 7 or later should be fine. Make sure you have the latest graphics drivers installed as Visual Studio and the Android emulators all utilize hardware acceleration. In addition, the machine will ideally support Hyper-V.

Step-by-step instructions

The Xamarin documentation portal has detailed setup and install instructions for Xamarin.

We also have a Windows setup video available which walks you through the steps to installing Xamarin on your development machine.

Here's the basics:

  1. Verify your PC is running Windows 8, or 10. Windows 7 is also supported but not recommended as it doesn’t get tested as much now and may have issues.

  2. Make sure you have at least 40-50G of free disk space – the IDE, Android emulator images and associated SDKs are all quite large.

  3. Install Visual Studio 2015 with Xamarin from xamarin.com/download. The installer will automatically download any missing tools and SDKs needed for iOS/Android development. If you don’t have Visual Studio installed, it will install the free Visual Studio 2015 Community edition; if you do have it installed, it will add the Xamarin development tools to your existing IDE. This might take a while depending on what is already installed since it may have to download fairly large SDKs.

Note: if you have an MSDN subscription, then use that to install Visual Studio first – it will ensure you have the proper license (e.g. Community vs. Pro vs. Enterprise)

When installing Visual Studio, make sure to do a custom installation and ensure the following things are checked during the install. Otherwise you will have to install them one-by-one later on and that will take more time.

Here is the current VS installer with the specific options checked,

In the Cross-platform section – make sure C#/.NET (Xamarin) is checked as well as the Emulator for Android.

Once the installation completes (and you’ve performed any request reboot), launch Visual Studio.

Xamarin update channels

In order to keep up with the rapidly changing mobile landscape, Xamarin updates the development platform quite frequently. There are three update channels available with Xamarin:

You can check or change which channel you are on using Tools > Options > Xamarin > Other menu.

Pairing Windows with a Mac host for iOS development

If you plan to do iOS development, you will need Visual Studio on your PC and a Mac host computer with the Xamarin tools installed. You will do your development on the Windows computer in Visual Studio and the Mac will build and package the iOS application using Apple’s tools. The two machines can be the same physical machine (e.g. using virtualization software such as VMWare or Parallels) or two separate physical machines as long as they are on the same network and able to ping each other.

Warning: when they are separate machines, it is best to have them on a wired network connection to avoid performance issues in transferring data. In addition, make sure that the network you are connecting to allows for peer-to-peer communication as most open networks do not. You can connect the two machines directly with a cross-over cable and hard-wired IP addresses if all else fails.

It is highly recommended that each developer have a unique Mac machine to work with. While multiple connections are, in theory, possible, it is against the Apple licensing. Additionally, the simulator and build tools are CPU intensive; having multiple instances running drastically slows everything down and can cause both performance issues and build/runtime failures.

Using virtual Mac images

While we prefer local networked Macs for the build host, there are several cloud providers which support Mac images, including http://www.macincloud.com/ and https://www.macstadium.com/. As long as the machines are hosted on a public IP and have remote access enabled (via SSH), you can use them as build hosts, just recognize that a very fast Internet connection will be necessary to provide any decent level of performance.

You will need to do all the below steps on the cloud-based Mac, just like the local variation.

Setup the Mac to use as a Build Host

Setup Visual Studio to use your Mac as a build host

As a first step, make sure you can ping your Mac host and remotely connect to it from your Windows machine through ssh. You can install a free tool such as PuTTY to perform this test. This will verify that no firewall restrictions are in place.

It will list all the located Macs on the network in the dialog, or you can add a specific Mac by name/IP by clicking the Add Mac... button. This second approach is required if the network doesn’t enable network discovery.

Select the Mac you want to use as your build host and click Connect. If you have never connected to this machine before, it will use Remote Login, retrieve a SSH fingerprint and prompt you for your username/password. This password is not cached; instead, the SSH key will be used to access the device.

It will then log into the Mac and cache the fingerprint for future logins. The dialog will close automatically and the computer icon on the Options dialog will now be in color to indicate you are connected to a Mac agent.

If any of these steps fail, there are some diagnostic logs you can check, both on Windows and on the remote Mac host. Read through the Mac build host troubleshooting guide for more information.

Running mobile applications

As you design, build and run your applications, you will want to test them locally before making them available to the world. You have two choices for local testing:

  1. Testing with a physical device
  2. Testing on a simulated device

We recommend using physical devices when possible - these provide the best testing experience that will be as close to what your users will see. However, you likely don't have every possible variation of hardware and software available to test on, so you will need to turn to simulators and emulators to fully test your applications.

Just always keep in mind that simultors and emulators are not the real thing - they often will be faster than a physical device (because they are running on your computer's hardware), don't expose all the features available (Bluetooth, NFC, etc.), and sometimes even use different runtime environments. Just because it runs on a simulator/emulator doesn't mean your app runs correctly on a real device - always test on both.

Testing with an iOS Device

You can run your applications on a physical iOS device plugged into your Mac Host using a USB cable. You must first configure the device for development purposes. The easiest way to do this is to use XCode – we have a video tutorial on how to do this with your device.

Once it’s configured and plugged into the connected Mac Host, it will show up as a device available from Visual Studio.

Testing with the iOS Simulator

The iOS Simulator is included as part of XCode and will be automatically launched by Visual Studio when you select a simulated device from the Visual Studio toolbar. You can choose which simulator to launch (iPhone vs. iPad, and iPhone variations) through the iOS toolbar – it should list all the variations that are installed on your Mac build host. If you don’t see the toolbar, right click on the toolbar area and select iOS.

The simulator will be launched and will run on the Mac, not on your Windows computer. To actually view and interact with the simulator, you will need physical or remote access to the Mac. We recommend Chrome Remote, VNC or TeamCity for remote access.

Alternatively, you can remote the simulator to your Windows machine by installing a preview feature in Windows. This will allow you to interact with the simulator right from your Windows machine without remote access to the Mac. See this guide for instructions on setting this up.

Testing with an Android device

As mentioned above, it's recommended that you use a physical Android device for testing. This is often easier to setup, and gives a more realistic view of the end-user experience. The device must be plugged into your Mac through a USB cable and be setup for USB debugging. On Android KitKat (4.4) and above this requires a few steps.

Note that on some devices, the steps might vary slightly - if they don't match the instructions below, try searching for your specific vendor and turning on device debugging.

Note: Depending on your Android device, you may also need to install device specific Windows USB drivers to get it to connect properly to your computer. Check the manufacture's website for details. If the manufacturer does not have specific drivers, there is a generic USB driver available in the Android SDK tools as an optional install. Use the SDK manager to download it (instructions below) and then install it from the SDK folder.

Testing with Android emulators

You can also use an emulator to test Android applications. Android Emulators. We recommend the Visual Studio Emulator for Android.

Visual Studio uses Hyper-V to run all the Android and Windows Phone Emulators. These are optional components which must be selected as part of your Visual Studio install - if you don't see the emulator options in Visual Studio, then you can use the Add/Remove Programs dialog to change your installed options, or use the standalone installer for the Visual Studio Emulator for Android. The Windows Phone emulators can only be installed through the Visual Studio installer.

I don't want to use Hyper-V

If your machine does not support Hyper-V, or you have software which conflicts with Hyper-V and don't want to use these emulators, then you can use the Google Android emulators.

If you want to turn Hyper-V on and off, you can setup a boot configuration. This will allow you to disable the services so that other virtual machines such as VMWare or VirtualBox can be used on your computer.

Working with the Visual Studio Emulator for Android

Once the Visual Studio Emulator for Android is installed, you can open the configuration dialog from the Tools > Visual Studio Emulator for Android menu.

This dialog allows you to download different device images. You can also launch one of the installed emulator images using the Play button next to the item. We recommend you install an emulator for both a phone device such as the Galaxy S5 and a tablet device such as the Google Nexus 10.

Once the emulator is running, you can perform administrative tasks with the associated toolbar:

You can then select a specific emulator using the target dropdown in Visual Studio when running your application:

Update your Android SDKs

Before you start building Xamarin.Android applications, you should verify that you have all the Android SDK packages you will need in order to build and run Xamarin.Android apps.

Here is an example – note the things which are selected/installed:

Setup Windows Emulators

To run Windows Store apps, or use the Windows platform projects with Xamarin.Forms you can either use the Microsoft provided emulators or deploy to a physical device. If you plan to use an emulator, you must have a machine capable of Second-level Address translation (SLAT) and have Hyper-V enabled.

The Windows Phone 8.1 emulators can be installed using the Visual Studio installer: For Visual Studio 2015 you need to check Windows and Web Deployment > Windows 8.1 and Windows Phone 8.0/8.1 > Emulators for Windows Phone 8.1. These emulators require Windows 8 or higher.

The Windows 10 Mobile emulators can only be installed using Visual Studio 2015. Run the installer and check Universal Windows App Development Tools > Universal Windows App Development Tools > Emulators for Windows 10 Mobile. These emulators require Windows 10.

Verify your installation

To validate your Xamarin installation on Windows, we will use Xamarin Studio to create a new Xamarin.Forms application and then run all of the possible variations to test our installation.

Start by creating a new Xamarin.Forms project. Open Visual Studio and create a new Xamarin.Forms application using the New Project wizard (**File > New Project > Visual C# > Cross Platform > Blank App (Xamarin.Forms Portable**). You can use this to test your setup and ensure you can build and run the various mobile configurations properly.

If you are running on Windows 10 and have the UWP SDK installed, then you will get a prompt during the project creation to select the UWP version to target. You can generally just leave the defaults in place and click OK.

Once it's finished, VS will have created a set of platform, or head projects, and a single shared (PCL) project. To test each platform, you will need to change the active project in the solution to be the specific platform project you want to run. The projects created will depend on the version of Visual Studio, the SDKs installed and the version of Windows you are running on. Here, we are on Windows 10 with all the SDKs, so we get all platform variations:

The active project is shown in Bold. You can change it by right-clicking on the specific project you want to make active and selecting "*Set As Startup Project*."

Testing iOS

Note: you will need a Mac build host connected and available in order to run the iOS version of the application. If one is not available, the simulator/device options will not show up in the IDE.

Testing Xamarin.Android

Testing Windows

Note: Depending on your operating system (Windows 7, 8, or 10) and what SDKs you have installed, the templates generated will be slightly different. If you’ve got everything installed, you will have apps for Windows Phone 8.1, Windows 8.1, and Windows UWP.

If it fails to launch and indicates that it could not be deployed, then use the configurations drop-down to change the projects which are built/deployed for your solution.