Product Documentation

Create App layer

An app layer is a virtual disk. The app layer includes one or more applications that you can deploy in any number of layered images. This article walks you through App layer creation, including:

  • Requirements
  • Start a new App layer
  • Deploy the packaging machine
  • Install the application(s)
  • Finalize the layer


An App layer includes one or more applications and related settings. MS Office should always be installed in an App layer, and never in the OS layer.

  • Anti virus applications: Always put your anti virus application in an App layer using the instructions provided here. Be strategic with your virus definition file updates. Also, be aware of file marking features, for example, Symantec’s Virtual Image Exception Tool. Consider host-based scanning engines, and keep in mind the delay at user logon. Be sure to scan the published layered image, not the layer. Scanning is only done on user access on XenApp and XenDesktop.
  • MS Office: Use this recipe to install Office. For VDI deployments of Office 2010 and later, consider KMS a requirement. For Office 2007 and earlier, consider Volume licensing a requirement. Using other licensing structure is not as convenient, because they require each license to be activated on each desktop. To persist user settings and data, enable Office 365 User layer stores .OST and streaming files. Note that the search indexes are not stored.
  • Recipes for layering specific applications: Virtually any application can be layered, but some are easier to layer successfully on the first try if you use the tips we’ve assembled in our App Layering Recipes forum. Before you start, consult the forum for tips and procedures about the specific applications you are layering.

App layer options

When creating and updating App layers, keep in mind the following advanced features.

  • Run Once script - To run a script upon system startup.
  • Layer caching - For faster App layer creation
  • Prerequisite layers (rarely recommended)

Start a new App layer

To create a packaging machine where you can install the application(s):

  1. Log into the management console and select Layers > App Layers.
  2. Click Create Layer in the Action bar.
  3. In the wizard’s Layer Details tab, enter a Layer Name and Version, both required values. You can also enter other values, but this is optional. For details, see more about these values below.
  4. On the OS Layer tab, select the OS Layer you want to associate with this App layer.
  5. (Optional) The Prerequisite layers tab gives you the option to specify other App layers that must be present while installing the apps on this layer. Only use this when the required apps cannot be included in the same layer. For more information about this advanced feature, see Prerequisite layers below. Note: When adding a new version to an existing App layer, you must specify the Prerequisite layers you need. They are not carried over from version to version.
  6. In the Connector tab, choose a connector configuration that includes the credentials for the platform where you plan to build the layer and the storage location. If the configuration you need isn’t listed, click New to add one.
  7. On the Packaging Disk tab, type a file name for the packaging disk, and choose the disk format. This disk is used for the packaging machine, the virtual machine where you install the application.
  8. On the Icon Assignment tab, choose an icon to assign to the layer. This icon represents the layer in the Layers Module.
    • To use an existing image, select an image in the image dialog box.
    • To import a new image, click Browse and select an image in PNG or JPG format.
  9. On the Confirm and Complete tab, review the details of the app layer and then click Create Layer. You can type an optional comment before creating the layer. Your comments appear in the Information view Audit History. After creating the packaging disk, the Tasks bar displays a link to the packaging disk in your hypervisor where you can deploy the packaging machine.
  10. Expand the Tasks bar at the bottom of the page and double-click the Packaging Disk task. The task expands to show the full task description, including a link to the location where the packaging machine for this layer is published.

Next, you can deploy the packaging machine for your layer.

Deploy the packaging machine

Select your hypervisor:

  • XenServer, Hyper-V, Nutanix, or vSphere
  • Azure
  • Other hypervisor (Network File Share)

XenServer, Hyper-V, Nutanix, vSphere

  1. Log into your hypervisor client (XenServer, Hyper-V Manager, Nutanix Prism, or vSphere).
  2. Log into the App Layering management console, and expand the tasks bar at the bottom of the console so you can see the current tasks.
  3. Double-click the Create App layer task to see the full task description.
  4. Use the URL provided in the task description to navigate to the packaging machine in your hypervisor client.
  5. The packaging machine is powered on.

You can now install the applications for this layer on the packaging machine.


