The Windows® Optional Component Setup (OCSetup.exe) tool is a command-line tool that can be used to add system components to an online Windows image. It installs or removes Component-Based Servicing (CBS) packages online by passing packages to the Deployment Image Servicing and Management (DISM) tool for installation or removal. OCSetup can also be used to install Microsoft® System Installer (MSI) packages by calling the Windows Installer service (MSIExec.exe) and passing Windows Installer components to it for installation or removal. In addition, OCSetup can be used to install CBS or MSI system component packages that have associated custom installers (.exe files). The OCSetup tool is available as part of the Windows® 7 and Windows Server® 2008 R2 operating systems.

You can use OCSetup.exe on a computer running Windows 7 or Windows Server 2008 R2.

Important:
  • To use OCSetup, the system MSI packages must be staged before they are installed, and the paths to the packages must be specified in an answer file (Unattend.xml). Staging the installer file is done by placing the file in either the location specified by the CustomSetup registry key or in the default location of %WINSYSDIR%\SysMSI\Stage\<Component>, where <Component> is the name of the installer as defined in the Registry setting for the installer.
  • Before running the OCSetup tool at a command prompt, set the command prompt to run as an administrator (even if you are logged on as an administrator on the computer).

Command-Line Options

The following command-line options are available for use with OCSetup.

ocsetup.exe [/?] [/h] [/help] component [/log:file] [/norestart] [/passive] [/quiet] [/unattendfile:file] [/uninstall] [/x: parameter]

Parameter Description

/?, /h, /help

Displays Help for all options whether they are run with or without options.

Example:

start /w ocsetup /help

component

The name of the component to be installed or uninstalled. The component name is case sensitive.

Separate multiple components to be installed or uninstalled with a semicolon.

If you are configuring Windows features without using an answer file that was created in Windows System Image Manager (Windows SIM), use the command-line name in the Windows-Foundation-Package section of the Unattended Windows Setup Reference.

Example:

start /w ocsetup <component_name>

/log: file

Specifies a non-default log file location. If an invalid path is specified, the log file will be created in the default log file location.

The default log file locations are:

  • The current directory when updating a Windows 7 or Windows Server 2008 R2 operating system.

  • The \windows\system32 directory for a Windows Vista® and Windows Server® 2008 operating system.

Note:

The size of the log file should be considerably smaller for Windows 7 operations.

Example:

start /w ocsetup <component_name> /log:C:\test\ocsetup.log

/norestart

The computer is not rebooted even if required after component installation.

Example:

start /w ocsetup <component_name> /norestart

/passive

Unattended mode. Only displays progress.

Example:

start /w ocsetup <Windows Installer MSI or package name> /unattendfile:<path to answer file> /passive

/quiet

Quiet mode. No user interaction.

Example:

start /w ocsetup <component_name> /quiet

/unattendfile: file

The file contains overrides or additions to default configuration settings. Implies passive mode.

Example:

start /w ocsetup <Windows Installer MSI or package name> /unattendfile:<path to answer file>

/uninstall

Uninstalls the component. Installation is the default.

Example:

start /w ocsetup <component_name> /uninstall

/x: parameter

Additional configuration parameters to be applied when installing a component that requires a custom installer. OCSetup will pass these parameters to the custom installer.

To determine if a component has a custom installer, review the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\OptionalComponents\componentName

The value of CustomSetup is the name of the custom installer. If the CustomSetup value is supplied, OCSetup defers to the indicated .exe file to perform the installation of the package. The .exe file is expected to conform to the same command-line specification as OCSetup.exe, and must return the same exit codes.

Note:

This registry key will not exist if system MSI files are not installed. In addition, this registry key will not exist if you have not registered the packages that require a custom installer and have not defined the custom installer.

Example:

start /w ocsetup <component_name> /x:<parameters>

Installing or Uninstalling a Package That Requires a Custom Installer

If you are installing or uninstalling a package that requires a custom installer, you must register the name of the package. When you register the name of the package, you also identify the type of package (CBS or MSI), any updates that have been applied, and the name of the custom installer .exe file.

