Welcome to Xamarin University! This guide is to help you get your macOS 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.
Apple generally requires that you run the latest released version of macOS. As of Fall 2017, you should plan to get a Mac that can run Sierra and is on the supported list for macOS High Sierra. The machine should have a 64-bit Intel processor, 50GBs of free disk space, and a minimum of 4G of RAM; the more RAM the better. Avoid computers made prior to 2010 as they will likely not be sufficient to run the tools on.
The Xamarin documentation portal has detailed setup and install instructions for Xamarin.
Verify that your Mac is running the latest released version of macOS. You can get this information from About This Mac in the system menu as shown above.
Make sure you have at least 40gb of free disk space. The IDE, simulator and emulator images and associated SDKs are all quite large.
Install the latest version of XCode from the Mac App Store.
Launch Xcode to accept the licensing agreements and download additional runtime files necessary for development.
Install Visual Studio for Mac from www.visualstudio.com/d. The installer will automatically include any tools and SDKs needed for Android development. This may take a while depending on what is already installed on the computer since it may have to download fairly large SDKs.
Launch Visual Studio for Mac It will be in your Applications folder; you can use Spotlight to locate and launch the application. We recommend keeping it in your Dock for quick access.
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 the Visual Studio for Mac > Check For Updates system menu option at any time.
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.
Just always keep in mind that simulators and emulators are not real devices, 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.
You can run your applications on a physical iOS device plugged into your Mac 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.
The iOS Simulator is included as part of XCode and will be automatically launched by Visual Studio for Mac when you select a simulated device from the Visual Studio for Mac toolbar. You can choose which simulator to launch (iPhone vs. iPad, and iPhone variations) through this toolbar along the top of your Visual Studio for Mac IDE window:
By default, only the latest simulator is installed by Xcode, however you can also install other versions by launching Xcode and using the Preferences > Components dialog.
This is particularly important as Apple releases new versions of iOS; the simulator is not updated automatically - so you will need to use this dialog to install newer versions of iOS devices on your Mac.
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.
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.
You can also use an emulator to test Android applications. We recommend the Android SDK emulators which are installed with Android Studio. These are hardware accelerated, kept up to date by Google and you can download images which have Google Play services pre-installed.
Download and run the Android Studio installer. It will install all the required Android development pieces as well as the emulators.
Once installed, run the application and click the Configure button at the bottom of the Welcome Screen. Select SDK Manager from the drop down.
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. 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).
Note that you do not need to install an SDK version to make your app compatible with that version - Android supplies backward-compatible libraries to ensure it runs on older versions as long as you are compiling against the latest.
It's recommended to have at least one modern (version 7 or higher) Android Virtual Device (AVD) defined. You will want to test on each Android version you can run on to ensure your app works properly on each target. The most common variation is a phone form-factor, but if you are building for tablets, you can choose a larger emulated device as well.
Unfortunately, the AVD dialog is only available in an active project, so to access the wizard, you will need to generate a new project with Android Studio.
Click OK to dismiss the SDK dialog if it’s still open and return to the Welcome Screen. If you rebooted your computer, then re-open Android Studio.
Create a new Android project by clicking the Start a New Android Project link on the Welcome Screen.
To validate your Xamarin installation on a Mac, we will use Visual Studio for Mac to create a new Xamarin.Forms application and then run it on both iOS and Android to check both environments.
Start by creating a new Xamarin.Forms project. Open Visual Studio for Mac and use the New Project wizard: File > New Solution > Multiplatform > App > Forms App (Note: the newest versions of Visual Studio for Mac use the term “Multiplatform” here while previous versions used “Cross-platform”). You will use this to test your setup and make sure you can build and run both iOS and Android applications.
Make sure the iOS platform project is the current startup project in the IDE – it should be in bold in the solution pad. You can right-click and choose Set As Startup Project to change it if necessary.
Select the Debug configuration and one of the iOS Simulator choices in the toolbar, for example the iPhone 6s iOS 9.3 choice:
Make sure the Android platform project is the active project in Visual Studio for Mac (you can right-click and choose Set As Startup Project to change it if necessary).
Select the Debug configuration and one of the choices in the emulator drop-down. If you don't see any choices, or you would like to configure the choices available, use the instructions described above.
Click the "Run" button in the toolbar (looks like a "Play" icon). It should build the application and then run it in the selected emulator.
You can uninstall Xamarin from your Mac using these instructions.
Most of the time, everything will install and run smoothly. However, if you have trouble with any of the steps, or you find that you cannot build or run the test application, check out our Troubleshooting Guide.