Product documentation
App Layering
View PDF

Update layer

February 8, 2023
Contributed by: 
D C E

The steps for updating the software in an OS, platform, or app layer are virtually the same. You add a version to the layer, install the upgrade or patch on the packaging machine, verify, and then finalize the layer. Once updated, you deploy the new layer version, which varies based on the type of layer.

The platform layer is the highest priority layer and critical for the deployment of images, especially with regards to devices, such as your networks. Whenever you update the infrastructure software, you must add a new version to the platform layer.

You add a version to the platform layer using the new OS layer as the base. Once the packaging machine has started, shut down the machine for finalization. The platform layer gathers the critical components from the new OS layer version, and updates them in the platform so that they match the OS version.

Add a version to the layer

For example, to add a version to an OS layer:

  1. In the Citrix App Layering Management Console, select Layers > OS Layers
  2. Select an OS layer and click Add Version on the Version Information tab.
  3. In Version Details:
    1. For Base Version, select the version to use as the base for the new layer version. The default is the latest version.
    2. Enter a name for the New Version. This can be the OS version or other identifying information.
  4. Select a Connector configuration for the hypervisor where you create your layer.
  5. Enter a file name for the Packaging Disk, and select the disk format to use if you are using the appliance’s File Share, instead of a connector configuration. This disk is used for the packaging machine (the virtual machine) where you install the application.
  6. Verify your settings and click Add Version. This runs a task to create an OS version. When the task completes, it shows a status of Action Required. When you select the task and click View Details, the following text displays:

“The Packaging Disk has been published. The virtual machine ‘<…>’ can be found in folder ‘<…>’ in data center ‘<…>’. Power on this virtual machine to install your application. When the installation is complete, power off the virtual machine before clicking Finalize on the Action bar.”

Next, you can deploy a packaging machine for this OS layer version.

Deploy a packaging machine to your hypervisor

The packaging machine is a virtual machine where you install the updates or applications to include in the layer. The packaging machine is a temporary virtual machine that is deleted once the OS layer has been finalized.

The task description contains directions to navigate to the location in your hypervisor where the packaging machine for this layer has been created.

  1. To create the packaging machine in your hypervisor, begin with the expanded packaging disk task shown in step 2.
  2. Log into your hypervisor client.
  3. Back in the management console, use the instructions in the expanded packaging disk task to navigate to the packaging machine.

Install the OS update

  1. Remote log into the packaging machine. Be sure to log in to the User account you used to create the OS.
  2. Install any updates or applications you want to include in the new OS layer version, such as Windows Updates or antivirus applications.
  3. If an application installation requires a system restart, restart it manually. The packaging machine does not restart automatically.
  4. Make sure the packaging machine is in the state you want it to be for the user:
    1. If the applications you install require any post-installation setup or application registration, complete those steps now.
    2. Remove any settings, configurations, files, mapped drives, or applications that you do not want to include on the packaging machine.

Next, you shut down the packaging machine and verify that the layer is ready to finalize.

Note:

When you upgrade Windows 10 from one major version to another (1703 to 1709, for instance), the previous Windows installation is left in a C:\Windows.old folder. In App Layering, you must not delete this folder. Our software needs to copy our drivers and other files from Windows.old to Windows once the upgrade is completely finished. We will clean up Windows.old when you Finalize the OS layer.

Verify the Layer and shut down the packaging machine

The next step is to verify that the layer is ready to be finalized. To be ready for finalization, any required post-installation processing, for example, a reboot or a Microsoft ngen process, must complete.

To verify that any outstanding processes are complete, you can run the Shutdown For Finalize tool (icon below), which appears on the Packaging Machine’s desktop.

To use the Shutdown For Finalize tool:

  1. If you are not logged into the packaging machine, remote login as the user who created the machine.
  2. Double-click the Shutdown For Finalize icon. A command line window displays messages detailing the layer verification process.
  3. If there is an outstanding operation that must be completed before the layer can be finalized, you are prompted to complete it. For example, if a Microsoft ngen operation must complete, you can try to expedite the ngen operation, as detailed below.
  4. Once any pending operations are complete, double-click the Shutdown For Finalize icon again. This shuts down the Packaging Machine.

The layer is ready to finalize.

If the connector configuration you selected is set to Offload Compositing, the layer is automatically finalized. Otherwise, the next step is to finalize the layer manually, as described in the next procedure.

Layer integrity messages

The following layer integrity messages tell you what queued operations must be completed before the layer is ready to finalize:

  • A RunOnce script is outstanding - please check and reboot the Packaging Machine.
  • A post-installation reboot is pending - please check and reboot the packaging machine.
  • A Microsoft ngen operation is in progress in the background. - An MSI install operation is in progress - please check the packaging machine.
  • A reboot is pending to update drivers on the boot disk - please check and reboot the packaging machine.
  • A Microsoft ngen operation is needed.
  • Software Center Client is configured to run, but the SMSCFG.INI is still present. To learn more about deploying SCCM in a virtual environment, see the Microsoft TechNet article, [Implementing SCCM in a XenDesktop VDI environment](https://social.technet.microsoft.com/wiki/contents/articles/23923.implementing-sccm-in-a-xendesktop-vdi-environment.aspx).

For details about what the layer integrity messages mean and how to debug them, see Debugging Layer Integrity Problems in Citrix App Layering 4.x and later.

You cannot bypass layer integrity messages by shutting down the machine. The App Layering software stops and returns you to the packaging machine until the processes have completed.

If a Microsoft ngen operation is in progress, you may be able to expedite it, as described in the next section.

Expedite Microsoft Ngen.exe operations, 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 <!--NeedCopy-->

  3. If using .NET Framework 3 or later, enter the following Ngen.exe command to run all queued items. This command processes queued component installs before building assemblies.

    ngen eqi 3 <!--NeedCopy-->

    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.

    Ensure that all Ngen.exe processes have run to completion. 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 eqi 3.

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

  4. If using .NET Framework 2 or earlier, enter the following Ngen.exe command to run the queued items.

    ``` ngen update /force 

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

>**Note:**
>It's okay if you see **compilation failed** messages.
Look in the Task Manager to see if an instance of MSWORD.EXE is running. If it is, you must allow it to complete, or rerun 'ngen update /force`. Do not reboot to stop the task. Allow it to complete.

Check the status of an `Ngen.exe` operation by opening a command prompt as Administrator and running this command: ```ngen queue status<!--NeedCopy-->

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

  5. When all operations are complete, shut down the virtual machine using the Shutdown For Finalize shortcut available on your desktop.

Finalize the layer manually

Once the packaging machine is created and any apps or updates installed, you can finalize the layer.

Note: When you finalize a new version of an OS layer, the system deletes the packaging machine so as not to incur more costs.

When a layer is ready to finalize:

  1. Return to the management console.
  2. In the Layers module, select the layer.
  3. Select Finalize in the Action bar.
  4. Monitor the Taskbar to verify that the action completes successfully and that the layer is deployable.
Update layer
February 8, 2023
Contributed by: 
D C E
February 8, 2023
Contributed by: 
D C E

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.