Jaa

Create, maintain, and deploy a network installation of Visual Studio

  • Artikkeli

Applies to: yesVisual Studio noVisual 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

Sometimes an enterprise administrator wants to create a network install point that contains Visual Studio files that can be deployed to client workstations. This is to facilitate scenarios where the client machines may have limited permissions or limited access to the internet, or when an organization wants to standardize on a particular version of the developer toolset. We've designed Visual Studio so that an administrator can create and maintain a network layout (file cache), that can be stored on an internal network share. The network layout includes all the Visual Studio files necessary for both initial installation and subsequent product updates.

There is a lot of information on this webpage, and it's grouped up into the following sections:

  • Before you get started: highlights tips and other important considerations you should think about when you plan.
  • Acquire the correct bootstrapper: guidance on where to find and how to distinguish the various bootstrappers that are available for you to use.
  • Create the network layout: describes how to create the layout with the correct product content, channel settings, and version of the installer and how to copy it to a network share.
  • Update, modify, and maintain the network layout: information on how to best maintain your layout, including how to update the layout's product version, product content, channel settings, installer version, and folder size.
  • Install the layout onto client machines: describes how to configure client default settings such as what workloads and components to install by default and where the client should look for updates from. Also includes how to do the initial installation of the Visual Studio layout onto the client machines. Guidance and information regarding updating client machines that were originally installed from a layout is covered in the separate update a network based installation of Visual Studio page.
  • Help and Support: where to ask for help

Before you get started

There are a few important things to plan out and be aware of before you get started.

  • Folder Management: If you have multiple editions of Visual Studio in use within your enterprise (for example, Visual Studio 2017 Professional and Visual Studio 2017 Enterprise), you must create a separate network install point for each edition. Furthermore, the original Visual Studio installation layout and all subsequent product updates must be located in the same network directory to ensure that the client's repair and uninstall functionality works properly. Lastly, the layout path must be fewer than 80 characters, although some organizations have successfully used symbolic links to work around the 80-character limitation.
  • Planning for Updates: You must decide how your client machines should receive product updates before you do the initial client install. This is necessary to ensure that your clients' update location configuration is set correctly. Your choices include having the clients get updates from either the network layout location or from Microsoft hosted servers on the internet. Once the client has installed from the layout, the client's update location configuration is locked and unchangable.

Download the Visual Studio bootstrapper to create the network layout

Download the bootstrapper for the edition of Visual Studio you want and copy it into the directory that you want to serve as the source location of the layout. Once the layout is created, you can use it to install Visual Studio onto any client machine. The bootstrapper is the executable that you use to create, update, and perform other layout operations. You must have an internet connection to complete this step.

To get the latest bootstrappers for Visual Studio 2017 version 15.9, download one of the files below. The bootstrappers listed below will always install the latest most secure version of Visual Studio 2017, no matter when you run them:

Edition Bootstrapper
Visual Studio 2017 Enterprise version 15.9 vs_enterprise.exe
Visual Studio 2017 Professional version 15.9 vs_professional.exe
Visual Studio 2017 Build Tools version 15.9 vs_buildtools.exe

Other supported bootstrappers include vs_feedbackclient.exe, vs_teamexplorer.exe, vs_testagent.exe, vs_testcontroller.exe, and vs_testprofessional.exe.

Tip

If you previously downloaded a bootstrapper file and want to verify what version it is, here's how. In Windows, open File Explorer, right-click the bootstrapper file, choose Properties, choose the Details tab, and then view the Product version number. To match that number to a release of Visual Studio, see Visual Studio build numbers and release dates.

Create the network layout

You must have an internet connection to complete this step.

Open a command prompt with administrator privileges, navigate to the directory that you downloaded the bootstrapper into, and use the bootstrapper's parameters as defined in the use command-line parameters to install Visual Studio page to create and maintain your network layout. Common examples of creating initial layouts are illustrated below and in the command-line parameter examples for Visual Studio installation page.

A complete initial layout for a single language locale requires about 35 GB of disk space for Visual Studio Community and 45 GB for Visual Studio Enterprise. Additional language locales require about half a GB each.

The recommended approach is to create an initial layout of Visual Studio Enterprise with all languages and all workloads in the layout directory on the network server. That way, your clients will have access to the entire product offering. To create a full complete layout of Visual Studio, run the following from the machine that you plan to host the network layout on:

vs_enterprise.exe --layout c:\VSLayout

