Project migration and upgrade reference for Visual Studio
Applies to: 
Visual Studio 
Visual Studio for Mac
Note
This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
Each 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 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.
Tip
If you're looking for information specific to our newest release, see the Visual Studio 2022 version of this page.
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 Send feedback about > This page button at the bottom of this page to provide details of your project. (If you use the anonymous "Is this page helpful?" control, we aren't able to respond to your feedback.)
| Type of Project | Support |
|---|---|
| .NET Core projects (xproj) | Projects created with Visual Studio 2015 used preview tooling that included an xproj project file. In Visual Studio 2017, the xproj format is not supported other than for migration to csproj format. When you open an xproj file, you're prompted to migrate the file to the SDK-style csproj format. (A backup of the xproj file is made.) SDK-style csproj projects are not supported in Visual Studio 2015 and earlier. 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:
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:
|
| 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 and Update SharePoint. |
| 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. For more information, see the Download and install SQL Server Data Tools (SSDT) for Visual Studio page. |
| SQL Server Integration Services (SSIS) | Support for Visual Studio 2017 is available through the SQL Server Data Tools (SSDT). For more information, see the Download and install SQL Server Data Tools (SSDT) for Visual Studio page, and the SQL Server Integration Services (SSIS) team 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. |
| 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 2017, 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.
Next steps
Refer to the following articles for further discussion: