Applying administrator updates that use Microsoft Endpoint Configuration Manager

  • Article

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

This document describes different types and characteristics of Visual Studio administrator updates. Below, you will find information about how and when they should be distributed throughout your organization, what configuration options are available, and how to view reports and troubleshoot. For more information about the pre-requisites for using administrator updates, see Enabling administrator updates. Administrator updates presumes that Visual Studio is already installed on the computer. Applying administrator updates will not initiate a brand new installation.

Understanding Visual Studio administrator updates

The Visual Studio administrator update package that is published to the Microsoft Update Catalog, WSUS, and the SCCM Configuration Manager contains information that the Visual Studio client machines need to be able to download and update Visual Studio. The Visual Studio administrator update packages don’t contain enough information to perform a new installation of the product, nor do they contain any of the actual product binaries that are published to the Content Delivery Network. The Visual Studio administrator updates are cumulative, just like regular Visual Studio updates. You can assume that any Visual Studio update that has a higher product version number and a later release date is a superset of an older, lower version.

The Visual Studio administrator update packages are titled in a way to help an IT administrator decide which updates should be distributed throughout their organization. An IT administrator can configure the administrator update in a way to control certain aspects of the update behavior, and they can download the Visual Studio administrator update package from the Microsoft Catalog and use it to update a network layout.

Visual Studio administrator updates that are deployed through SCCM cause the client machines to download the product files from wherever the client is configured to download updates from and apply the update. The updated product bits can be sourced from either the internet or, in scenarios where the client is not connected to the internet, the updated product bits can come from an updated network layout.

Note

By default, the client machine's SYSTEM account will be downloading and installing the Visual Studio administrator updates, which means that the SYSTEM account must have administrative privileges to the machine, and it must also have access to either the internet or to the network layout location in order to download the updated product bits. Furthermore, Visual Studio must be closed in order for the update to be successfully applied.

Visual Studio administrator updates apply to Visual Studio servicing versions that are under support. For more information about which Visual Studio servicing baselines are still in support during a particular timeframe, see Visual Studio Product Lifecycle and Servicing. All supported Visual Studio servicing baselines will be kept secure.

Types and characteristics of administrator updates

There are three types of administrator updates to Visual Studio 2017:

  • Security updates are applicable to all Visual Studio editions (Enterprise, Professional, Community, and so on), and they contain limited, highly targeted and compatible servicing level changes. While the product is in its mainstream support period, security updates will not advance a client to a later minor version; they are designed to deliver fixes to security vulnerabilities to a client that is already at a particular minor version level. However, once the product enters the extended support period, which for Visual Studio 2017 happened in April 2022, security updates will apply to all minor versions and will update the client to the latest secure version of the product. Security updates will have at least one security fix in them, but the security fix may or may not be in a component or workload that’s installed on the client machine. For example, we could fix a security vulnerability in the .NET components, and we would label the update as a security update, but it wouldn’t really have any meaningful effect on a client machine that had only C++ components installed. Security updates may also contain other reliability fixes or other necessary component updates. Security updates are published to both the Microsoft Update Catalog (MUC) and Windows Server Update Services, where they are classified as "Security Updates".
  • Feature updates enable IT admins to advance computers in their organization to a more recent minor version of Visual Studio. Feature updates only apply to Visual Studio editions that are commonly found in enterprises, such as Enterprise, Professional, and Build Tools SKUs. All feature updates will be published to the Microsoft Update Catalog as “Feature Packs,” and they are available to optionally manually import into Configuration Manager from the Microsoft Update Catalog. Feature updates are cumulative and will contain additional quality and prior security fixes. See the configuration options section below for instructions about how to configure a client machine to remain on a servicing baseline and prevent feature updates from being delivered to specific clients.
  • Quality updates are also only applicable to those Visual Studio editions that are commonly found in enterprises, and they contain limited, highly targeted and compatible servicing level changes. Quality updates will not advance a client to a later minor version; they are designed to deliver performance and reliability fixes or other necessary component updates to a client that is already at a particular minor version level. Quality updates accumulate along with security updates, and thus will contain security fixes only if the security fix has already been independently released. Quality updates are published to the Microsoft Update Catalog as “Updates”, and they are also available to optionally manually import into Configuration Manager.

Decoding the titles of administrator updates