Configure the contents of a network layout

There are several options you can use to customize the contents of your network layout. You can create a partial layout that only contains a specific set of language locales, workloads, components, and their recommended or optional dependencies. This might be useful if you know that you're going to deploy only a subset of workloads to client workstations. Typical command-line parameters for customizing the layout include:

  • --add to specify workload or component IDs.
    If --add is used, only those workloads and components specified with --add are downloaded. If --add isn't used, all workload and components are downloaded.
  • --includeRecommended to include all the recommended components for the specified workload IDs.
  • --includeOptional to include all the optional components for the specified workload IDs.
  • --lang to specify language locales.

Here are a few examples of how to create a custom partial layout.

  • To create a layout with all workloads and components for only one language, run:

    vs_enterprise.exe --layout C:\VSLayout --lang en-US

  • To create a layout with all workloads and components for multiple languages, run:

    vs_enterprise.exe --layout C:\VSLayout --lang en-US de-DE ja-JP

  • To create a layout with one workload and all recommended components for that workload, for all languages, run:

    vs_enterprise.exe --layout C:\VSLayout --add Microsoft.VisualStudio.Workload.Azure --includeRecommended

  • To create a layout with two workloads and one optional component for three languages, run:

    vs_enterprise.exe --layout C:\VSLayout --add Microsoft.VisualStudio.Workload.Azure --add Microsoft.VisualStudio.Workload.ManagedDesktop --add Microsoft.VisualStudio.Component.Git --lang en-US de-DE ja-JP

  • To create a layout with two workloads and all of their recommended and optional components, run:

    vs_enterprise.exe --layout C:\VSLayout --add Microsoft.VisualStudio.Workload.Azure --add Microsoft.VisualStudio.Workload.ManagedDesktop --includeRecommended --includeOptional

Copy the layout to a network share

You will need to host the layout on a network share so it can be run from the client machines. If you created the layout on a local machine, then you will need to copy it to a network location. The following example uses xcopy. You can also use robocopy, should you wish. Example:

xcopy /e c:\VSLayout \\server\share\layoutdirectory

Important

To prevent an error, make sure that your full layout path on the network share is fewer than 80 characters. Or, some organizations have successfully used symbolic links to work around the 80-character limitation.

Update or modify your layout

It is possible to update a network layout of Visual Studio with the latest product updates so that it can be used both as an installation point and an update source for client workstations to receive the latest version of Visual Studio. It is a best practice to periodically update your layout, particularly if you intend for your clients to receive updates from the layout. This section describes the most common or useful layout maintenance operations.

If you host a layout on a file share, you may want to update a private copy of the layout (for example, c:\VSLayout) and then, after all of the updated content is downloaded, copy it to your file share (for example, \\server\products\VS). If you don't do this, there is a greater chance that any users who happen to run Setup while you are updating the layout might get a mismatch of content from the layout because it was not yet completely updated.

Update the layout to the most current version of the product

Microsoft frequently releases updated versions of the product to fix functionality or security issues. We recommend that you keep your layout updated with the latest version of the product, so that new client installs always receive the latest goodness. It's also very important to keep your layout updated if your clients are configured to receive updates from the layout.

When you create the initial layout, the specified options, such as which workloads and languages to include in the layout, are saved in the layout's configuration file. Later, when you want to update that layout to a newer version of the product, you don't have to re-specify the options that you used during initial layout creation. The layout update commands automatically use the saved layout settings.

Suppose you already created this partial layout using one of the evergreen bootstrappers in the table above.

vs_enterprise.exe --layout c:\VSLayout --add Microsoft.VisualStudio.Workload.ManagedDesktop --lang en-US

Updating this layout to the latest version of the product offered by Microsoft and hosted on Microsoft servers is easy. You just need to use the same evergreen bootstrapper, and run the --layout command again to download the latest packages into your layout.

vs_enterprise.exe --layout c:\VSLayout

You can also update your layout to a newer version in an unattended manner. The layout operation runs the setup process in a new console window. The window is left open so users can see the final result and a summary of any errors that might have occurred. If you are performing a layout operation in an unattended manner (for example, you have a script that is regularly run to update your layout to the latest version), then use the --passive parameter and the process will automatically close the window.

vs_enterprise.exe --layout c:\VSLayout --passive

Update the layout to a specific version of the product

Sometimes you may want to update your layout to a particular version of the product. For example, you may want to make your layout match the latest secure version of the servicing baseline that you have standardized your organization on. Here's how to do this:

