Project migration and upgrade reference for Visual Studio 2017

Each new version of Visual Studio generally supports most previous types of projects, files, and other assets. You can work with them as you always have, and provided that you don't depend on newer features, Visual Studio generally tries to preserve backwards compatibility with previous versions like Visual Studio 2015, Visual Studio 2013, and Visual Studio 2012. (See the Release Notes for which features are specific to which versions.)

Support for some project types also changes over time. A newer version of Visual Studio may no longer support certain projects at all, or requires updating a project such that it's no longer backwards compatible. For current status on migration issues, refer to the Visual Studio Developer Community site.

This present article provides details only for project types that Visual Studio 2017 can migrate. The article excludes project types that are no longer supported in Visual Studio 2017 and cannot therefore be migrated. The article also excludes supported project types that have no migration issues; that list is found on Platform Targeting and Compatibility.

Important

Certain project types require installing the appropriate workloads through the Visual Studio installer. If you don't have the workload installed, Visual Studio reports an unknown or incompatible project type. In that case, check your installation options and try again. Again, see the Platform Targeting and Compatibility article for details on project support in Visual Studio 2017.

Project types

The following list describes support in Visual Studio 2017 for projects that were created in earlier versions.

If you don't see a project or file type listed here that should be, consult the Visual Studio 2015 version of this article and use the "Give documentation feedback" option at the bottom of this page to provide details of your project. (If you'd like a response, use the documentation feedback rather than the anonymous "Is this page helpful?" control.)

Type of Project Support
.NET Core projects (xproj) Projects created with Visual Studio 2015 used preview tooling that included an xproj project file. When you open an xproj file with Visual Studio 2017, you are prompted to migrate the file to the csproj format (a backup of the xproj file is made). This csproj format for .NET Core projects is not supported in Visual Studio 2015 and earlier. The xproj format is not supported in Visual Studio 2017 other than for migration to csproj. For more information, see Migrating .NET Core projects to the csproj format.
ASP.NET Web Application and ASP.NET Core Web Application with Application Insights enabled For each Visual Studio user, resource information is stored in the registry per user instance. This information is used when a user doesn't have a project opened and wants to search Azure Application Insights data. Visual Studio 2015 uses different registry location than Visual Studio 2017 and does not conflict.

Once a user creates an ASP.NET Web Application or ASP.NET Core Web Application, the resource is stored in the .suo file. The user can open the project in Visual Studio 2015 or 2017 and the resource information is used for both as long as Visual Studio supports projects and solutions being used across both versions. Users need to authenticate once on each product. For example, if a project is created with Visual Studio 2015 and opened in Visual Studio 2017, the user needs to authenticate on Visual Studio 2017.
C#/Visual Basic Webform or Windows Form You can open the project in Visual Studio 2017 and Visual Studio 2015.
Database Unit Test Projects (csproj, .vbproj) Older Data Unit test projects are loaded in Visual Studio 2017 but use the GAC'd version of dependencies. To upgrade the unit test project to use the latest dependencies, right-click on the project in Solution Explorer and select Convert to SQL Server Unit Testing Project....
F# Visual Studio 2017 can open projects created in Visual Studio 2013 and 2015. To enable Visual Studio 2017 features in these projects, however, open the project properties and change target fsharp.core to F# 4.1. Note also that the F# language support option in the Visual Studio installer is not selected by default with .NET workloads; you must include it by selecting that option for the workload, or selecting it from the Individual components tab under Development activities.
InstallShield
MSI setup
Installer projects created in Visual Studio 2010 can be opened in later versions with the help of the Visual Studio Installer Projects extension. Also see the WiX Toolset Visual Studio 2017 Extension. InstallShield Limited Edition is no longer included with Visual Studio. Check with Flexera Software about availability for Visual Studio 2017.
LightSwitch LightSwitch is no longer supported in Visual Studio 2017. Projects created with Visual Studio 2012 and earlier opened in Visual Studio 2013 or Visual Studio 2015 are upgraded and can be opened only in Visual Studio 2013 or Visual Studio 2015 thereafter.
Microsoft Azure Tools for Visual Studio To open these types of projects, first install the Azure SDK for .NET, then open the project. If necessary, your project is updated.
Model-View-Controller framework (ASP.NET MVC) Support for MVC versions and Visual Studio:
  • Visual Studio 2010 SP1 supports MVC 2 and MVC 3; MVC 4 support is added through the ASP.NET 4 MVC 4 for Visual Studio 2010 SP1 download
  • Visual Studio 2012 supports only MVC 3 and MVC 4
  • Visual Studio 2013 supports only MVC 4 and MVC 5
  • Visual Studio 2017 and Visual Studio 2015 supports MVC 4 (you can open existing projects but not create new ones) and MVC 5