The title of each administrator update describes both the applicable version range and the resultant version of the update. For example,

  • Visual Studio 2017 version 15.9.48 update classified as a “Security Update” will apply to any Visual Studio 2017 edition on the client between versions 15.0.0 and 15.9.47, and it will update those client editions to 15.9.48.
  • Visual Studio 2017 version 15.9.0 to 15.9.37 update classified as simply “Updates” will apply to Visual Studio 2017 editions licensed for enterprise use on the client between versions 15.9.0 through 15.9.37, and it will update those client editions to 15.9.37.
  • Visual Studio 2017 version 15.9.0 to 15.9.35 update classified as a “Security Update” will apply to any Visual Studio 2017 edition on the client between versions 15.9.0 through 15.9.35, and it will update those client editions to 15.9.35.
  • Visual Studio 2017 version 15.0.0 to 15.9.0 update classified as a “Feature Pack” will apply to Visual Studio 2017 editions licensed for enterprise use on the client between the entire product version range of 15.0.0 through 15.9.0, and it will update those client editions to 15.9.0. Applying this feature pack basically enables the clients to then receive security updates.

Using Configuration Manager to deploy Visual Studio updates

Understanding configuration options

There are a few configuration options that are can be used to tailor the Visual Studio administrator updates so that they’re compatible and aligned with your organization’s deployment preferences and requirements. The most common configuration options are listed below. For an exhaustive list of all the supported administrator update behaviors, see Use command-line parameters to install Visual Studio and pay attention only to those that correspond to the "update" action.

  • Administrator update opt-in: This registry key is required for the client machine to receive administrator updates. It is a machine-wide key, which means it applies to all instances of Visual Studio installed on the box.
  • Visual Studio user opt-out: Visual Studio users can use a separate machine-wide AdministratorUpdatesOptOut registry key to opt out of receiving Visual Studio administrator updates. The purpose of this key is to allow the Visual Studio user to have some control over having updates automatically applied to the machine. To configure the client computer to block administrator updates, set the AdministratorUpdatesOptOut REG_DWORD key to 1. The absence of the key, or a set value of 0, means that the Visual Studio user wants to receive administrator updates to Visual Studio. Note that the AdministratorUpdatesOptOut key for encoding user preference is prioritized over the AdministratorUpdatesEnabled key, which encodes the IT admin intent. If AdministratorUpdatesOptOut is set to 1, the update will be blocked on the client, even if the AdministratorUpdatesEnabled key is also set to 1. This action assumes that IT admins can access and monitor which developers chose to opt out, and that the two parties can then discuss whose needs are more important. IT admins can always change either key whenever they want.
  • Location of the updated product bits: When executing the update, the client machines will download the updated product bits from either the internet via the Microsoft CDN or from from a network layout share. In both of these cases, the account on the client machine that is executing the update (typically SYSTEM, but can be customized to USER) must have both administrative privileges on the machine as well as access to the source location of product bits.
    • If the product is being sourced from the internet, then the SYSTEM account executing the update must have access to at least the Visual Studio endpoints.
    • If the product is being sourced from a network layout location then the following conditions must be true before the administrator update can be successfully deployed:
      • The account executing the update must have permissions to the network share. For example, if SYSTEM accounts are executing the administrator updates, then you'll need to give the "Domain Computers" group permissions to the network layout share.
      • The client machine must have, at some point, already run the bootstrapper from that network layout location. Ideally, the original client install would have happened using the bootstrapper from the network layout, but it's also possible to have just installed an update using an updated bootstrapper in that same network location. Either one of these actions would embed, on the client machine, a connection with that particular layout location.
      • The network layout location (where the client is connected to) must be updated to contain the updated product bits that the administrator update wants to deploy.
  • Force the update to occur even if Visual Studio is in use: Visual Studio must be closed before you install the update. If Visual Studio is open or being used, the update installation will be aborted. An easy way to ensure that Visual Studio is closed is to configure Confirmation Manager to apply the update right after a machine reboot. You can also use the --force parameter to force shut down Visual Studio. Forcing Visual Studio to close might cause loss of work, so use it with caution. Running an administrator update in the default system context will ignore the –-force flag, so you will need to configure the administrator Update to be run in user context.

Methods for configuring an administrator update