You can use an administrator update to update your layout to a specific version. To get the Administrator Update, go to the Microsoft Update Catalog, search for the update you want to update your layout to. Download the update.exe to the computer that's hosting the layout, open up a command prompt on that computer and run a command like this:

visualstudioupdate-17.0.0to17.0.1.exe layout --layoutPath c:\VSLayout

Note that administrator updates will not initiate an original layout install; they will only update an existing layout or a client instance.

Modify the contents of the layout

It is possible to modify this layout and add or remove additional workloads or components or languages. In the example below, we'll add the Azure workload and a localized language to the layout we created above. After we've made the modification, both the Managed Desktop and Azure workloads, and the English and German resources are included in this layout. Also, the layout is updated to the latest available version.

vs_enterprise.exe --layout c:\VSLayout --add Microsoft.VisualStudio.Workload.Azure --lang de-DE

If you want to modify an existing partial layout so that it becomes a full layout, use the --all option, as shown in the following example.

vs_enterprise.exe --layout c:\VSLayout --all

Here's how to add an additional workload and localized language without updating the version. (This command adds the ASP.NET and Web Development workload.) Now the Managed Desktop, Azure, and ASP.NET & Web Development workloads are included in this layout. The language resources for English, German, and French are also included for all these workloads. However, the layout is not updated to the latest available version when this command is run. It remains at the existing version.

vs_enterprise.exe --layout c:\VSLayout --add Microsoft.VisualStudio.Workload.NetWeb --lang fr-FR --keepLayoutVersion

Important

An update operation doesn't download or install additional optional components either to the layout or onto the client. If you need to add or change optional components, first remove the old optional components from the layout.json configuration file and include the new components you need in the "add" section of layout.json. Then, when you run the --layout command to update the layout, it will download the newly added components into the layout.

To get these new components installed on the client machine, make sure you do these three steps. First, verify that the layout contains the new components as described above. Next, update your client to the latest bits in the layout. Finally, again on the client, run a modify operation which will install the new components (that were added to the layout) onto the client machine.

Verify a layout

Use --verify to perform verification on the network layout which checks if the packages files are either missing or invalid. At the end of the verification, it prints the list of missing and invalid files.

Verification works only for the latest version of a specific minor version of Visual Studio. As soon as a new version is released, verification won't work for layouts that contain previous releases.

vs_enterprise.exe --layout <layoutDir> --verify

Note

Some important metadata files that are needed by the --verify option must be in the layout folder. If these metadata files are missing, "--verify" cannot run and Setup gives you an error. If you experience this error, try to update the layout again, or re-create a new network layout in a different folder.