Upgrading MVC versions:
Modeling If you allow Visual Studio to update the project automatically, you can open it in Visual Studio 2015, Visual Studio 2013, or Visual Studio 2012.

The format of the modeling project has not changed between Visual Studio 2015 and Visual Studio 2017 and the project can be opened and modified in either version. However, there are differences in behavior in Visual Studio 2017:
  • Modeling projects are now referred to as "Dependency Validation" projects in the menus and templates.
  • UML diagrams are no longer supported in Visual Studio 2017. UML files are listed in the Solution Explorer as before but are opened as XML files. Use Visual Studio 2015 to view, create, or edit UML diagrams.
  • In Visual Studio 2017, validation of architectural dependencies is no longer performed when the modeling project is built. Instead, validation is carried out as each code project is built. This change does not affect the modeling project, but it does require changes to the code projects being validated. Visual Studio 2017 can automatically make the necessary changes to the code projects (more information).
MSI Setup (vdproj) See InstallShield Projects.
Office 2007 VSTO Requires a one-way upgrade for Visual Studio 2017.
Office 2010 VSTO If the project targets the .NET Framework 4, you can open it in Visual Studio 2010 SP1 and later. All other projects require a one-way upgrade.
Service Fabric (sfproj) Service Fabric Application projects can be opened in either Visual Studio 2015 or Visual Studio 2017, unless the Service Fabric Application project references an ASP.NET Core service project. Service Fabric projects from Visual Studio 2015 that are opened in Visual Studio 2017 are one-way migrated from the xproj format to csproj. See ".NET Core projects (xproj)" earlier in this table.
SharePoint 2010 When a SharePoint solution project is opened with Visual Studio 2017, it's upgraded to either SharePoint 2013 or SharePoint 2016. The ".NET Desktop Development" workload must be installed in Visual Studio 2017 for the upgrade.

For more information about how to upgrade SharePoint projects, see Upgrade to SharePoint 2013, Update Workflow in SharePoint Server 2013, and Create the SharePoint Server 2016 farm for a database attach upgrade.
SharePoint 2016 SharePoint Add-In projects created in Office Developer Tools Preview 2 cannot be opened in Visual Studio 2017. To work around this limitation, update the MinimumVisualStudioVersion to 12.0 and MinimumOfficeToolsVersion to 12.2 in the csproj vbproj file.
Silverlight Silverlight projects not supported in Visual Studio 2017. To maintain Silverlight applications, continue to use Visual Studio 2015.
SQL Server Reporting Services and SQL Server Analysis Services (SSRS, SSDT, SSAS, MSAS) Support for these project types is provided through two extensions in the Visual Studio Gallery: Microsoft Analysis Services Modeling Projects and Microsoft Reporting Services Projects. SSDT support is also included with the Data Storage and Processing workload in Visual Studio 2017.
SQL Server Integration Services (SSIS) Support for Visual Studio 2017 is available through the SQL Server Data Tools (SSDT). For more information, see the SQL Server Integration Services blog.
Visual C++ You can use Visual Studio 2017 to work in projects that were created in earlier versions of Visual Studio back to Visual Studio 2010. When you first open the project, you have the option to upgrade to the latest compiler and toolset or to continue using the original ones. If you choose to keep using the original ones, Visual Studio 2017 does not modify the project file, and uses the toolset from the earlier Visual Studio installation to build your project. Keeping the original options means you can still open the project in the original version of Visual Studio if necessary. For more information, see Use native multi-targeting in Visual Studio to build old projects.
Visual Studio Extensibility/VSIX Projects with MinimumVersion 14.0 or less are updated to declare MinimumVersion 15.0, which prevents the project from being opened in earlier versions of Visual Studio. To allow a project to open in earlier versions, set MinimumVersion to $(VisualStudioVersion). See also How to: Migrate Extensibility Projects to Visual Studio 2017.
Visual Studio Lab Management You can use Microsoft Test Manager or Visual Studio 2010 SP1 and later to open environments created in any of these versions. However, for Visual Studio 2010 SP1 the version of Microsoft Test Manager must match the version of Team Foundation Server before you can create environments.
Visual Studio Tools for Apache Cordova Projects can be opened in Visual Studio 2017, but are not backwards compatible. Upon opening a project from Visual Studio 2015, you're prompted to allow modifications to your project. This modification upgrades the project to use toolsets instead of a taco.json file to manage the versioning of the Cordova library, its platforms, its plugins, and its node/npm dependencies. See the migration guide for more information.
Web Deployment (wdproj) Support for Web Deployment projects was removed in Visual Studio 2012 with the addition of publish profile support. Because there is no equivalent in Visual Studio 2017, there is no automatic migration path for such projects. Instead, open the wdproj file in a text editor and copy-paste any customizations into to the pubxml (publish profile) file, as described on StackOverflow. Also see Plans regarding website and web deployment projects (MSDN blogs).
Windows Communication Foundation, Windows Workflow Foundation You can open this project in Visual Studio 2017, Visual Studio 2015, Visual Studio 2013, and Visual Studio 2012
Windows Presentation Foundation You can open this project in Visual Studio 2013, Visual Studio 2012, and Visual Studio 2010 SP1.
Windows Store/Phone apps Projects for Windows Store 8.1 and 8.0, and Windows Phone 8.1 and 8.0 are not supported in Visual Studio 2017. To maintain these apps, continue to use Visual Studio 2015. To maintain Windows Phone 7.x projects, use Visual Studio 2012.

How Visual Studio decides when to migrate a project

Each new version of Visual Studio generally seeks to maintain compatibility with previous versions, such that the same project can be opened, modified, and built across different versions. However, there are inevitable changes over time such that some project types may no longer be supported. (See Platform Targeting and Compatibility for which project types are supported in Visual Studio 2017.) In these cases, a newer version of Visual Studio won't load the project and doesn't offer a migration path; you need to maintain that project in a previous version of Visual Studio that does support it.

In other cases, the newer version of Visual Studio can open a project, but must update or migrate the project in such a way that might render it incompatible with previous versions. Visual Studio uses a number of criteria to determine whether such migration is necessary:

  • Compatibility with the target versions of platforms, back to Visual Studio 2013 RTM.‚Äč

  • Compatibility of design-time assets with previous versions of Visual Studio. (Namely different channels of Visual Studio 2017; Visual Studio 2015 RTM & Update 3; Visual Studio 2013 RTM & Update 5; Visual Studio 2012 Update 4; Visual Studio 2010 SP 1.) Visual Studio 2017 aims to fail gracefully with deprecated design-time assets without corrupting them, such that previous versions can still open the project.

  • Whether new design time assets would break compatibility with previous versions down to Visual Studio 2013 RTM & Update 5.

The engineering owner of the project type in question looks at these criteria and makes the call where support, compatibility, and migration are concerned. Again, Visual Studio tries to maintain transparent compatibility between Visual Studio versions if possible, meaning that one can create and modify projects in one version of Visual Studio and it just works in other versions.

If such compatibility is not possible, however, as with some of the project types described in this article, then Visual Studio opens the upgrade wizard to make the necessary one-way changes.

Such one-way changes may involve changing the ToolsVersion property in the project file, which denotes exactly which version of MSBuild can turn the project's source code into runnable and deployable artifacts that you ultimately want. That is, what renders a project incompatible with previous versions of Visual Studio is not the Visual Studio version, but the MSBuild version, as determined by ToolsVersion. So long as your version of Visual Studio contains the MSBuild toolchain that matches the ToolsVersion in a project, then Visual Studio can invoke that toolchain to build the project.

To maintain maximum compatibility with projects created in older versions, Visual Studio 2017 includes the necessary MSBuild toolchains to support ToolsVersion 15, 14, 12, and 4. Projects that use any of these ToolsVersion values should result in a successful build. (Subject, again, to whether Visual Studio 2017 supports the project type at all, as described on Platform Targeting and Compatibility.)

In this context, the question naturally arises whether you should try to manually update or migrate a project to a newer ToolsVersion value. Making such a change is unnecessary, and would likely generate many errors and warnings that you'd need to fix to get the project to build again. Furthermore, if Visual Studio drops support for a specific ToolsVersion in the future, then opening the project will trigger the project migration process specifically because the ToolsVersion value must be changed. In such a case, the subsystem for that specific project type knows exactly what needs to be changed, and can make those changes automatically as described earlier in this article.

Refer to the following articles for further discussion: