We’ve been delivering improvements to Visual Studio 2017 more frequently than ever before. Since its first release in March we’ve released four major updates to VS2017 and are currently previewing the fifth update, VS2017 version 15.5.

The MSVC toolset in VS2017 is built as a minor version update to the VS2015 compiler toolset. This minor version bump indicates that the VS2017 MSVC toolset is binary compatible with the VS2015 MSVC toolset, enabling an easier upgrade for VS2015 users. Even though the MSVC compiler toolset in VS2017 delivers many new features and conformance improvements it is a minor version, compatible update from 14.00 in VS2015 to 14.10 in VS2017.

We’ve made significant updates to the MSVC toolset twice so far in VS2017: once with the first release of VS2017 and again in update version 15.3. We’re making another significant update with VS2017 version 15.5. The MSVC toolsets in 15.1, 15.2, and 15.4 were incremental, bug fix-level updates. For reference, here are the MSVC toolset versions and compiler versions (_MSC_VER) in each release of VS2015 to VS2017. (Note that for historical reasons the MSVC compiler version is 5 higher than the MSVC toolset version displayed in Visual Studio.)

Minor version updates are designed to be source and binary compatible with previous versions. We test all source changes for compatibility and document all C++ conformance changes and any required source changes with every release. The source changes that we document are almost always forward and backward compatible, meaning that you can compile the code with either a new or old compiler.

Sometimes, despite best efforts, adding new functionality can introduce bugs that affect your code. If you do encounter bugs with your source base, or you need extra time to apply source fixes in your codebase, you may need a way to get back to the previous VS2017 update’s toolset while you update your code or we fix bugs. You can now install the previous minor version MSVC toolset (14.11) if you run into issues with the MSVC compiler with VS2017 version 15.5 preview 4 (14.12).

Who should use this feature?

This feature is intended as an “escape hatch” for developers who find that there is a bug, either in their source code or in MSVC, that cannot be easily worked around or fixed in a timely fashion. If there’s a conformance issue in your source code, the best option is to apply the proper fixes to make your code conforming if possible (sometimes there are too many required changes in your code to fix it all immediately.) If you believe that there’s a bug in MSVC, it’s best to talk with us so that we can fix the bug or supply a workaround.

This feature is useful in the unlikely event that we can’t deliver a bug fix quickly enough and you cannot apply a workaround in your source code. It’s not meant to be a general-purpose feature. If you run into an issue you should first contact us (see Contact us! below) so we can try to resolve your problem directly.

What alternatives do I have?

If you suspect that you will need to stay on a particular VS2017 update—say your product is ready to ship the day after VS2017 updates—you might consider preserving an offline installation of the VS2017 version that builds the current version of your product. Preserving an offline installation will allow you to install an older version of VS2017 after it’s been updated. You can find more information on this page, Creating an offline installation of Visual Studio 2017.

Older versions of Visual Studio and the MSVC toolset may not be supported

You should note that older versions of Visual Studio and the MSVC toolset follow the standard Visual Studio servicing guidelines. These guidelines specifically advise that only the RTW version and latest versions are supported. Please review the VS servicing guidelines for yourself before using either the side-by-side minor version MSVC toolsets or an offline installation of an older VS2017 version.

How to install side-by-side MSVC toolsets

If the MSVC team has advised a side-by-side toolset as your best option to work around a compiler bug or source issue, how do you install it? It’s actually an option in the VS2017 installer. Just select the “Individual Components” tab at the top of the installer screen and scroll down to the “Compilers, build tools, and runtimes” section.  The 14.11 toolset is included in the VS2017 version 15.5 update 4 installer.

Selecting the “VC++ 2017 version 15.4 v14.11 toolset” will also select the current MSVC toolset for VC++ 2017 version 15.5. Projects will by default use the current MSVC toolset–you’ll have to edit your project file (.vcxproj) to use the older toolset.

Using a side-by-side minor version MSVC toolset in VS

Side-by-side minor version MSVC toolsets don’t appear in the “Platform Toolset” options of the Project Configuration Properties. To enable them you need to edit the .vcxproj file for your project. Each side-by-side minor version MSVC toolset includes a .props file that can be included in your project’s .vcxproj file.

Before you start, you should add the -Bv compiler option as an Additional Option on the compiler command line. This will show the verbose compiler version information in the build Output box. Just enter “-Bv” in the Project Properties > C/C++ > Command Line edit box.

Now, open the VC\Auxiliary\Build\14.11 directory in the folder where you installed VS2017 version 15.5 Preview 4. For example, using the default install location you’ll find it here: C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise\VC\Auxiliary\Build\14.11. You should see three files in this folder. You’ll need to copy one of them, Microsoft.VCToolsVersion.14.11.props, into your solution directory.

Next, open the folder containing your solution by right-clicking on the solution and selecting “Open Folder in File Explorer”.

Copy the Microsoft.VCToolsVersion.14.11.props file from the VS2017 version 15.5 Preview 4 folder into your solution directory. The file should sit in the same directory as your project’s solution file, e.g., Project6.sln.

Now unload your project by right-clicking on the project and selecting “Unload Project”.

Once the project is unloaded, you can edit the project by clicking on it and selecting “Edit [ProjectName]”.

Locate the line that says

[xml] <Import Project=”$(VCTargetsPath)\Microsoft.Cpp.Default.props” /> [/xml]

Add a line directly above this line that imports the Microsoft.VCToolsVersion.14.11.props that you just copied into the solution directory:

[xml] <Import Project=”$(SolutionDir)\Microsoft.VCToolsVersion.14.11.props” /> <Import Project=”$(VCTargetsPath)\Microsoft.Cpp.Default.props” /> [/xml]

Now, save the file, then right-click on the project name and select “Reload Project”.

If you haven’t already saved the file, you’ll be prompted to close the open .vcxproj file. Select “Yes” to close the file.

Now when you rebuild the solution you’ll see that you’re using the 14.11 MSVC compiler toolset.

Using a side-by-side minor version MSVC toolset from the command line

If you need to use a side-by-side minor version MSVC toolset from the command line you just need to customize a developer command prompt. The command prompts installed with VS2017 version 15.5 Preview 4 are located in the VC\Auxiliary\Build subdirectory of your VS install dir. For example, with the default installation path, they are located in the C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise\VC\Auxiliary\Build directory.

In that folder you’ll find four developer command prompts (named vcvars*.bat). Pick any one and create a copy to edit. The contents of these files are pretty simple: they all just invoke vcvarsall.bat with the proper architecture parameter. We’ll do the same, but add a new parameter that tells vcvarsall.bat to set up the environment for the v14.11 toolset: -vcvars_ver=14.11.

Here’s an example of a command to set up the environment for the v14.11 x86-hosted, x64-targeting tools. Running the command cl -Bv shows that the environment is set up for the right version of the tools.

Contact us!

Usually at the end of our blog posts we encourage you to try out the feature we’ve discussed. In this case, we’re doing the opposite. If you think you’ve run into an issue with the MSVC toolset in VS2017 version 15.5 Preview 4 that can’t be worked around in sources, please contact us. We’d like to know about your issue and try to help you address it without having to fall back to an older MSVC toolset. But if you do need the option to install the older MSVC toolset side-by-side with the current toolset, it’s available to you.

As always, we can be reached via the comments below, via email (visualcpp@microsoft.com) and you can provide feedback via Help > Report A Problem in the product, or via Developer Community. You can also find us on Twitter (@VisualC) and Facebook (msftvisualcpp).