Visual Studio for Mac Preview Release Notes

Visual Studio for Mac is a new member of the Visual Studio family focused on mobile and cloud development using Xamarin and .NET Core.


Visual Studio for Mac is an evolution of Xamarin Studio, and includes all the functionality of Xamarin Studio 6.2.

Many changes have been made to the look-and-feel, terminology and default settings to to align more closely with Visual Studio, while remaining a Mac-centred development experience.

Core Functionality

Visual Studio for Mac has everything you would expect from a modern IDE, including a full-featured source editor, code search and navigation, a powerful debugger, a customizable workspace, git integration, and a rich extension system.

Other features include:

  • Roslyn-based C# IntelliSense, refactoring, analyzers and code fixes
  • NuGet-based package management
  • Visual Studio compatible project format
  • MSBuild build engine
  • Integrated unit testing
  • Support for F# out-of-the-box

Xamarin Platform

First-class support for the Xamarin Platform allows you to develop rich native experiences for iOS, Android and Mac. The Xamarin.Forms cross-platform library helps you share XAML-based UI code between iOS, Android and UWP (though UWP is not supported on Mac) without limiting access to native functionality.

This includes:

  • Building, deployment, debugging and profiling
  • Drag-and-drop UI designers for iOS and Android
  • Live preview for Xamarin Forms
  • .NET Standard compatible framework
  • Bindings to native APIs

New Features

The following features are new in Visual Studio for Mac Preview:

.NET Core Support

.NET Core is a platform for creating applications that run on Windows, Linux and Mac. Visual Studio for Mac has support for loading, creating, running and debugging .NET Core projects.

In order to run .NET Core projects the .NET Core SDK should be downloaded and installed.

.NET Core support includes:

  • C# and F# IntelliSense.
  • .NET Core project templates for console, library and web applications.
  • Full debugging support, including breakpoints, call stack, watch window, etc.
  • NuGet PackageReferences and MSBuild-based restore.
  • Integrated unit testing support for running and debugging tests with the Visual Studio Test Platform that is included with the .NET Core SDK.
  • Migration from old project.json format.

Connected App Templates

The new Connected App project templates offer a quick way to create a multi-platform mobile app and its cloud backend.

These templates create multiple projects: a Xamarin.iOS app project and a Xamarin.Android app project that share code via a shared project, and a .NET Core Web API project that implements a back-end service for the apps.

Multi-Process Debugging

In Xamarin Studio, projects have Project Run Configurations which specify options and arguments for running your project. A dropdown in the toolbar lets you view and change the current active Run Configuration.

Visual Studio for Mac extends this by adding Solution Run Configurations which allow multiple projects to be launched at once. You can create solution run configurations in the Solution Options dialog.

Using solution run configurations, you can debug multiple projects at once. This is very useful for debugging how a mobile app interacts with its backend service.

TextMate Bundles

Visual Studio for Mac has support for TextMate language bundles, which you can use to add:

  • Editor color themes
  • Code snippets
  • Grammars for new languages, enabling highlighting and basic IntelliSense

You can add TextMate bundles in Preferences > Text Editor > Language Bundles.


Audio Unit Wizard

The new Audio Unit Extension wizard adds 3 options to customize the Audio Unit project template's plist.

  • Audio Unit Type
    • Instruments
    • Generator
    • Effect
    • Music effect
  • Subtype Code: has to be 4 characters exactly
  • Manufacturer Code: has to be 4 characters exactly

Audio Unit Wizard

Remove TLS Provider option

TLS Provider is not needed in the iOS build options anymore because:

  1. AppleTLS is the default since C7 and support up to TLS 1.2.
  2. MonoTLS is limited to SSLv3 and TLSv1: both are being deprecated.

Note: Xamarin.iOS 10.4 release notes already mention MonoTLS is deprecated and that it will be removed in the future.

