Product Documentation

App layer

Jan 11, 2018

An app layer is a software image or virtual disk. The app layer includes one or more applications that you can deploy in any number of layered images. When publishing a layered image, you can combine an App layer with:

  • The OS Layer used to create the App layer
  • Other App layers
  • A Platform layer

To create an App layer, you start the Create Layer wizard, deploy a packaging machine in your environment, install one or more applications, and finalize the layer.

A packaging machine is a virtual machine on which you install the application(s) to include in the layer. The App Layering software creates the packaging machine in the location and with the credentials you supply when selecting the Hyper-V connector configuration.

In the process of creating an App layer, if you don't have the connector configuration you need, you can add a new Hyper-V connector configuration and then select it.

Before you start

Create your OS layer. You need an OS layer for your app layers. The application(s) you install must be compatible with your OS layer.


Before you create an app layer, you can also create resources that assist with installing the application. These resources are for temporary use during installation only and are not used to deliver the application.

  • Create prerequisite layers
  • Create a platform layer (Hyper-V with network file share connector). Do this step only if you create app layers on a hypervisor other than the one from which you imported your OS Layer.
  • Run Once script

If the application you install affects boot-level components, restart the packaging machine as part of finalizing the layer or version.

Does this app layer require prerequisite layers?

Prerequisite layers provide a process to include existing application layers on the packaging disk when creating or adding a version to an application 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 installation of 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 logon 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.

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.

To prepare a new app layer

  1. Select Layers > App Layers and then click Create Layer in the Action bar. The Create Layer wizard opens.

  2. In the Version Details tab:
    1. (Required) Enter a name for the New Version. This can be the software version or other identifying information.
    2. If you are adding a version to an existing layer, the Base Version field lets you choose which version to use as the starting point. The default choice is the latest version.
  3. On the OS Layer tab, select the OS Layer you want to associate with this app layer.

  4. On the Prerequisite Layers tab, click the Include Prerequisite Layers check box, and then choose the necessary app layers. Use this option if the application you are layering requires other App Layers to be present during installation.


    • 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.
  5. On the Connector tab, choose a Hyper-V Connector Configuration that specifies where in your Hyper-V environment to package the layer. If the configuration you need isn't in the list, click New, select Hyper-V, and click Add a Configuration.

  6. 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.

  7. 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.
  8. 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 Task bar displays a link to the packaging disk in Hyper-V. You use this link to deploy the packaging machine.

  9. Expand the Tasks bar at the bottom of the UI, and double-click the Packaging Disk task. The task expands to show the full task description,. This includes a link to the location in Hyper-V where the packaging machine for this layer is published.

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

Deploy a Packaging Machine in Hyper-V

A link to the packaging machine is included In the Create Layer task description. 

  1. Log into Hyper-V. This is so you can navigate to the packaging machine in the next step.
  2. In the Management Console, expand the Task Panel, and then the Packaging Disk task. The task description includes a link to the Packaging Machine.
  3. Navigate to the Packaging Machine using the link provided in the Packaging Disk task.
  4. In Hyper-V, power on the Packaging Machine.

Install the Applications

This section explains how to install your applications on the packaging machine you created in Hyper-V. The state of the app before you finalize the layer is what users experience when they access the app.

  1. Remote log into the packaging machine you created in Hyper-V. Be sure to log in by using the User account you used to create the OS in Hyper-V.

  2. Install the applications, along with any drivers, boot-level applications, or files that users need.

    If an application installation requires a system restart, restart the app manually. The packaging machine does not restart apps automatically.

  3. Make sure the packaging machine is in the state you want it to be for the user:

    • If the applications you install require any post-installation setup or application registration, complete those steps now.
    • Remove any settings, configurations, files, mapped drives, or applications that you do not want to include in the packaging machine.

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

Verify the Layer and Shut Down the Packaging Machine

After installing the application on the packaging machine, verify that the layer is ready to be finalized. To be ready for finalization, complete any required post-installation processing. For example, a restart might be required, or a Microsoft NGen process may need to complete.

To verify that all processes are complete, you can run the Shutdown For Finalize tool. The icon appears on the desktop of the packaging machine.

localized image

To use the Shutdown For Finalize tool

  1. If you are not logged on to the packaging machine, log on 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 operation that must complete before finalizing the layer, a prompt appears to finish the process. For example, to complete a Microsoft NGen operation, you can force the process to the foreground, so it finishes faster.
  4. After completion of any pending operations, double-click the Shutdown For Finalize icon again. The packaging machine shuts down.

The layer is now ready to finalize.

During shutdown for finalization

Layer integrity messages show the queued tasks that must finish before finalizing a layer.

Address the following conditions before finalizing a new layer or version:

  • A restart is pending to update drivers on the boot disk. Check and restart the packaging machine.
  • A post-installation restart is pending - check and restart the packaging machine.
  • An MSI install operation is in progress - check the packaging machine.
  • A Microsoft NGen operation is in progress in the background.


If a Microsoft NGen operation is in progress, you can expedite it, as described in the next section.

Expediting a Microsoft NGen operation

NGen is the Microsoft Native Image Generator and is part of the .NET system. NGen recompiles the .NET byte code into native images and constructs the registry entries to manage them. Windows decides when to run NGen. It runs based on what the installation is and what Windows detects in the configuration. When NGen is running, you must let it complete. An interrupted NGen operation can leave you with a non-functioning .NET assembly
 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. However, every time you check the queue status, you are creating foreground activity, which can cause the background processing to pause temporarily.

Forcing the NGen to the foreground allows you to view the progress and when the output is complete, you can finalize the layer.

To force an NGen operation to the foreground

Open a command prompt as an administrator.

Go to the Microsoft .NET Framework directory for the version currently in use. At the command prompt, type:

Change directory 复制

cd C:\Windows\Microsoft.NET\FrameworkNN\vX.X.XXXXX

Enter the NGen command to run the queued items:

Command 复制

ngen update /force

The NGen task comes to the foreground in the command-line window and lists the assemblies being compiled.


You might see several messages that the compilation failed. You can ignore the 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. If it doesn't complete, run the force command again. Do not restart to stop the task.

To check the status of an NGen operation

Open a command prompt as an administrator.

Check the status by running the following command:

Command 复制

ngen queue status

When you receive the following status, the NGen operation is complete and you can finalize the layer.

消息 复制

The .NET Runtime Optimization Service is stopped.

Finalize the Layer

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

Return to the management console.

Select Layers > App Layers and then the layer you just prepared.

Click Finalize on the Action bar.
The Finalize wizard appears.

(Optional) On the Script Path wizard tab, enter the path to the Run Once Script on a server in your network.

  • If the App Layer is elastically assigned, the Run Once Script runs the first time the app is used.
  • If the App Layer is included in a layered image, the Run Once Script runs the first time the layered image starts.

Click Finalize to finish creating the layer.

Monitor the task bar to verify that the action completes successfully and that the layer is ready to deploy.

Reference: Create App Layer Wizard values

  • Layer Name - (Required) A name that lets you know what apps the layer is used for.
  • Layer Description - (Optional) Description of the layer.
  • Version - (Required) The version you assign to the layer or the application. This value appears in the Details view of the layer. You add a new version when you update apps to this layer. The version also includes the description.
  • Version Description - (Optional) Enter a description of the version.
  • Specify the Max Layer Size - The maximum layer size in GB. Layers are thin-provisioned and grow as needed, up to the maximum size. The default size is 10 GB. Applications might require more space. If so, change the value to an appropriate size.