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.
Any development-class machine capable of running Windows 7 or later will work, however we recommend Windows 10. Make sure you have the latest graphics drivers installed as Visual Studio and the Android emulators utilize video hardware acceleration. In addition, the machine s processor should support VT-x for faster virtualization.
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.
Verify your PC is running Windows 10. Windows 7, 8 and 8.1 are also supported but not recommended. They receive less testing and aren't capable of locally running UWP applications.
Make sure you have at least 40-50G of free disk space – the IDE, Android emulator images and associated SDKs are all quite large.
Install Visual Studio 2017 from www.visualstudio.com/. Make sure you select the Mobile development with .NET workload. The installer will automatically download the tools and SDKs needed for iOS and Android development. If you're already installed Visual Studio 2017, run the installer and check the Mobile Developer with .NET workload.
Once the installation completes (and you’ve performed any request reboot), launch Visual Studio.
Xamarin updates are shipped with updates to Visual Studio 2017. It is highly recommended that you install updates to Visual Studio as they're released.
If you'd like to use pre-release Xamarin updates, you can install the Xamarin Updates Extension. More information is available here: developer.xamarin.com.
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 reach each other.
Warning: when using 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 possible, it is against Apple licensing. Additionally, the simulator and build tools are CPU intensive; having multiple instances running can cause signifigant performance issues and build/runtime failures.
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.
Make sure your Mac is running the latest version of macOS (e.g. El Capitan).
Log into the Mac using an account with administrator privileges.
Install the latest version of XCode from the Mac App Store. You will need an Apple account for this.
Install the Visual Studio for Mac from www.visualstudio.com/. This will install the Xamarin tools including the Build Host.
Open the Mac's Sharing preferences pane (**Apple > System Preferences > Sharing**) and make sure the Remote Login service is active. This is disabled by default, so you will likely need to turn it on.
Make sure the account you will be using is listed in the Allow access for: pane, or that the account is part of the administrators group (which is added by default).
Verify that ssh is now running by executing
ssh localhost from a Terminal command prompt on the Mac host.
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.
Open Visual Studio on your Windows machine.
Open Tools > Options > Xamarin > iOS Settings and click the Find Xamarin Mac Agent button.
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.
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:
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.
Remember that simulators and emulators are not real devices, they're often 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 use different runtime environments. Just because it runs on a simulator/emulator doesn't mean your app will run correctly on a real device; always test on both.
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 an available device in Visual Studio on Windows.
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.
If you have a Visual Studio Enterprise license, you can remote the simulator to your Windows machine using the Remoted iOS Simulator.. This will allow you to interact with the simulator from your Windows machine. See this guide for more information.
It is recommended to 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 in 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.
Go back to the Settings menu and now you'll be able to see a “Developer options” menu item.
Tap it and turn on USB Debugging from the menu on the next screen. When you connect it to the computer, it will prompt you to allow USB debugging – make sure to check the Always allow from this computer to avoid the prompt in the future.
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.
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 Xamarin.Android apps.
In Visual Studio, open Tools > Android > Android SDK Manager. The dialog will auto-select all updates; you can de-select Android emulator images – these are quite large and unnecessary if you are using a different emulator.
Make sure all the Android SDK Tools are installed for latest released Android Platform. Generally, you should always build your app with the latest SDK tools.
Make sure you have the SDK Platform installed for the most recent released version of Android. These are located under each platform version node. There are multiple versions of the SDK available - these are the libraries used by the build process to access the Java APIs in your Android applications. At a minimum, you should install the latest released version (not previews) but adding additional versions won't hurt anything (beyond using disk space).
At the very bottom in the Extras section, make sure to select the Android Support Library and Android Support Repository options.
As noted above, if you plan to use a physical device, under extras there is a USB driver for Windows – this lets you connect to an Android device. Use this if your device manufacturer does not include a USB driver.
Here is an example – note the things which are selected/installed:
To validate your Xamarin installation on Windows, we will use Visual 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*."
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.
Make sure the iOS platform project is the current startup project in the IDE.
Select the Debug configuration, iOS Simulator, and one of the simulator choices in the toolbar by clicking the arrow next to the Play button, for example the iPhone 6s:
Click the "Run" button in the toolbar (looks like a "Play" icon).
It should build the application and then run it in the simulator and display some text. If you have the simulator remoting option installed and turned on, you will actually get the simulator window on your Windows machine - otherwise, it will run on the Mac host.
Make sure the Android platform project is the active project in the IDE.
Connect your deveice or launch your Android emulator.
Select the Debug configuration and your device in the device drop-down (next to the Play button).
Make sure the Windows UWP platform projects is the active project in the IDE.
Select a Debug configuration, a CPU configuration and a device or Local Machine. Remember that emulators will require x86 and devices will require ARM builds.
Click the "Run" button in the toolbar to build and launch the application.
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.