Applying administrator updates that use Microsoft Endpoint Configuration Manager
Applies to: Visual Studio Visual Studio for Mac
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.
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.
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:
- Security updates are applicable to all Visual Studio editions (e.g. Enterprise, Professional, Community, etc.), and they contain limited, highly targeted and compatible servicing level changes. 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. 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.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.
- 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 2019 version 16.7.0 to 16.7.12 update classified as a “Security Update” will apply to any Visual Studio 2019 edition on the client between versions 16.7.0 through 16.7.12, and it will update those client editions to 16.7.12.
- Visual Studio 2019 version 16.0.0 to 16.9.0 update classified as a “Feature Pack” will apply to Visual Studio 2019 editions licensed for enterprise use on the client between the entire product version range of 16.0.0 through 16.9.0, and it will update those client editions (that haven’t been configured to remain on an earlier servicing baseline) to 16.9.0.
- Visual Studio 2019 version 16.8.0 to 16.8.7 update classified as simply “Updates” will apply to Visual Studio 2019 editions licensed for enterprise use on the client between versions 16.8.0 through 16.8.7, and it will update those client editions to 16.8.7.
- Visual Studio 2022 version 17.0.3 update classified as "Security Update" will apply to any Visual Studio 2022 edition on the client that is on either the Current channel or the 17.0 LTSC channel, and bring it up to the 17.0.3 version.
- Visual Studio 2022 version 17.1.0 update classified as a "Feature Pack" will apply to Visual Studio 2022 editions licensed for enterprise use on the client that is on the Current channel, and it will update it to the 17.1.0 version.
- Visual Studio 2022 version 17.1.2 update classified as simply "Updates" will apply to Visual Studio 2022 editions licensed for enterprise use on the client that is on the Current channel, and it will update it to the 17.1.2 version.
- Visual Studio 2022 version 17.2.7 update classified as "Security Update" will apply to any Visual Studio 2022 edition on the client that is on either the Current channel or the 17.2 LTSC channel, and bring it up to the 17.2.7 version.
If the client instance is greater than the version of the administrator update that's being applied, then the administrator update will have no effect.
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.
- Servicing baseline stickiness: As described above, administrator feature updates advance a Visual Studio installation to a more current minor version of the product. Sometimes, however, Visual Studio users need to remain at a particular stable and secure servicing baseline level, and they want to control when their machines advances to a more current minor version. To configure a client machine to remain on a servicing baseline and ignore undesired administrator feature updates sent to it, you’ll need to create and set the BaselineStickinessVersions2019 Reg_SZ data value to a string that represents the preferred baseline that the client machine should snap to and stay on. The string can contain an allowable servicing baseline version such as 16.9.0.
BaselineStickinessVersions2019registry value is malformed, then all administrator feature updates will be blocked from installing on the machine. Make sure you pay attention to the supported timeframes for Visual Studio feature updates. Also, regardless of the presence or value of the
BaselineStickinessVersions2019key, while it is technically possible to apply administrator feature updates that have reached the end of their lifetimes, we don't recommend it because they will be out of support and thus potentially insecure.
- 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
--forceparameter 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
–-forceflag, 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
installerUpdateArgswhich 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_setupfor 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
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:
|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
|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:
- Refer to the Troubleshooting Visual Studio installation and upgrade issues guidance.
- Ask questions to the community at the Visual Studio Setup Q&A Forum.
- Go to the Visual Studio support page, and check whether your issue is listed in the FAQ. You can also select the Support Link button for chat help.
- Provide feature feedback or report a problem to the Visual Studio team regarding this experience of applying administrator updates.
- Contact your organization’s technical account manager for Microsoft.
- Enabling administrator updates
- Visual Studio administrator guide
- Visual Studio Product Lifecycle and Servicing
- Install Visual Studio
- Update Visual Studio
- Using Command Line Parameters to install Visual Studio
- Tools for detecting and managing Visual Studio instances
- Create a network installation of Visual Studio
- Update a Visual Studio client that was installed from a network layout
- Microsoft Update Catalog FAQ
- Microsoft Endpoint Configuration Manager (SCCM) documentation
- Import updates from Microsoft Catalog into Configuration Manager
- Windows Server Update Services (WSUS) documentation
Submit and view feedback for