Product Documentation

Prepare your OS image for layering in Citrix Hypervisor, Hyper-V, or vSphere

This topic explains how to prepare a clean OS image for import into a new OS layer. Before you start, make sure that you meet the requirements. While preparing the image, you can Expedite Microsoft NGen operations, as described at the end of this article.

If using Windows 10 and not running PVS, MCS, or View, you can speed up desktop start times by removing Windows 10 built-in applications. However, we recommend removing the apps on a new version of the OS layer, not in the OS image itself.

Install the OS on a virtual machine

It is crucial to start with an OS freshly installed from ISO, preferably from your hypervisor.

In this procedure, be sure to follow steps and notes specific to the Windows version you are installing.

  1. Log into your hypervisor client.
  2. Create a virtual machine with the correct CPU, RAM, and network settings for your operating system type.
    • Memory:
      • Windows 7, Windows Server 2008R2
        • 1-2 CPUs
        • 2 GB RAM
      • Windows 8, Windows Server 2012
        • 1-2 CPUs
        • 2 GB RAM
      • Windows 10, WIndows Server 2016 R2
        • 1-2 CPUs
        • 4-8 GB RAM
    • Hard drive:
      • Large enough to accommodate an OS installation.
    • Network:
      • Citrix Hypervisor virtual machine: Make sure that only one network is selected.
      • VMware virtual machine: You must select the VMXNET 3 network adapter. >Important: You can have one, and only one, network device, and the E1000 NIC should never have been used. The default E1000 adapter (or even a ghost NIC leftover from an E1000 adapter) can cause customization timeout errors on the virtual machines.
    • Thin Client:
      • vSphere virtual machine: Select Thin Client.
  3. Configure a virtual hard disk that is large enough for a Windows installation. Make sure it can be accessed by the appliance.
  4. Attach the ISO and install the operating system. This machine should not be joined to the domain.
  5. Install your hypervisor tools on the OS image. If you have more than one hypervisor, install the tools for the second hypervisor on the Platform layer. The tools on the Platform layer take precedence over the tools installed on the OS layer.


    Use the Microsoft Windows Integration Services Setup Disk to install Hyper-V Integration Services.

  6. If installing a server OS and you need a session host feature, install the feature as follows:
    1. In the Server Manager, select Add roles and features.
    2. For the Installation Type, select Role-based or Feature-based installation.
    3. For the Server Role, select Remote Desktop Services > Remote Desktop Session Host (Installed).
    4. Complete the process of adding the Server Roles.
  7. Install all important updates. Check for updates again after the virtual machine is rebooted, because some updates became available only after others are installed.
  8. Install all required service packs:
    • If using Windows 2008 R2 with PVS or Horizon View, install Windows Server 2008 R2 Service Pack 1 (SP1).
  9. Install all required hot fixes:
    • Windows 2008 R2 or Windows 7 with PVS or MCS:
      • If you are using PVS or MCS, install hotfix KB2550978 and restart the virtual machine.


        You may need to uninstall KB3125574, before installing this one.

  10. Turn off Windows Automatic Updates and disable Windows System Restore using the local group policy editor, gpedit.msc. The system handles restore points for you. Layer versions allow you to specify when updates occur.
  11. Windows 10: Turn off Hibernation by entering this command:
    powercfg.exe /hibernate off
  12. Enable the built-in administrator and check Password never expires.
  13. If using KMS licensing, run a command window as Administrator, and enter these commands:
    slmgr /skms <kmsserverhost>
    slmgr /rearm
    slmgr /ipk XXXX-YOUR-KMS-KEY-XXXX
    slmgr /ato
  14. If this is a server OS:
    1. Add Domain Users to the Remote setting. Choose an option, and then specify who can connect.
    2. Run the following commands in PowerShell:
      Set-ExecutionPolicy Unrestricted
  15. Check Network and ghost NICs and delete if any exist.
    1. Enter the commands:
      set devmgr_show_nonpresent_devices=1
    2. Uninstall any dead (ghost) NICs.

Run the App Layering OS Machine Tools on the image

To prepare the OS image to run in a layer, you execute the the OS Machine Tools file on the image. This executable runs a GPO setup script (gposetup.cmd), and a Set KMS Version script (SetKMSVersion.hta).

  1. Download the following executable file onto the OS image:
  2. Run the executable. Files are extracted to:


    The file must be extracted to the above directory. Do not change the directory.

If using Key Management Service (KMS), configure license activation

Once the scripts are extracted, the SetKMSVersion utility asks you to choose whether or not to use KMS licensing.

  1. In the dialog box that appears, select whether or not to use Key Management Service (KMS) licensing.

    Set KMS version image

To configure scripts for KMS, do the following.

  1. Navigate to:


  2. Run SetKMSVersion.hta as Administrator. This creates a script file in the c:\windows\setup\scripts\kmsdir folder.

When the operating system starts, the appropriate KMS activation script is executed.

Make sure the correct versions of .Net Framework are installed (Windows 7, Windows 10, Windows Server 2016)

The .Net Framework is a software framework provided by Microsoft, and it is required for many 3rd party applications to run.

  • /.NET Framework 4.5: Required on Windows 7.
  • /.NET Framework 3.5: Required on Windows 10 and Windows Server 2016.