Other improvements and bug fixes

  • We now show a progress bar when deploying to device. This is especially useful for watchOS. (Requires Xamarin.iOS
  • We now use known OS versions from Xamarin.iOS to populate the deployent target dropdowns.
    The two advantages are that we can give you the exact minimum version for each App Extensions type, as well as avoid showing OS versions, based on Xcode, that Xamarin.iOS does not yet support.


Please report any problems you encounter with the Visual Studio for Mac Preview using the Help > Report a Problem menu.

If there is any functionality that you would like to be changed or added to Visual Studio for Mac, please use the Visual Studio for Mac UserVoice to share your ideas and vote on suggestions made by other people. You can also access this from Help > Provide a Suggestion.

We can't respond to all feedback directly, but we do read it all and it very much helps us prioritize improvements to make Visual Studio for Mac work better for you.

System Requirements

Visual Studio for Mac Preview requires macOS 10.11 or later. For Xamarin development there are additional requirements listed here.

Side by Side Installation with Xamarin Studio

Visual Studio for Mac Preview can be installed side by side with Xamarin Studio.

However, Visual Studio for Mac requires Mono 4.8, and installing or updating the stable or beta version of Xamarin Studio will downgrade Mono to an older version.

You can work around this by switching Xamarin Studio to the alpha update channel, or by opting out of Mono 4.6 downgrades in the Xamarin Studio update dialog. If you need to reinstall Mono 4.8, you can get it here.

Known Issues

This is a preview release, and ships with several known issues and limitations that will be addressed in future updates.

  • Changes in files on disk are not picked up by wildcards until the project is reloaded.
  • There are very few ASP.NET Core specific file templates.
  • HTML IntelliSense does not support HTML5.
  • The first time you build an Android project that uses the Google Android Support Libraries, the build may appear to hang with no output while the download takes place.
  • The Connected App templates currently require the app to be manually configured with the address of the service on the host machine, except when using the iOS Simulator.
  • The debugger sometimes does not automatically exit the debug layout when the debug session ends.
  • The Xamarin.Forms XAML previewer can cause Visual Studio for Mac to become unresponsive.
  • The File Nesting extension version 0.1 causes NuGet package restore to fail with Visual Studio for Mac Preview. This extension should be disabled in the Extension Manager until a new version is published that is compatible.

Changes in Preview 5


  • Application icon updated

 .NET Core Support Improvements

  • Added support for setting PipeTransport settings when running .NET Core application
  • .NET Core debugger now supports running in external console
  • ASP.NET Core run configuration dialog simplified
  • Updated to NuGet
  • Updated to latest .NET Core SDK 1.0.1 project templates
  • Updated to latest stable Visual Studio Test client 15.0.0

Bug Fixes

  • Fixed dotted filenames not excluded correctly
  • Fixed F# tutorial project template
  • Fixed runtimes not restored for .NET Core projects
  • Fixed PackageTargetFallback being ignored for .NET Core projects
  • Fixed Android project showing errors in text editor for types
  • Fixed wrong .NET Core SDK download url shown in download dialog
  • Fixed no code completion in new C# file
  • Fixed F# interactive window not working
  • Fixed debug files being generated in the wrong location
  • Fixed global MSBuild properties not used for project build
  • Fixed MSBuild Remove item added when file was deleted
  • Fixed failure to building legacy MonoMac projects
  • Fixed hard coded wildcard globs for Sdk projects
  • Fixed error when installing extensions

Changes in Preview 4


  • This release includes all the new features and fixes included in Xamarin Studio 6.3 (release notes).
  • MSBuild is now the default build engine instead of xbuild.
  • Portable and embedded compiler options can now be specified in project options.
  • Various optimizations, memory usage and performance improvements across the IDE.

 .NET Core Support

  • Integrated unit testing support for running and debugging tests with the Visual Studio Test Platform that is included with the .NET Core SDK.
  • Integrated the .NET Core templating engine and project templates.
  • F# .NET Core projects are now supported.
  • Support for migrating projects project.json/xproj to csproj.
  • References and Packages folders have been removed from the Solution window. This information is shown in the Dependencies folder under the Assemblies, Projects, Packages and SDK folders.
  • Allow multiple NuGet packages to be select and removed in one step for .NET Core projects.
  • A message dialog is now displayed if .NET Core SDK is missing or unsupported with a download link.
  • Added ASP.NET Core run configuration settings in project options. App url, launch url and enabling/disabling launching the browser can now be configured.

Bug Fixes

  • Fixed license acceptance dialog not shown for .NET Core projects
  • Fixed crash at startup if the ~/Library/Preferences/Xamarin directory is owned by another user
  • Base class constructor tooltip does not contain all constructor definitions
  • Fixed Find References of All Overloads not returning all items
  • Fixed language selection for recent templates not showing correct lanuage used
  • Fixed quick task drawing glitch
  • Fixed incorrect working directory used when running .NET Core projects
  • Fixed Lamba argument renaming shows code completion items
  • Fixed disabled breakpoints being hit when debugging .NET Core project
  • Fixed restore errors after renaming project file
  • Fixed unevaluated MSBuild expression being shown in the project options as the compiler's Define Symbol for .NET Core projects.
  • Fixed potential race condition on saving an MSBuild project
  • Fixed Description not saved in .NET Core project file if modified
  • Fixed RootNamespace to be updated from project options for .NET Core projects
  • Refresh NuGet packages after target framework changed in project options
  • Fixed target framework changes made in project options not saved
  • MSBuild project option is no longer shown for .NET Core projects
  • Show correct target frameworks in project options for .NET Core projects
  • Remove extra metadata saved with ProjectReferences
  • Fixed app freezing whilst attempting to debug on iOS Simulator
  • Fixed intellisense fails when referencing an iOS binding project
  • Fixed scrolling to type when using Go To Definition with Assembly Browser
  • Fixed crash on adding breakpoint to any line of Main.axml file
  • Hide diagnostics when severity is hidden.
  • Fixed formatting on pasting large blocks of unformatted code
  • Fixed crash when using the Assembly Browser
  • Fixed library reference alias change not reflected in the type system
  • Tabs to Spaces defaults to true for F# projects
  • Fixed code completion on standalone files
  • Fixed open statements greyed out that contain operators
  • Fixed floating versions not handled in package references
  • Fixed document is not part of the workspace exception
  • Item groups now merged in F# projects for Visual Studio compatibility
  • Increase length of strings shown in Watch window
  • Fixed copying the contents of a debugger expression does not copy just the value
  • Fixed crash on opening .cs file in Hex Editor
  • Fixed build error after referencing another .NET Core project
  • Restore after modifying project references
  • Fixed Clean failures not reported on Rebuild
  • Fixed broken code completion after referencing a project
  • Fixed main toolbar switches back from Release to Debug on adding/removing a file
  • Fixed not being able to reference .NETStandard projects from .NET Core projects
  • Fixed hovering over constructor not showing resolved constructor overload
  • Fixed xmlns being added to .NET Core SDK projects
  • Fixed PackageReference elements added with a Version element instead of using an attribute

Changes in Preview 3


  • Recently used project templates are now displayed in the New Project dialog.
  • Open Url context menu is now available for hyperlinks in the text editor.

 .NET Core Support Improvements

  • Updated the .NET Core CLR debug adapter to version to 1.6.3
  • Project templates updated to use the new simplified MSBuild Sdk style projects.
  • Support simplified MSBuild .NET Core projects that use the Sdk attribute.
  • Simplified MSBuild .NET Core projects require the .NET Core SDK 1.0.0-rc4 to be installed and Mono or higher.
  • Show packages from .NET Core project file by default in the Dependencies folder whilst waiting for dependency information to be returned from MSBuild.
  • NuGet packages are now restored on saving the project file after it has been edited in the text editor.
  • NuGet is now used to restore .NET Core packages instead of running MSBuild restore.


Bug Fixes

  • Fixed text editor not highlighting code correctly for pre-processor directives.
  • Fixed C# brace matching.
  • Fixed code templates not working correctly from "Insert Template..." dialog.
  • Fixed enter in code generator not implicitly selecting current item.
  • Fixed format document changing position of caret.
  • Fixed C# code completion for Android shows XML.
  • Fixed Go To Matching brace not working for regions.
  • Fixed TextMate indentation engine not reading the on the fly formatting IDE setting.
  • Fixed text editor scrolling there are many IExtendingTextLineMarkers.
  • Fixed invalid search pattern error with certain wildcard items.
  • Fixed non-C# files not displayed in Solution window for .NET Core projects.
  • Fixed build error after renaming a .NET Core project.
  • Fixed breakpoint not hit in .cshtml files.

Changes in Preview 2

  • Solutions now load much faster.
  • Visual Studio for Mac now uses NuGet
  • The XAML previewer is more reliable.
  • NuGet package source information is now reloaded if the NuGet.Config file is modified in the text editor or externally.
  • The external console is now used for new .NET Core console applications by default. This can be changed in Project Options - Run - Configurations - Default.
  • Welcome Page
    • Recent project / solution list can be filtered and removed.
    • The page can be navigated using keyboard.
    • Fixed activation / deactivation issue when opening and closing a solution.

Bug Fixes

  • Fixed Report a Problem on macOS 10.11.
  • Fixed IntelliSense and syntax highlighting in XAML files.
  • Fixed application icon rendering issue.
  • Fixed NuGet package sources information not available when NuGet.Config read fail.
  • Fixed NuGet package sources with encrypted passwords not being supported.
  • Fixed install error when installing a NuGet package, such as Microsoft.AspNetCore.Mvc, which has package dependencies not in the local NuGet package cache into a .NET Core project.
  • Fixed NuGet package restore information not displayed for the Connected Service project templates.
  • Fixed potential user interface hang on opening a .NET Core project.
  • Fixed execution error when an environment variable is used in a run configuration.
  • Fixed potential crash when switching active run configuration.
  • Many other bug fixes!

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.