The appliance opens the Azure Custom deployment template, where you can create the packaging machine.

  1. Log into the Azure portal ( Note: You must log in before attempting the next step.
  2. Go to the App layering management console, expand the Tasks bar at the bottom of the console. Open the Create App layer task details.
  3. Use the link in the task details to navigate to the packaging machine in Azure. The Custom deployment panel opens.
  4. Set the Azure parameters.
    • Packaging Machine Name - must conform to Azure virtual machine name requirements.
    • Size – virtual machine size.
    • Virtual Network and Subnet - for deploying the packaging machine. IMPORTANT: Make sure the value of the Resource group location matches the Storage account location that you configured in the connector configuration. If these locations are not the same, the packaging machine fails to deploy. If your deployment does fail, you can paste the link into the browser again and start over.
  5. Once your packaging machine is powered on, you can install the application(s) you want to include in the layer.

Other hypervisor (by way of the appliance’s Network File Share)

  1. Locate the packaging disk in the following directory on the Network File Share: \Unidesk\Packaging Disks

  2. Copy the packaging disk to a separate location on your hypervisor. This allows space for the files generated by your hypervisor when you use the disk to create a new virtual machine.

    Important: Do not copy the disk to the Finalize folder until it is ready to finalize. A disk in the Finalize folder cannot be attached to the new virtual machine that you are going to create next.

  3. Create a virtual machine using the packaging disk as the boot disk.

  4. Power on the packaging machine.

Once your packaging machine is powered on, you can install the application(s) you want to include in the layer.

Install the application(s)

When installing your application(s) on the packaging machine, leave the application(s) as you want users to see them when they log in. The application’s state is what users experience every time they access the app.

  1. Remote log into the packaging machine with the User account used to create the operating system.
  2. Install the application(s), along with any drivers, boot-level applications, or files required for the app.
  3. If a system restart is required, restart it manually. The packaging machine does not restart automatically. If the application you install affects boot-level components, you’ll need to restart the packaging machine as part of finalizing the layer or version.
  4. Make sure the packaging machine is in the state you want it to be in for the user:
    • If the application(s) require any post-installation setup or registration, complete those steps now.
    • Remove any settings, configurations, files, mapped drives, or applications that you do not want to include on the packaging machine.

Verify the layer and shut down the machine

Once the application is installed on the packaging machine, it is important to verify that the layer is ready to be finalized. To be ready for finalization, any required post-installation processing needs to be completed. For example, a reboot may be required, or a Microsoft NGen process may need to complete. To verify that any outstanding processes are complete, you can run the Shutdown For Finalize tool, which appears on the packaging machine’s desktop. image

To use the Shutdown For Finalize tool:

  1. If you are not logged into the packaging machine, remote log in 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 to be completed before the layer can be finalized, you are prompted to complete the process. If a Microsoft NGen operation needs to complete, you may be able 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, and the layer is ready to finalize.

Layer integrity messages you may see during the finalization process

Layer integrity messages let you know what queued tasks must be completed before a layer is finalized. The new layer or Version can only be finalized when the following conditions have been addressed:

  • A reboot is pending to update drivers on the boot disk - please check and reboot the packaging machine.
  • A post-installation reboot is pending - please check and reboot the packaging machine.
  • An MSI install operation is in progress - please check the packaging machine.
  • A Microsoft NGen operation is in progress in the background. Note: If a Microsoft NGen operation is in progress, you may be able to expedite it, as described in the next section.

Expediting a Microsoft NGen operation

NGen is the Microsoft Native Image Generator. It is part of the .NET system, and basically re-compiles .NET byte code into native images and constructs the registry entries to manage them. Windows will decide when to run NGen, based on what is being installed and 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. You have the choice of waiting for the NGen to complete in the background, or you can force the NGen to the foreground. You can also check the status of the NGen operation, as described below. However, every time you check the queue status, you are creating foreground activity, which might cause the background processing to temporarily pause. Forcing the NGen to the foreground will allow you to view the progress and once the output has completed, you should be able to finalize the layer.

  1. Force an NGen operation to the foreground.Normally, NGen is a background operation and pauses if there is foreground activity. Bringing the task into the foreground can help the task to complete as quickly as possible. To do this:
    1. Open a command prompt as Administrator.
    2. Go to the Microsoft .NET Framework directory for the version currently in use:
    3. cd C:\Windows\Microsoft.NET\FrameworkNN\vX.X.XXXXX
    4. Enter the NGen command to execute the queued items:
    5. ngen update /force
    6. This brings the NGen task to the foreground in the command prompt, and lists the assemblies being compiled.
    7. Note: It’s okay if you see several compilation failed messages! Look in the Task Manager to see if an instance of MSCORSVW.EXE is running. If it is, you must allow it to complete, or re-run ngen update /force. Do not reboot to stop the task. You must allow it to complete.
  2. Check the status of an NGen operation
    1. Open a command prompt as Administrator.
    2. Check status by running this command: ngen queue status
    3. When you receive the following status, the NGen is complete, and you can finalize the layer.The .NET Runtime Optimization Service is stopped

Finalize the Layer

Once the software has been installed and the packaging machine has been verified and shut down, you are ready to finalize the layer.

XenServer, Azure, Hyper-V, Nutanix AHV, VMware vSphere

Now that the Layer has been verified and shut down, it is ready to finalize.

  1. Return to the management console.
  2. Select Layers > App layers, and then the layer you just prepared.
  3. Select Finalize in the Action bar. The Finalize wizard opens.
  4. (Optional) On the Script Path wizard tab, you can enter the path to a Run Once Script located on a server on your network. If the App layer is:
    • Elastically assigned - The Run Once script is executed the first time the app is used.
    • Included in a layered image - The Run Once script is executed the first time the layered image is booted.
  5. Click Finalize to finish creating the layer.
  6. Monitor the task bar to verify that the action completes successfully.

Once the layer is verified, the packaging machine is removed to minimize storage space used.

Other hypervisor (Network File Share)

Now that the Layer has been verified and shut down, it is ready to finalize.

  1. Copy the Packaging Disk from the folder containing the Packaging Machine files to the Finalize folder on the Network File Share: \Unidesk\Finalize

  2. Return to the Management Console.

  3. Select Layers > App Layers.

  4. Select Finalize in the Action bar.

  5. Monitor the Task bar to verify that the action completes successfully and that the layer is deployable.

App layer options

Before you create an App layer, you can create resources that assist with installing the application.

  • Run Once script
  • Layer Caching for faster App layer creation
  • Create prerequisite layers

Run Once Script

You can include a Run Once script in an app layer. The script runs the first time any layered image that includes the app layer starts. If the app layer is elastically layered, the Run Once script runs when mounting the app layer disk. Run Once scripts are typically used for apps, such as MS Office, that requires activating the license when Office starts for the first time.

Layer Caching for faster App layer creation

If you are creating multiple App layers that use the same OS layer, Platform layer, and Prerequisite layer(s) if you have them, you can save significant time by setting the Layer Disk Cache Size in the connector. If Cache Size is set to a value greater than 0, the first time you create an App layer with a specific OS layer, Prerequisite layer(s) and Platform layer, the App layering software will save a template in the cache that consists of the boot disk and the empty packaging disk. The next time you create an App layer that uses the same OS layer, Prerequisite layer(s) and Platform layer, the App layering software will re-use this template, thereby significantly cutting the time it takes to create this App layer in half. Please note that if you create an App layer that uses a different OS layer, Prerequisite layer(s) or Platform layers from what is saved in the template, the App layering software will create a new template and store it in cache.

The size that you need to set for your cache depends on how many different combinations of OS layers, Prerequisite layer(s), Platform layer combinations and therefore how many cached templates you will use as you layer various Apps. To estimate the space required for each template you can determine how much space a Boot disk will use by selecting the i for the OS layer you are using and observing the Maximum Layer Size value in the Version Information section. Likewise, you can obtain the Pkg disk size for an existing Application/Platform layer using the same approach. When creating new layers, you can set the Max Layer Size used by setting the Max Layer Size (GB) field in the Create Layer wizard. By looking at the size of your existing layers, and estimating how many layers you are going to be creating/editing you can determine how large to set the Cache Size in your connector configuration.

Prerequisite layers

Prerequisite layers provide a process to include existing application layers on the packaging disk when creating or adding a version to an App layer. Use prerequisite layers only if they are required. The prerequisite applications can possibly add something into the layer that is not required for deploying the current application. This behavior can cause conflict in the future. Prerequisite layers can be required for several reasons:

  • If installing the application on the current layer requires software on another application. For example, if you install an application that requires Java, and Java is located in a separate layer.
  • If the installation of the software adds the settings of an existing application. For example, when you install an Office add-in, you must install Microsoft Office first.
  • If two applications change the same registry key, and the second application must add to a key and not replace it. For example, two applications that both change login keys in Windows, such as Citrix Agent and Imprivata.


Some of these issues can also be handled by putting the two applications in the same layer rather than using prerequisite layers.

  • Prerequisite layers are not included in the app layer that you create.
  • Prerequisite layers are not included when adding a version to this app layer. When you add a version to this app layer, you must choose the Prerequisite Layers again.
  • The app layer you create and each of its Prerequisite Layers must be associated with the selected OS Layer.