To register a package that requires a custom installer, edit the following registry key.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\OCSetup\Components\ ComponentName

Add the following values under this key:

Value Type Data

Type

REG_DWORD

Type of package

0 - CBS

1 - MSI

Component

REG_SZ

The name of the CBS update or the path to the MSI.

PatchFiles

REG_MULTI_SZ

(Optional) Path to the MSI update file.

CustomSetup

REG_SZ

(Optional) Path to the custom installer .exe file.

The custom installer is expected to conform to the same command-line specification as OCSetup.exe, and must return the same exit codes.

Examples

The following table gives examples of using OCSetup on Client editions of Windows to install Windows optional components.

Optional Component Command

SNMP (Simple Network Management Protocol)

 
start /w ocsetup SNMP

Telnet Client

 
start /w ocsetup TelnetClient

Hearts

 
start /w ocsetup Hearts

This has a dependency on the InboxGames Optional Component, which must be installed first.

The following table gives examples of using OCSetup on Server editions of Windows to establish server roles that have no dependencies.

Server Role Command

Dynamic Host Configuration Protocol (DHCP) Server

 
start /w ocsetup DHCPServer

Domain Name System (DNS) Server

 
start /w ocsetup DNS-Server-Full-Role

Windows Deployment Services (Windows DS)

 
start /w ocsetup Microsoft-Windows-Deployment-Services

The following table gives examples of using the OCSetup tool to enable Windows features available in server editions.

Windows Feature Command

Desktop Experience

 
start /w ocsetup DesktopExperience

This has a dependency on the InkSupport Optional Component, which must be installed first.

Certificate Services

 
start /w ocsetup CertificateServices

Windows Server Backup

 
start /w ocsetup WindowsServerBackup

Troubleshooting

To run OCSetup as an administrator

Note:

This procedure is not necessary if you are running a Server Core installation of the Windows Server® 2008 R2 operating system.
  1. Click Start, point to All Programs, and then click Accessories.

  2. Right-click Command Prompt, and then click Run as administrator.

To verify that a component is installed, do one of the following:

  • Verify in the Event Viewer that OCSetup raised the event OCSETUP_EVENT_INSTALLSUCCESS.

  • If you are enabling a Windows feature, in Control Panel, click Programs, under Programs and Features, click Turn Windows features on or off, and then confirm that the check box for the Windows feature is selected. You can also open the Turn Windows features on or off dialog box by running OptionalFeatures.exe from the command prompt.

  • On a Server Core installation, run OCList.exe to list the server roles and optional features that are currently installed. The OCList tool is installed by default on a computer running a Server Core installation.

To verify that a component was removed, do one of the following:

  • Verify in the Event Viewer that OCSetup raised the event OCSETUP_EVENT_UNINSTALLSUCCESS.

  • If you are disabling a Windows feature, in Control Panel, click Programs, and then, under Programs and Features, click Turn Windows features on or off. Confirm that the check box for the Windows feature is cleared.

    On a Server Core installation, run OCList.exe to list the server roles and optional features that are currently installed. The OCList tool is installed by default on a computer running a Server Core installation of Windows Server 2008 R2.

Additional troubleshooting information can be found in the following log files:

  • Windows Update log (%WINDIR%\WindowsUpdate.log)

  • Component-Based Servicing Log (%WINDIR%\logs\cbs\cbs.log)

OCSetup fails to configure some Windows features

OCSetup fails to enable or disable Windows features that include spaces in the feature name. For example, the Windows features “More Games”, “Internet Checkers”, and “Internet Backgammon” all include spaces.

Workaround: Use the DISM command to enable or disable features from the command line. For example, dism /online /enable-feature /featurename:"More Games" Additionally, you can configure Windows features by using an answer file and selecting the appropriate package action.

Using OCSetup and an answer file to install or uninstall a component may fail

If you attempt to install or uninstall a component using OCSetup and an unattended answer file, the procedure can fail even if the unattended file includes the root-level component.

Workaround: Use DISM to apply the unattended answer file instead of using OCSetup.

Additional Information

For more information about installing or removing system components, see this Microsoft Web site.

See Also