App Layering

Prepare your OS image for layering in Azure

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.exe operations, if you think it is taking too long.

If using Windows 10 and not running Citrix Provisioning, machine creation, 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.

Note:

Do not use an unattend file in Azure. The App Layering software removes the unattend file if it is present, because it is not necessary or recommended in Azure.

Install the OS on a virtual machine

  1. In the Microsoft Azure portal, create a new virtual machine from the Windows Server Remote Desktop Session Host Windows Server 2016 or 2012 R2 image by selecting: New > Compute > Virtual Machine > From Gallery > Windows Server Remote Desktop Session Host Windows Server 2012 R2
  2. Choose Resource Manager from the Select a deployment model option list, and click Create.

    Note:

    The App Layering software does not support the Classic option from the Select a deployment model option list.

  3. Complete the Create virtual machine wizard:

    Basics:

    • Name: The name you specify for the new machine must comply with Azure naming conventions.
    • Username and password: The user name and password of the new server machine you specify are used for any packaging machines that are created containing this OS layer.
    • Resource group location: Be sure that the value for the Resource group location matches the Storage account location that you configured in the connector configuration.

    Settings:

    • Storage: Under Use managed disks, select No, and specify a storage account.
  4. Select required network settings.
  5. Review the summary and create the virtual machine.
  6. Log into the new virtual machine, and reboot the machine.
  7. Install all important updates. Be sure to reboot the system and check for more updates. Some updates become available only after others are installed.
  8. Run Windows Ngen.exe.
  9. Remove or rename the Unattend file in C:\Windows\OEM.
  10. Clear Windows Automatic Updates by selecting: Control Panel > System and Security > Windows Update > Change Settings
  11. Ensure that this machine is not joined to a domain.
  12. Enable the built-in administrator and check Password never expires.
  13. If this is a server OS, run the following commands in PowerShell:

    Set-ExecutionPolicy Unrestricted
    Enable-PSRemoting
    

Run the App Layering OS Machine Tools on the image

  1. On the new machine, open a web browser, navigate to the Download Center and download the OS Machine Tools.
  2. Download the following zip file onto the OS image:

    Citrix_App_Layering_OS_Machine_Tools_19.x.x.exe
    
  3. Run the file, and it copies files to:

    c:\windows\setup\scripts

    Note:

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

If using Key Management Service, configure license activation

Once the scripts are extracted, the SetKMSVersion utility asks you to choose whether to use Key Management Service (KMS) licensing.

Note: Publishing images into environments where both KMS and Active Directory-based activation (ADBA) are being used at the same time causes problems with activation.

  1. In the following dialog box, select whether to use Key Management Service (KMS) licensing.

    Set KMS version image

To configure scripts for KMS, do the following.

  1. Navigate to:

    c:\windows\setup\scripts

  2. Run SetKMSVersion.exe as Administrator to create a script file in the c:\windows\setup\scripts\kmsdir folder.

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

Install the App Layering services

  1. On the new machine, navigate to C:\Windows\Setup\scripts and run setup_x64.exe to install the App Layering drivers on the OS machine.
  2. The installation prompts you for the location of the Unattend.xml file (the default location is ‘C:\windows\panther).
  3. Ensure that this machine is not joined to a domain.
  4. Perform pending reboots on the OS machine so that you can import this image into a layer.
  5. Make sure that the new OS machine is in one of the following states before proceeding.
    • Running
    • Stopped
    • Stopped (deallocated)

Expedite a Microsoft Ngen.exe operation, if necessary

Once all software updates have been installed, you must allow Ngen.exe to essentially recompile .NET byte code into native images and construct the registry entries to manage them.

Ngen.exe is the Microsoft Native Image Generator, which is part of the .NET system. Windows determines when to run Ngen.exe based on what software is being installed and what Windows detects in the configuration.

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

Normally, Ngen.exe is a background operation that pauses when there is foreground activity. If you want to expedite an Ngen.exe operation, you can bring the task into the foreground to complete it as quickly as possible.

To bring the task into the foreground:

  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 following Ngen.exe command to run all queued items. This command processes queued component installs before building assemblies.

    ngen eqi 3

    The Ngen.exe task moves to the foreground in the command prompt, and lists the assemblies being compiled. It is OK if you see compilation messages.

    You can use the Task Manager to see if an instance of MSCORSVW.EXE is running. If it is, allow it to complete, or run ngen update eqi 3.

    Caution: Do not reboot to stop the task. Allow the task to complete!

  4. Ensure that all Ngen.exe processes have run to completion.

Prepare your OS image for layering in Azure