There are three main methods of configuring administrator updates: a registry key, a configuration file on the client machine, or a modification of the Configuration Manager deployment package itself.

  • Registry key: Administrator updates look for specific registry keys in any of the standard Visual Studio locations as described in Set defaults for enterprise deployments. Options that are controlled by registry keys are items such as AdministratorUpdatesEnabled Reg_DWORD and AdministratorUpdatesOptOut Reg_DWORD. Admin access on the client computer is required to create and set the value of registry keys.

  • Configuration file: Some settings can be preserved on the client machine in an optional configuration file, which has the benefit of setting it only once and having it apply to all future administrator updates. The configuration file approach behaves like a registry key and is machine wide, which means it will apply to all installs of Visual Studio installed on the client machine. The standard location for the configuration file is at C:\ProgramData\Microsoft\VisualStudio\updates.config. However, if you wish to use another location to store the file, you can do so by creating a Reg_SZ registry key called UpdateConfigurationFile and setting the value of this key to the path of your config file. This registry key can be place in any of the Visual Studio registry locations as described in Set defaults for enterprise deployments. If you choose to add a registry value for a custom configuration file location, it will look for that file; if the file doesn’t exist, then an exception will be thrown and the update will fail.

    The configuration file, which is in JSON format, supports the option installerUpdateArgs which is an array of strings separated by commas that specify more switches you can pass into the Visual Studio installer. If the contents of the file include an invalid field or an option that is not supported, then the update will fail. For more information, see Use command-line parameters to install Visual Studio.

    Here's an example configuration file:

    "installerUpdateArgs" : ["--quiet", "--noWeb"], 
"checkPendingReboot" :  "true"

  • Manually updating the Administrator Updates Package in SCCM: The command-line parameters of an individual administrator update package in SCCM can also be manually modified.

Verification, reports, and troubleshooting error codes

Determining that Visual Studio was updated

You can use one of the following methods to verify that the administrator update was installed correctly:

  • On the client computer, start Visual Studio, select Help > About, and verify that the version number matches the last number in the title of the intended update.
  • Use the vswhere tool on the client machine to identify the various versions of Visual Studio on the computer. For more information, see Tools for detecting and managing Visual Studio instances.
  • Each administrative update attempt generates several log files in the client machine’s %temp% directory that captures the progress of the update operation. Sort the folder by date and look for files that begin dd_updatedriver, dd_bootstrapper, dd_client, and dd_setup for the administrative updates, the bootstrapper, the Visual Studio Installer, and the setup engine, respectively. Verify that these log files contain a 0, indicating that the update was successfully applied. Note that these log files can also be used to verify that the configuration file is being used. Refer to the Visual Studio Log Collection Tool for further details.

Error codes and conditions

Important

Remember that Visual Studio must be closed before you install the update. If Visual Studio is open or being used, the update installation will be canceled.

Administrative updates may return the following return codes: 

Error code Definition
0 The administrative update was successfully installed.
1001 Visual Studio Installer or a related setup process is running. The update is not applied.
1002 Visual Studio Installer is paused. The update is not applied.
1003 Visual Studio is running. The update is not applied. This condition can be overruled using the --force flag.
1004 No internet detected. The update was unable to contact the internet location holding the updated files. The update is not applied.
1005 The AdministratorUpdatesEnabled registry value is set to 0 or not set at all. The update is not applied.
1006 The AdministratorUpdatesOptOut registry value is set to 1. The update is not applied. The key is intended for client computers that should not be updated by the administrator.
1007 The Visual Studio Installer is not installed.
1008 The BaselineStickinessVersions2019 registry value is not in a readable format.
1009 The Visual Studio instance is configured to use a layout, but the layout is missing packages to perform the update.
3010 The system requires a reboot. The update may or may not have been applied. Reboot the computer and attempt the update again.
862968 The update was successful, and a restart is recommended but not required.
Other Error occurred attempting to apply the update. The update is not applied.

For an exhaustive list of client error codes, see Use command-line parameters to install Visual Studio.

Feedback and support

Support or troubleshooting

Sometimes, things can go wrong. If your Visual Studio installation fails, see Troubleshoot Visual Studio installation and upgrade issues for step-by-step guidance.

Here are a few more support options:

  • We also offer an installation chat (English only) support option for installation-related issues.
  • Report product issues to us via 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.
  • Suggest a feature, track product issues, and find answers in the Visual Studio Developer Community.

You can use the following methods to provide feedback about Visual Studio administrator updates or report issues that affect the updates:

See also