Remember that Microsoft ships updates to Visual Studio periodically, so a more recent layout might not contain the same version as the initial layout, unless you use the [fixed link bootstrappers](#download-the-visual-studio-bootstrapper-to create-the-network-layout).

Fix a layout

Use --fix to perform the same verification as --verify and also try to fix the identified issues. The --fix process needs an internet connection, so make sure your machine is connected to the internet before you invoke --fix.

vs_enterprise.exe --layout <layoutDir> --fix

Remove older versions from a layout

After you perform layout updates to a network cache, the layout folder may have some obsolete packages that are no longer needed by the latest Visual Studio installation. You can use the --clean option to remove obsolete packages from the network layout folder.

To do this, you'll need the file path(s) to catalog manifest(s) that contain those obsolete packages. You can find the catalog manifests in an "Archive" folder in the network layout cache. They are saved there when you update a layout. In the "Archive" folder, there is one or more "GUID" named folders, each of which contains an obsolete catalog manifest. The number of "GUID" folders should be the same as the number of updates made to your layouts.

A few files are saved inside each "GUID" folder. The two files of most interest are a "catalog.json" file and a "version.txt" file. The "catalog.json" file is the obsolete catalog manifest you'll need to pass to the --clean option. The other version.txt file contains the version of this obsolete catalog manifest. Based on the version number, you can decide whether you want to remove obsolete packages from this catalog manifest. You can do the same as you go through the other "GUID" folders. After you make the decision on the catalog(s) you want to clean, run the --clean command by supplying the files paths to these catalogs.

Here is an example of how to use the --clean option:

c:\VSLayout\vs_enterprise.exe --layout c:\VSLayout --clean c:\VSLayout\Archive\1cd70189-fc55-4583-8ad8-a2711e928325\Catalog.json --clean c:\VSLayout\Archive\d420889f-6aad-4ba4-99e4-ed7833795a10\Catalog.json

When you execute this command, Setup analyzes your network layout folder to find the list of files that it will remove. You will then have a chance to review the files that are going to be deleted and confirm the deletions.

Install Visual Studio onto a client machine from a network installation

Administrators can deploy Visual Studio onto client workstations as part of an installation script. Or, users who have administrator rights can run setup directly from the share to install Visual Studio on their machine.

  • Users can manually install the product from a network layout by running the following command:

    \\server\products\VS\vs_enterprise.exe

  • Administrators can install in an unattended mode by running the following command:

    \\server\products\VS\vs_enterprise.exe --quiet --wait --norestart

Note

Be patient. Make sure you --wait for both the installer and the product to finish. When installing or updating a client from a layout, the installer is always the first thing to get installed or updated, and then the Visual Studio product itself will get installed or updated. Both of these processes need to finish in order to be considered a successful update.

When executing the install or update as part of an unattended automated batch file, the --wait option is helpful to ensure that the vs_enterprise.exe process waits until the installation is complete before it returns an exit code. This is useful if an enterprise administrator wants to perform further actions on a completed installation, such as apply a product key to a successful installation. Using the --wait option prevents subsequent operations from kicking off prematurely. If you do not use --wait, the vs_enterprise.exe process can exit before both parts of the installation are complete, and thus will return an inaccurate exit code that doesn't represent the state of the install operation.

Install on a client that doesn't have internet access

When you install from a layout, the content that is installed will default to be acquired from the layout. However, if you select a component that isn't in the layout, and the client has been configured to look at Microsoft hosted servers for updates, then the installer will attempt to acquire Visual Studio packages from the internet too. If you want to prevent Visual Studio setup attempting to download any content from the web that is missing in your layout, use the --noWeb option. If --noWeb is used and the layout is missing any content that is selected to be installed, then the setup will fail.

Important

The --noWeb option does not stop the Visual Studio installer on an internet-connected client machine from checking for updates if the client has been configured to look at Microsoft hosted servers for updates. Rather, --noWeb simply prevents the client from downloading the product packages. For more information, see the Update a Visual Studio client that was installed from a network layout page.

Configure initial client installation defaults for this layout

You can modify some files in the layout folder to set default values that are used when the product is initially installed on the client machine. Common configuration options include:

  • Ability to configure which workloads, components, or languages should be selected by default during initial install.
  • Ability to specify where the client should receive updates from. Options are from the admin-controlled network layout location or from Microsoft hosted servers on the internet (which is the default).

For more information about how to customize and configure the default client settings for the layout, see Automate Visual Studio installation with a response file.

Configure enterprise deployment behavior

You can also control other enterprise deployment behavior, such as where shared packages are installed. Refer to Set defaults for enterprise deployments of Visual Studio for additional details.

Error codes

If you used the --wait parameter, then depending on the result of the operation, the %ERRORLEVEL% environment variable is set to one of the following values:

Value Result
0 Operation completed successfully
740 Elevation required
1001 Visual Studio installer process is running
1003 Visual Studio is in use
1602 Operation was canceled
1618 Another installation running
1641 Operation completed successfully, and reboot was initiated
3010 Operation completed successfully, but install requires reboot before it can be used
5003 Bootstrapper failed to download installer
5004 Operation was canceled
5005 Bootstrapper command-line parse error
5007 Operation was blocked - the computer does not meet the requirements
8001 Arm machine check failure
8002 Background download precheck failure
8003 Out of support selectable failure
8004 Target directory failure
8005 Verifying source payloads failure
8006 Visual Studio processes running
-1073720687 Connectivity failure
-1073741510 Microsoft Visual Studio Installer was terminated (by the user or external process)
Other
(for example:
-1, 1, 1603)		 Failure condition occurred - check the logs for more information

Get support for your network layout

If you experience a problem with your network layout, we want to know about it. The best way to tell us is by using the Report a Problem tool that appears both in the Visual Studio Installer and in the Visual Studio IDE. If you're an IT Administrator and don't have Visual Studio installed, you can submit IT Admin feedback here. When you use this tool, it would be very helpful if you could send the logs from the VS Collect tool which can help us diagnose and fix the problem.

We also offer an installation chat (English only) support option for installation-related issues.

We have other support options available, too. See our Visual Studio Developer Community.

See also