To install .NET Framework:

  1. On the Start menu, select Control Panel > Programs and Features.
  2. In the left panel select Turn Windows features on or off. A window opens.
  3. Select the correct version of .NET Framework, click OK, and wait for the installation to complete.


    Even if .NET is already installed, continue with the rest of these steps.

  4. Exit the Control Panel.
  5. In Notifications in the right-side of your taskbar, click All Settings, and open the Windows 10 Settings app.
  6. Select Settings > Update & Security.
  7. Check for updates, and install all updates available.
  8. Exit Settings.
  9. Open an administrator-level command prompt, and enter the following commands:

    cd \windows\Microsoft.Net\Framework\v4.nnnnn
    ngen update /force
  10. Wait for the command to complete, and enter the following commands:

    cd \windows\Microsoft.Net\Framework64\v4.nnnnn
    ngen update /force
  11. Exit the command prompt.

Install the App Layering services

  1. In the Citrix_App_Layering_OS_Machine_Tools folder, run the setup_x86.exe (32-bit) or setup_x64.exe (64-bit).

  2. If you are using an unattend file, the installation prompts for the location of the file. The default location is c:\windows\panther.

Once this is done, you are ready to import the image into a new OS layer.

Run the Optimization script, if using MS Office

The Optimization script included in the App Layering installation package is required to layer Microsoft Office. This script allows you to save memory and CPU by disabling services you don’t need, enabling services you do need, and removing installation-specific drivers and settings.

You can run the Optimization script on the OS layer, and if needed, supercede it with a new version of the script in an App layer included in your image template. Since App layers are applied to the image after the OS layer, the script in the App layer overrides the original version in the OS layer.

  1. In the c:\windows\setup\scripts folder, run the optimizations.cmd file to create a file that will be run when the image is created.

  2. If you run the unattend.hta file, the optimizations.cmd file is run automatically. If you run optimizations.cmd without first running unattend.hta, follow the instructions to run it on the OS Image.

    If you are using the Optimizations script and you are enabling the View Persona feature, you must go to the section of the script called Disable Unnecessary Services to Save Memory and CPU, deselect the option to Disable Offline File Service, and click Save File. This is because View Persona folder redirection requires Offline files to be enabled, and by default, the optimization script turns off any offline files that are not a requirement for App Layering.

If you need to run Windows Mini Setup, use our answer file

If you need to run Windows Mini Setup, follow these steps to use our unattend.hta answer file.

  1. In the c:\windows\setup\scripts folder, right-click the unattend.hta tool and choose Run as administrator. The unattend builder form opens.
  2. Complete the unattend form.Product key activation.
    • For KMS activation, select KMS Server.
      • For KMS with a Multiple Activation Key (MAK), select KMS with MAK and enter the MAK.
      • For Retail Licensing with a MAK, select Retail with MAK, and the MAK.
    • Local Administrator account
      • If you want to use the unattend.xml file to enable the Administrator account on each Layered Image, select Enable. Remember to also enable this account in your OS Image or Operating System Layer revision. It is possible to enable the Administrator account for your OS Image and then have it disabled in the deployed Layered Images by clearing the check box
      • If you want to add an alternate Administrator account, select Enable and enter the account information. This account cannot be pre-configured in the OS Image.
      • You can create a Layered Image where the Administrator is disabled and the alternate administrator is created and enabled. However for this to work, the Administrator account must be enabled in the OS Image and it cannot be renamed.
    • Time zone
      • Select the time zone. If your time zone is not listed, you can add it to the Other box. Be sure to use the time zone, not the display setting. A list of time zone settings can be found in Microsoft TechNet.
    • Disabling automatic activation
      • Select this option if you plan to use the Microsoft Volume Activation Management Tool.
  3. Click Save File.

Expedite Microsoft NGen operations, if needed

NGen is the Microsoft Native Image Generator. It is part of the .NET system, and essentially recompiles .NET byte code into native images and constructs the registry entries to manage them.

Windows decides when to run NGen based on:

  • What is being installed.
  • What Windows detects in the configuration.

When NGen is running, you must let it complete. An interrupted NGen operation can leave you with non-functioning .NET assemblies or other problems in the .NET system.

Force an NGen operation to the foreground

Normally, NGen is a background operation that pauses if there is foreground activity. Bringing the task into the foreground helps the task to complete as quickly as possible.

  1. Open a command prompt as Administrator.
  2. Go to the Microsoft .NET Framework directory for the version currently in use:

    cd C:\Windows\Microsoft.NET\FrameworkNN\vX.X.XXXXX
  3. Enter the NGen command to execute the queued items:

    ngen update /force

    This brings the NGen task to the foreground in the command prompt, and lists the assemblies being compiled.

    It is okay if you see several compilation messages. You can use Task Manager to see if an instance of MSCORSVW.EXE is running. If it is, you must allow it to complete, or run `ngen update /force.


    Do not reboot to stop the task. You must allow it to complete.

  4. Ensure that all NGen processes have run to completion.
  5. When complete, you can now shut down the virtual machine.