# App Blocks
App blocks represent a virtual hard disk (VHD) that is stored within an Amazon S3 bucket within your account that contains the application files and binaries necessary to launch the applications your users will use. App blocks also include the setup script that informs the operating system how to handle the VHD file.
App blocks support two different types of packaging:
+ Custom - Choose this option to create your application package (VHD) manually. For more information, see [Custom App Blocks](custom-app-blocks.md).
+ WorkSpaces Applications - Choose this recommended option to create your application package using app block builder. For more information, see [WorkSpaces Applications App Blocks](appstream-app-blocks.md).
**Topics**
+ [Custom App Blocks](custom-app-blocks.md)
+ [WorkSpaces Applications App Blocks](appstream-app-blocks.md)
+ [Unsupported Applications](app-blocks-unsupported.md)
# Custom App Blocks
Elastic fleet streaming instances utilize applications that are installed on virtual hard disk (VHD) files stored within an Amazon S3 bucket in your account. App blocks with custom packaging gives you the flexibility to create your own VHD file, and upload it to an Amazon S3 bucket within your account.
**Topics**
+ [Create the VHD](create-vhd.md)
+ [Create the Setup Script for the VHD in Amazon WorkSpaces Applications](create-setup-script.md)
+ [Create a Custom App Block](create-app-block.md)
+ [Update the App Block, VHD, and Setup Script](update-app-block.md)
# Create the VHD
A VHD is a single file that when mounted to the operating system is treated like a hard disk. The VHD can be mounted as a drive letter, to a folder path, or both. When the VHD is mounted, you can treat it as you would any other hard disk, including installing your application or copying files to it that your user will need.
To create the app block, you will need to create the VHD, install your applications to it, then detach it. Once detached you can test your VHD on another PC, an EC2 instance, or an WorkSpaces Applications image builder to validate the applications work as expected. Once completed, upload to an Amazon S3 bucket in your account and create the app block.
**Note**
This page describes using a VHD to deliver your application; however, the WorkSpaces Applications streaming instance will download any object from Amazon S3. The object you store in Amazon S3 can also be a zip file, application installer, or the application executable itself. You can use the setup script to configure it correctly on the streaming instance before a user launches their application.
The WorkSpaces Applications streaming instance waits up to 120 seconds for the VHD to complete downloading before the setup script runs. If the VHD does not complete downloading within this duration, the download stops, and the setup script will not run.
We recommend a maximum size of 1.5 gigabyte for the VHD. You might be able to reduce the size of the VHD by compressing. You must use the setup script to decompress it before mounting it, because the file needs to be fully downloaded from Amazon S3 before it can be mounted and the application is launched. Larger VHDs increase the time it takes for the application to launch and the streaming session to begin.
**To create a VHD for Microsoft Windows**
1. From a Windows PC or Windows Amazon Elastic Compute Cloud (Amazon EC2) instance, open a command prompt with administrative privileges.
1. Launch the Microsoft **diskpart** utility by entering the following command:
**diskpart**
1. Create the unformatted and uninitialized VHD file by entering the following command, where ** is the size of the VHD file, in MB:
**create vdisk file=C:\$1path\$1to\$1new\$1file.vhdx maximum=** type=expandable **
1. Select the newly created VHD by entering the following command:
**select vdisk file=C:\$1path\$1to\$1new\$1file.vhdx**
1. Attach the newly created VHD by entering the following command:
**attach vdisk**
1. Initialize the newly created VHD by entering the following command:
**convert mbr**
1. Create the primary partition spanning the entire VHD by entering the following command:
**create partition primary**
1. Format the newly created partition by entering the following command:
**format fs=ntfs quick**
1. You can mount your newly created VHD to an unused drive letter, a folder path on the root volume, or both.
To mount a drive letter, enter: **assign letter=****
To mount a folder, enter: **assign mount=*C:\$1path\$1to\$1empty\$1folder\$1to\$1mount\$1***
**Note**
To mount to a folder path, the folder must already exist and must be empty.
1. You can now install your application to the VHD, using either the drive letter or the folder mount path chosen in step 9.
After you finish installing your application(s) to the VHD, you need to detach it before you can safely upload it to an Amazon S3 bucket.
**To detach a VHD for Microsoft Windows**
1. Launch the Microsoft diskpart utility by entering the following command:
**diskpart**
1. Select the VHD by entering the following command:
**select vdisk file=*C:\$1path\$1to\$1new\$1file.vhdx***
1. Detach the VHD by entering the following command:
**detach vdisk**
1. The VHD has now been detached, and can be tested on another Windows PC, Amazon EC2 instance, or an WorkSpaces Applications image builder.
**To create a VHD for Linux**
1. Open a terminal:
+ For Ubuntu Pro 24.04 LTS: Use EC2 instance, or WorkSpaces powered by Ubuntu Pro
1. Create the unformatted and uninitialized VHD file:
**dd if=/dev/zero of=** bs=** count=1**
1. Add a file system to the created VHD by entering the following command:
**sudo mkfs -t ext4 ****
**Note**
You might see a message stating that the file is not a block special device. You can select to proceed anyway.
1. Create an empty folder to use for the mount point by entering the following command:
**sudo mkdir */path/to/mount/point***
1. Mount the newly created VHD to a file system path by running the following command:
**sudo mount -t auto -o loop ** */path/to/mount/point***
1. You can now install your application to the VHD using the folder mount path chosen in step 4.
**Note**
The default permissions for files and folders created on the VHD can prevent non-administrator users from launching applications or reading files. Validate the permissions and change them, if necessary.
After you finish installing your application(s) to the VHD, you need to detach it before you can safely upload it to an Amazon S3 bucket.
**To detach a VHD for Linux**
1. Open a terminal session, and enter the following command:
**sudo umount */path/to/mount/point***
1. The VHD has now been detached, and can be tested on another Ubuntu Pro 24.04 LTS Amazon EC2 instance or Ubuntu WorkSpaces Personal.
# Create the Setup Script for the VHD in Amazon WorkSpaces Applications
WorkSpaces Applications uses a setup script that you provide to mount the VHD before the application launches. You can also use the setup script to complete other tasks required to make your application work. For example, you can configure registry keys, register DLLs, manage pre-requisites, or modify the user profile from the setup script. WorkSpaces Applications provides script examples that you can use to mount your VHD. You will need to modify these scripts for your VHD and application needs.
**Note**
Setup scripts aren't required for app blocks with WorkSpaces Applications packaging. However, you can provide optional post-setup scripts to customize application installation.
Use the following links to download the example scripts:
+ [Ubuntu Pro 24.04 LTS bash script](samples/Linux-mount-vhd-script2.zip)
+ [Microsoft Windows Powershell script](samples/Windows-mount-vhd-script3.zip)
**Note**
WorkSpaces Applications and the Microsoft Windows operating system reserve drive letters A through E. Don't mount VHDs or network shares to these drive letters.
WorkSpaces Applications downloads the setup script and VHD to a directory on the fleet streaming instance, then runs the setup script. The setup script runs on the operating system with full administrator rights. The setup script runs in the `SYSTEM` context on Microsoft Windows, and as the `root` user on Ubuntu Pro 24.04 LTS.
File system location for the VHD and setup script:
+ Ubuntu Pro 24.04 LTS:
`/opt/appstream/AppBlocks/appblock-name/`
**`appblock-name` **
The name of the app block that the VHD and setup script correspond to.
+ Microsoft Windows:
`C:\AppStream\AppBlocks\appblock-name\`
**`appblock-name` **
The name of the app block that the VHD and setup script correspond to.
WorkSpaces Applications maintains the file name as they are on the object. For example, if your app block is named `MyApps`, with a VHD named `apps.vhd` and setup script named `mount-apps.ps1`, then the full path on a Windows streaming instance is:
+ VHD
`C:\AppStream\AppBlocks\MyApps\apps.vhd`
+ Setup script
`C:\AppStream\AppBlocks\MyApps\mount-apps.ps1`
WorkSpaces Applications captures the standard error and standard output from your setup script when it runs on a fleet streaming instance and uploads the output to an Amazon S3 bucket within your account. You can use these logs to identify and resolve issues you may have with your setup script. The buckets are named in a specific format as follows:
```
appstream-logs-region-code-account-id-without-hyphens-random-identifier
```
**`region-code` **
This is the AWS Region code in which the elastic fleet is created within.
**`account-id-without-hyphens` **
Your AWS account identifier. The random ID ensures that there is no conflict with other buckets in that Region. The first part of the bucket name, appstream-logs, does not change across accounts or Regions.
For example, if you create an elastic fleet in the US West (Oregon) Region (us-west-2) on account number 123456789012, WorkSpaces Applications creates an Amazon S3 bucket within your account in that Region with the name shown. Only an administrator with sufficient permissions can delete this bucket.
```
appstream-logs-us-west-2-1234567890123-abcdefg
```
The path for the folder where the log files are stored in the S3 bucket in your account uses the following structure:
```
bucket-name/fleet-name/instance-id/appblock-name/
```
**`bucket-name` **
The name of the Amazon S3 bucket in which the setup script logs are stored. The name format is described earlier in this section.
**`Instance-id` **
The unique identifier for the streaming instance that the setup script ran on
**`appblock-name` **
The name of the appblock that the setup script corresponds to.
The following example folder structure applies to a streaming session started from `test-fleet`. The session is from an AWS account ID of 123456789012, and appblock name is testappblock in the US West (Oregon) Region (us-west-2):
`appstream-logs-us-west-2-1234567890123-abcdefg/test-fleet/i-084427ab4a1cff7f5/testappblock/`
This example folder structure contains one log file for the standard output, and one log file for the standard error.
**Topics**
+ [App block setup script execution in Amazon WorkSpaces Applications](script-execution.md)
# App block setup script execution in Amazon WorkSpaces Applications
The following diagrams indicate where in the process the setup script runs. The run order is dependent upon whether Application Settings Persistence is enabled on the stack associated with the elastic fleet.
**Note**
WorkSpaces Applications uses your VPC details to download the VHD and setup script from the Amazon S3 bucket. Your VPC must provide access to the Amazon S3 bucket. For more information, see [Using Amazon S3 VPC Endpoints for WorkSpaces Applications Features](managing-network-vpce-iam-policy.md).
Application Settings Persistence is enabled:
![\[Application Settings Persistence is enabled.\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/images/app-settings-enabled.png)
Application Settings Persistence is disabled:
![\[Application Settings Persistence is disabled.\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/images/app-settings-disabled.png)
# Create a Custom App Block
You can use the WorkSpaces Applications console to create the app block resource once you have your VHD and setup script created and uploaded to an S3 bucket in your AWS account. To learn more about storing the VHD and setup script in an Amazon S3 bucket, see [Store Application Icon, Setup Script, Session Script, and VHD in an S3 Bucket](store-s3-bucket.md).
**Note**
You must have IAM permissions to perform the `S3:GetObject` action on the VHD and setup script objects in the Amazon S3 bucket to create the app block resource.
**To create the app block resource**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. From the left-hand navigation menu, choose **Applications**, **App block**, and **Create app block**.
1. For app block packaging, select **Custom**.
1. For **App block details**, type a unique name identifier for the app block. Optionally, you can also specify the following:
+ **Display name** – A friendly name for the app block.
+ **Description** – A description for the app block.
1. For **Virtual hard disk object in S3** under **Script settings**, either enter the S3 URI that represents the VHD object, or choose **Browse S3** to navigate to your S3 buckets and find the VHD object.
1. For **Setup script object in S3** under **Script settings**, either enter the S3 URI that represents the setup script object, or choose **Browse S3** to navigate to your S3 buckets and find the setup script object.
1. For **Setup script executable** under **Script settings**, enter the executable necessary for your setup script.
**Note**
If your setup script can execute directly, enter the filename of the setup script. If your setup script relies on another executable (for example, Microsoft PowerShell) to execute, enter the path to that executable.
Path to Microsoft PowerShell on Microsoft Windows:
`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`
1. Optionally, for **Setup script executable arguments** under **Script settings**, enter in the arguments that need to be provided to the setup script executable to execute your setup script.
**Note**
If you are using a Microsoft PowerShell script, you must specify the "-File" parameter with the name of your setup script as an executable argument. Additionally, ensure that the Execution Policy allows your script to be run. To learn more, see [about\$1Execution\$1Policies](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.2) and [What is PowerShell?](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2).
1. For **Execution duration in seconds** under **Script settings**, enter the timeout duration for your setup script.
**Note**
The execution duration in seconds is how long WorkSpaces Applications waits for the setup script to run before continuing. If your setup script doesn’t complete within this duration, an error is displayed to your user and the application will attempt to launch. The setup script is terminated after the execution duration has elapsed.
1. (Optional) For **Tags**, create tags for the app block resource
1. Review the information that you entered, and choose **Create**.
1. If your app block was created successfully, you see a success message at the top of the console. If an error occurred, you see a descriptive error message and will need to try creating the app block again.
# Update the App Block, VHD, and Setup Script
App block resources are immutable and do not allow you to change them once created. If you need to make backwards compatible updates to the VHD or setup script, it is recommended that you upload a new version of the file to the Amazon S3 bucket, overwriting the current version. New Elastic fleet streaming sessions will download the latest version of the objects, and use them.
If you need to make backwards incompatible updates to the VHD or setup script, it is recommended that you upload them as new objects to the Amazon S3 bucket, and create a new app block and application resource. You can then manage the deployment to your users as part of a change window or other outage.
# WorkSpaces Applications App Blocks
Elastic fleet streaming instances utilize applications that are installed on virtual hard disk (VHD) files stored within an Amazon S3 bucket in your account. When it comes to app blocks with custom packaging, you have the flexibility to create your own VHD file and upload it to an Amazon S3 bucket within your account. Alternatively, for app blocks with WorkSpaces Applications packaging, you can take advantage of the app block builder, which handles the packaging of your applications, creates a VHD file, and uploads it to your Amazon S3 bucket.
By using the WorkSpaces Applications packaged app block, you not only eliminate the need for manual steps in building a VHD file, but also remove the requirement for a setup script. It expands application compatibility with elastic fleets, as well as reduces manual administrative steps required to create an app block. WorkSpaces Applications handles the setup of app blocks with WorkSpaces Applications packaging automatically without the need of any setup scripts. However, you can still provide optional post-setup scripts to customize the installation for your needs.
**Topics**
+ [Overview](appstream-app-blocks-overview.md)
+ [Unsupported Applications](appstream-app-blocks-unsupported.md)
+ [Create an WorkSpaces Applications App Block](appstream-app-blocks-create.md)
+ [Activate an App Block](appstream-app-blocks-activate.md)
+ [Create an App Block with an Existing App Package](appstream-app-blocks-create-VHD.md)
+ [Test an App Block](appstream-app-blocks-test.md)
+ [Associate an App Block in Amazon WorkSpaces Applications](appstream-app-blocks-associate.md)
+ [Disassociate an App Block in Amazon WorkSpaces Applications](appstream-app-blocks-disassociate.md)
# Overview
To create an app block with WorkSpaces Applications packaging, you need to initiate a streaming session with an app block builder. After the session is launched, you can download your application installers and enable the recording options. From that point onwards, WorkSpaces Applications records the file system and registry changes made on the app block builder using Application Redirection technology.
Application Redirection uses Windows filter driver framework to intercept and redirect file-system and registry changes. This redirection is seamless to the application being installed. The application will continue to interact with the original file locations on the C: drive. For example, if an installer for "TestApplication" is run on a machine with App Redirection set up, it will be installed by default to C:\$1Program Files\$1TestApplication. However, behind the scenes, all files and folders will be redirected to a mounted virtual hard disk (VHD), and a link will be created from the original file location to the actual file location. On the machine, TestApplication will still appear to be installed at C:\$1Program Files\$1TestApplication.
After all the installation changes are recorded, the VHD file is uploaded to an Amazon S3 bucket in your account.
When a user requests a session using an Elastic fleet, WorkSpaces Applications downloads the VHD file, sets up the application, runs the post-installation setup scripts (optional), and starts the application streaming.
**Note**
Application Redirection technology does not record any file system changes under %USERPROFILE%, except new directories created under %APPDATA% and %LOCALAPPDATA% directories.
Application Redirection technology does not record any registry changes under the current user, HKEY\$1CURRENT\$1USER (HKCU).
# Unsupported Applications
Applications might encounter failures when installing or running in the following scenarios:
+ **Applications with location-based checks during installation**: If an application’s installation process verifies the actual location of the installed files, it might result in a failure. Because WorkSpaces Applications redirects the files to the app block VHD, only links to the actual files are maintained at the original location.
If you are uncertain whether your application falls into any of these categories, you can use WorkSpaces Applications packaging to create an app block. This process involves installing your application(s) on an app block builder instance. In the event that your application(s) fail to install on the app block builder instance, you can take the following actions:
+ Check the logs. The error log file for your app block builder instance can be found at C:\$1AppStream\$1AppBlocks\$1errorLog. This log records all installation failures, including RegKeys/File operation processing. If you see any of the following logs in the errorLog, it indicates that the packaging of your application is currently unsupported by the WorkSpaces Applications app block builder:
+ "Unable to create symbolic link"
+ "Service doesn't support file renaming"
If there is no errorLog file, or if this file is empty, then check your application installation logs to identify the reason for failures.
+ Report a problem. Select the **Report a problem** button, which is available on the application builder assistant in the app block builder. Selecting this option will gather all the WorkSpaces Applications logs from your app block builder instance, and submit them to the WorkSpaces Applications team for assistance.
+ Create an app block with custom packaging: If you are unable to package your applications using the app block builder, you can try to create an app block using custom packaging methods. For more information, see [Custom App Blocks](custom-app-blocks.md).
+ If you need more help, contact AWS Support. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/).
It is important to consider these potential limitations, and plan accordingly when using WorkSpaces Applications packaging for your applications.
# Create an WorkSpaces Applications App Block
Follow these steps to create an app block with the WorkSpaces Applications packaging type.
## Step 1: Configure the app block
**To configure the app block**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. From the left-hand navigation menu, choose **Applications Manager**, **App blocks**, and **Create app block**.
1. For app block packaging, select **WorkSpaces Applications**.
1. For **App block details**, type a unique name identifier for the app block. Optionally, you can also specify the following:
+ **Name** – A unique name for the app block.
+ **Display name** (optional) – A friendly name for the app block.
+ **Description** (optional) – A description for the app block.
1. (Optional) An app block with WorkSpaces Applications packaging doesn't need a setup script. You can optionally provide post-installation steps the following **Advanced Options**:
+ For **Post setup script object in S3**, either enter the Amazon S3 URI that represents the post setup script object, or choose **Browse S3** to navigate to your Amazon S3 buckets and find the setup script object.
+ For **Post setup script executable**, enter the executable needed for your post setup script.
**Note**
If your setup script can execute directly, enter the filename of the setup script. If your setup script relies on another executable (for example, Microsoft PowerShell) to execute, enter the path to that executable.
Path to Microsoft PowerShell on Microsoft Windows:
`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`
Optionally, for **Setup script executable arguments** under **Script settings**, enter in the arguments that need to be provided to the setup script executable to execute your setup script.
**Note**
If you are using a Microsoft PowerShell script, you must specify the "-File" parameter with the name of your setup script as an executable argument. Additionally, ensure that the Execution Policy allows your script to be run. To learn more, see [about\$1Execution\$1Policies](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.2) and [What is PowerShell?](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2).
For **Execution duration in seconds** under **Script settings**, enter the timeout duration for your setup script.
**Note**
The execution duration in seconds is how long WorkSpaces Applications waits for the setup script to run before continuing. If your setup script doesn’t complete within this duration, an error is displayed to your user and the application will attempt to launch. The setup script is terminated after the execution duration has elapsed.
1. Under **Import Settings**, choose **Create new app block application file**. For **S3 Location** under **Import settings**, either enter the Amazon S3 URI that represents the bucket, or choose **Browse S3** to navigate to your Amazon S3 buckets and select an appropriate bucket. The list of Amazon S3 buckets is global and lists all the buckets across all regions. Make sure you select the bucket in the region where you want to create your app block. For more information about setting bucket permissions, see [Store Application Icon, Setup Script, Session Script, and VHD in an S3 Bucket](store-s3-bucket.md).
1. Select an app block builder. Only app block builders that are not associated with other app blocks are available. If the list is empty, either create a new app block builder, or disassociate the existing ones to use. App block builder is a reusable resource that you can use to create your application package.
**Note**
If you do not select an app block builder here, you can still create your app block in the **Inactive** state, and activate your app block later. For more information, see [Activate an App Block](appstream-app-blocks-activate.md).
1. (Optional) For **Tags**, create tags for the app block resource.
1. Choose **Next**.
1. Review the information that you entered, and choose one of the following options:
+ Choose **Create app block** if you didn't select an app block builder in step 7.
+ Choose **Launch app block builder** if you chose an app block builder in step 7. Then continue to Step 2 to create your application package using the app block builder streaming session.
At this point, your app block resource is created, but it is **Inactive** and can't be used for Elastic fleets.
## Step 2: Create the Application Package
Use the app block builder streaming instance to package your applications and activate your app block. The app block created using app block builder will have WorkSpaces Applications packaging, and the application package will be uploaded onto the Amazon S3 bucket in your AWS account.
**To create the application package**
1. After your streaming session is on, the application builder assistant automatically starts. If it doesn’t start, start it manually using the desktop icon.
1. The initial screen provides instructions for the application packaging process.
1. Bring your application installer onto your app block builder streaming session by using one of the following options:
+ Download the application installers from the web.
+ Use your streaming session file interface.
+ Download the application installer from another AWS service using a machine role.
1. After you have all the required application installers, stop all the other apps running on the instance and choose **Start recording**. The app block builder starts recording system changes, and the screen says **Recording in progress**.
1. Start installing your applications one by one.
1. When you are done with application installation, choose **Stop recording**, and the system will stop recording changes. If you want to make any more changes to your application package, such as add more applications or remove an already installed application, choose **Start recording**, and make sure the system is in **Recording in progress** mode.
**Note**
If your application installation fails, choose **Report a problem** to collect WorkSpaces Applications related logs from the instance, and report the problem to the WorkSpaces Applications team. When you are done, end your app block builder streaming session. You can try to restart the process creating an app block by using a new app block builder instance. If the problem persists, then try to create your app block using custom packaging.
1. When you are done installing all the applications, choose **Stop recording**. You can test your application, by using the Start Menu or browsing the application using File Explorer.
1. Choose **Next** to review your app block details.
**Note**
The recommended size of an application package (VHD) file for an Elastic fleet is less than 1.5 GB. If your VHD file size is bigger than 1.5 GB, try reducing the number of applications packaged within one app block.
Application package (VHD) file size will not shrink if you uninstall an application. Restart the application packaging process using a new app block streaming session, and install fewer applications.
1. Choose **Finish app block creation and disconnect** to create the application package and upload it to the Amazon S3 bucket. If you are successful, the streaming session will automatically disconnect, and the app block will be in an **Active** state.
**Note**
If your application installation fails, choose **Report a problem** to collect WorkSpaces Applications related logs from the instance, and report the problem to the WorkSpaces Applications team. When you are done, end your app block builder streaming session. You can try to restart the process creating an app block by using a new app block builder instance. If the problem persists, then try to create your app block using custom packaging.
# Activate an App Block
If an app block with WorkSpaces Applications packaging was created, but the application package (VHD) was not attached to it, then the app block will be in an inactive state, and it can't be used to associate applications with Elastic fleets. To activate an app block, an application package (VHD) must be associated with the app block.
**To create the application package**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. From the left-hand navigation menu, choose **Applications Manager**, **App blocks**.
1. Select an **Inactive** app block that you want to activate, and choose **Activate** from the **Actions** menu.
1. Select an app block builder, and choose **Launch app block builder**.
+ If the list is empty, then you either don’t have an app block builder, or all of your app block builders are associated with other app blocks. Either create a new app block builder, or disassociate an existing app block builder and test it.
+ If the app block builder is already associated with an app block, then you can continue using it for activating the app block.
+ If the selected app block builder was not associated with an app block builder, then it will be associated with the one you select, and the streaming session will launch. The app block builder remains associated with this app block after the session ends.
1. After the app block builder streaming session starts, follow the steps in [Step 2: Create the Application Package](appstream-app-blocks-create.md#appstream-app-blocks-create-step2) to create your application package (VHD) and activate the app block.
# Create an App Block with an Existing App Package
You can use your existing application package (VHD) with WorkSpaces Applications packaging to create WorkSpaces Applications app blocks. To do this, copy your application package (VHD) file from the source Amazon S3 bucket to another destination Amazon S3 bucket. The destination bucket can be in a different region.
**To create an app block with existing app package**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. From the left-hand navigation menu, choose **Applications Manager**, **App blocks**, and **Create app block**.
1. For app block packaging, select **WorkSpaces Applications**.
1. For **App block details**, type a unique name identifier for the app block. Optionally, you can also specify the following:
+ **Name** – A unique name for the app block.
+ **Display name** (optional) – A friendly name for the app block.
+ **Description** (optional) – A description for the app block.
1. (Optional) An app block with WorkSpaces Applications packaging doesn't need a setup script. You can optionally provide post-installation steps the following **Advanced Options**:
+ For **Post setup script object in S3**, either enter the Amazon S3 URI that represents the post setup script object, or choose **Browse S3** to navigate to your Amazon S3 buckets and find the setup script object.
+ For **Post setup script executable**, enter the executable needed for your post setup script.
**Note**
If your post setup script can execute directly, enter the filename of the post setup script. If your post setup script relies on another executable (for example, Microsoft PowerShell) to execute, enter the path to that executable.
Path to Microsoft PowerShell on Microsoft Windows:
`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`
Optionally, for **Post setup script executable arguments**, enter in the arguments that need to be provided to the setup script executable to execute your setup script.
**Note**
If you are using a Microsoft PowerShell script, you must specify the "-File" parameter with the name of your post setup script as an executable argument. Additionally, ensure that the Execution Policy allows your script to be run. To learn more, see [about\$1Execution\$1Policies](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.2) and [What is PowerShell?](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2).
For **Execution duration in seconds** under **Script settings**, enter the timeout duration for your setup script.
**Note**
The execution duration in seconds is how long WorkSpaces Applications waits for the post setup script to run before continuing. If your post setup script doesn’t complete within this duration, an error is displayed to your user and the application will attempt to launch. The setup script is terminated after the execution duration has elapsed.
1. Choose **Use existing app block application file** under **Import settings**. For **S3 Location**, you can enter the Amazon S3 URI for the object in an Amazon S3 bucket that represents the application package (VHD), Or, choose **Browse S3** to navigate to your Amazon S3 buckets and select the object in an Amazon S3 bucket. The list of Amazon S3 buckets is global and lists all the buckets across all regions. Make sure you select the bucket in the region where you want to create your app block.
1. Choose **Next**.
1. Review the information that you entered, and choose **Create app block**.
At this point your app block resource is created and in the **Active** state.
# Test an App Block
You can use an app block builder to test your app block and verify your application functionalities. You don’t need to launch an Elastic fleet for this option. You can also create multiple app block builders with different instance types or sizes, and test the performance of your application with different compute options.
**Note**
The test app block option is supported only for app blocks with WorkSpaces Applications packaging.
**To test an app block**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. From the left-hand navigation menu, choose **Applications Manager**, **App blocks**.
1. Select an app block that you want to test, and choose **Test** from the **Actions** menu.
1. Select an app block builder, and choose **Launch and test app block**.
+ If the list is empty, then you either don’t have an app block builder, or all of your app block builders are associated with other app blocks. Either create a new app block builder, or disassociate an existing app block builder and test it.
+ If the app block builder is already associated with an app block, then you can continue using it for activating the app block.
+ If the selected app block builder was not associated with an app block builder, then it will be associated with the one you select, and the streaming session will launch. The app block builder remains associated with this app block after the session ends.
1. App block builder launches in a separate browser window in a Desktop streaming mode. The service downloads the app block from the Amazon S3 bucket and installs it on the app block builder instance.
1. Your applications can now be streamed and tested. You can open your application by either browsing it in File Explorer or using the Start menu.
1. When you are done testing, end the streaming session.
# Associate an App Block in Amazon WorkSpaces Applications
In order to create, test, or activate your app block with WorkSpaces Applications packaging, you need to associate it with an app block builder. One app block builder can only be associated with only one app block, and vice versa.
**Note**
Associating and disassociating an app block is only supported for app blocks with WorkSpaces Applications packaging.
**Associate an app block with app block builder in Amazon WorkSpaces Applications**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. From the left-hand navigation menu, choose **Applications Manager**, **App blocks**.
1. Select an app block, and choose **Associate** from the **Actions** menu.
1. Select an app block builder, and choose **Associate app block builder**.
If the list is empty, then you either don’t have an app block builder, or all of your app block builders are associated with other app blocks. Either create a new app block builder, or disassociate an existing app block builder and then associate.
# Disassociate an App Block in Amazon WorkSpaces Applications
If all your app block builders are associated with other app blocks, and you want to test, create, or activate another app block, then you can either create a new app block builder, or disassociate an existing app block builder from the app block and use it with the new app block.
**Note**
Associating and disassociating an app block is only supported for app blocks with WorkSpaces Applications packaging.
Disassociation is allowed only if an app block builder is in the **STOPPED** state.
**Disassociate an app block from an app block builder**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. From the left-hand navigation menu, choose **Applications Manager**, **App blocks**.
1. Select an app block, and choose **Disassociate** from the **Actions** menu.
1. Select an already associated app block builder, and choose **Disassociate app block builder**.
# Unsupported Applications
Applications might encounter failures when installing or running in the following scenarios:
+ **Applications requiring reboots after installation**: If an application needs to perform additional changes or configurations after installation that require a reboot, it might fail. Currently, app block builder does not support restart, which can prevent the application from completing its required post-installation steps.
+ **Applications relying on user-specific details**: Applications that are intended to be installed only for the currently logged-in user on app block builder, or that rely on the logged-in user details on app block builder, such as security identifiers (SIDs) during installation, might not function correctly on Elastic fleets. This is due to the logged-in user changes within the elastic fleet environment. Additionally, application redirection does not record all directories under %USERPROFILE%. However, you have the option to configure post setup scripts to dynamically change your application configuration based on environment.
+ **Applications relying on machine-specific details**: Applications that rely on machine-specific details on app block builder during installation, such as network adaptor GUID, might encounter issues on Eastic fleets. This is because the machine details, including network adaptor GUIDs, can change within the elastic fleet environment. To address this, you can configure the post setup scripts to handle the configuration of those machine-specific details.
If you are uncertain whether your application falls into any of these categories, you can use WorkSpaces Applications packaging to create an app block. This process involves installing your application(s) on an app block builder instance. In the event that your application(s) fail to install on the app block builder instance, you can take the following actions:
+ Check the logs. The error log file for your app block builder instance can be found at C:\$1AppStream\$1AppBlocks\$1errorLog. This log records all installation failures, including registry keys and file operation processing. If you see any of the following logs in the errorLog, it indicates that the packaging of your application is currently unsupported by the WorkSpaces Applications app block builder:
+ "Unable to create symbolic link"
+ "Service doesn't support file renaming"
If there is no errorLog file, or if this file is empty, then check your application installation logs to identify the reason for failures.
+ Report a problem. Select the **Report a problem** button, which is available on the application builder assistant in the app block builder. Selecting this option will gather all the WorkSpaces Applications logs from your app block builder instance, and submit them to the WorkSpaces Applications team.
+ Create an app block with custom packaging: If you are unable to package your applications using the app block builder, you can try to create an app block using custom packaging methods. For more information, see [Custom App Blocks](custom-app-blocks.md).
+ If you need more help, contact AWS Support. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/).
It is important to consider these potential limitations, and plan accordingly when using WorkSpaces Applications packaging for your applications.