Skip to content

Commit

Permalink
Android AssetPack Implementation
Browse files Browse the repository at this point in the history 
Google Android began supporting splitting up the app package into multiple
packs with the introduction of the `aab` package format. This format allows
the developer to split the app up into multiple `packs`. Each `pack` can be
downloaded to the device either at install time or on demand. This allows
application developers to save space and install time by only installing
the required parts of the app initially. Then installing other `packs`
as required.

There are two types of `pack`. The first is a `Feature` pack, this type
of pack contains code and other resources. Code in these types of `pack`
can be launched via the `StartActivity` API call. At this time due to
various constraints .NET Android cannot support `Feature` packs.

The second type of `pack` is the `Asset` pack. This type of pack ONLY
contains `AndroidAsset` items. It CANNOT contain any code or other
resources. This type of `feature` pack can be installed at install-time,
fast-follow or ondemand. It is most useful for apps which contain allot
of `Assets`, such as Games or Multi Media applications.
See the [documentation](https://developer.android.com/guide/playcore/asset-delivery) for details on how this all works.
.NET Android does not have any official support for this type of pack.
However a hack is available via the excellent @infinitespace-studios on
[github](https://github.com/infinitespace-studios/MauiAndroidAssetPackExample).
This hack allows developers to place additional assets in a special
`NoTargets` project. This project is built just after the final `aab` is
produced. It builds a zip file which is then added to the `@(Modules)`
ItemGroup in the main application. This zip is then included into the
final app as an additional feature.

We want to provide our users the ability to use `Asset` packs without
having to implement the hack provided by @infinitespace-studios. Using
a separate project like in the hack is one way to go. It does have some
issues though.

1. It is a `special` type of project. It requires a `global.json` which imports the
   `NoTargets` sdk.
2. There is no IDE support for building this type of project.

Having the user go through a number of hoops to implement this for
.NET Android or .net Maui is not ideal. We need a simpler method.

The new idea is to make use of additional metadata on `AndroidAsset`
Items to allow the build system to split up the assets into packs
automatically. So it is proposed that we implement support for something
like this

```xml
<ItemGroup>
   <AndroidAsset Include="Asset/data.xml" />
   <AndroidAsset Include="Asset/movie.mp4" AssetPack="assets1" />
   <AndroidAsset Include="Asset/movie2.mp4" AssetPack="assets1" />
</ItemGroup>
```

In this case the additional `AssetPack` attribute is used to tell the
build system which pack to place this asset in. Since auto import of items
is common now we need a way for a user to add this additional attribute
to auto included items. Fortunately we are able to use the following.

```xml
<ItemGroup>
   <AndroidAsset Update="Asset/movie.mp4" AssetPack="assets1" />
   <AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
   <AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>
```

This code uses the `Update` attribute to tell MSBuild that we are going
to update a specific item. Note in the sample we do NOT need to include
an `Update` for the `data.xml`, since this is auto imported it will still
end up in the main feature in the aab.

Additional attributes can be used to control what type of asset pack is
produced. The only extra one supported at this time is `DeliveryType`,
this can have a value of `InstallTime`, `FastFollow` or `OnDemand`.
Additional attributes do not need to be included on ALL items. Any one
will do, only the `AssetPack` attribute will be needed.
See Google's [documentation](https://developer.android.com/guide/playcore/asset-delivery#asset-updates) for details on what each item does.

```xml
<ItemGroup>
   <AndroidAsset Update="Asset/movie.mp4" AssetPack="assets1" DeliveryType="InstallTime" />
   <AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
   <AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>
```

If the `AssetPack` attribute is not present, the default behavior will
be to include the asset in the main application package.

There are a few changes we need to make in order to support this feature.
One of the issues we will hit is the build times when dealing with large assets.
Current the assets which are to be included in the `aab` are COPIED
into the `$(IntermediateOutputPath)assets` directory. This folder is
then passed to `aapt2` for the build process.

The new system adds a new directory `$(IntermediateOutputPath)assetpacks`.
This directory would contain a subdirectory for each `pack` that the
user wants to include.

```dotnetcli
assetpacks/
    assets1/
        assets/
            movie1.mp4
    feature2/
        assets/
             movie2.mp4
```

All the building of the `pack` zip file would take place in these subfolders.
The name of the pack will be based on the main "packagename" with the asset pack
name appended to the end. e.g `com.microsoft.assetpacksample.assets1`.

During the build process we identify ALL the `AndroidAsset` items which
define an `AssetPack` attribute. These files are then copied to the
new `$(IntermediateOutputPath)assetpacks` directory rather than the
existing `$(IntermediateOutputPath)assets` directory. This allows us to
continue to support the normal `AndroidAsset` behavior while adding the
new system.

Once we have collected and copied all the assets we then use the new
`GetAssetPacks` Task to figure out which asset packs we need to create.
We then call the `CreateDynamicFeatureManifest` to create a required
`AndroidManifest.xml` file for the asset pack. This file will end
up in the same `$(IntermediateOutputPath)assetpacks` directory.
We call this Task `CreateDynamicFeatureManifest` because it can be used
to create any feature pack if and when we get to implement full feature
packs.

```dotnetcli
assetpacks/
    assets1/
        AndroidManifest.xml
        assets/
            movie1.mp4
    feature2/
        AndroidManifest.xml
        assets/
             movie2.mp4
```

We can then call `aapt2` to build these packs into `.zip` files. A new
task `Aapt2LinkAssetPack` takes care of this. This is a special version
of `Aapt2Link` which implements linking for asset packs only.
It also takes care of a few problems which `aapt2` introduces. For some
reason the zip file that is created has the `AndroidManifest.xml` file
in the wrong place. It creates it in the root of the zip file, but the
`bundletool` expects it to be in a `manifest` directory.
`bundletool` will error out if its not in the right place.
So `Aapt2LinkAssetPack` takes care of this for us. It also removes a
`resources.pb` which gets added. Again, `bundletool` will error if this
file is in the zip file.

Once the zip files have been created they are then added to the
`AndroidAppBundleModules` ItemGroup. This will ensure that when the
final `.aab` file is generated they are included as asset packs.
  • Loading branch information
@dellis1972
dellis1972 committed Feb 21, 2024
1 parent 39ce2f9 commit 7d5ec40
Show file tree
Hide file tree
Showing 19 changed files with 956 additions and 61 deletions.
176 changes: 176 additions & 0 deletions Documentation/guides/AndroidAssetPacks.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
# Android Asset Packs

Google Android began supporting splitting up the app package into multiple
packs with the introduction of the `aab` package format. This format allows
the developer to split the app up into multiple `packs`. Each `pack` can be
downloaded to the device either at install time or on demand. This allows
application developers to save space and install time by only installing
the required parts of the app initially. Then installing other `packs`
as required.

There are two types of `pack`. The first is a `Feature` pack, this type
of pack contains code and other resources. Code in these types of `pack`
can be launched via the `StartActivity` API call. At this time due to
various constraints .NET Android cannot support `Feature` packs.

The second type of `pack` is the `Asset` pack. This type of pack ONLY
contains `AndroidAsset` items. It CANNOT contain any code or other
resources. This type of `feature` pack can be installed at install-time,
fast-follow or ondemand. It is most useful for apps which contain allot
of `Assets`, such as Games or Multi Media applications.
See the [documentation](https://developer.android.com/guide/playcore/asset-delivery) for details on how this all works.
.NET Android does not have any official support for this type of pack.
However a hack is available via the excellent @infinitespace-studios on
[github](https://github.com/infinitespace-studios/MauiAndroidAssetPackExample).
This hack allows developers to place additional assets in a special
`NoTargets` project. This project is built just after the final `aab` is
produced. It builds a zip file which is then added to the `@(Modules)`
ItemGroup in the main application. This zip is then included into the
final app as an additional feature.

## Asset Pack Specification

We want to provide our users the ability to use `Asset` packs without
having to implement the hack provided by @infinitespace-studios. Using
a separate project like in the hack is one way to go. It does have some
issues though.

1. It is a `special` type of project. It requires a `global.json` which imports the
`NoTargets` sdk.
2. There is no IDE support for building this type of project.

Having the user go through a number of hoops to implement this for
.NET Android or .net Maui is not ideal. We need a simpler method.

The new idea is to make use of additional metadata on `AndroidAsset`
Items to allow the build system to split up the assets into packs
automatically. So it is proposed that we implement support for something
like this

```xml
<ItemGroup>
<AndroidAsset Include="Asset/data.xml" />
<AndroidAsset Include="Asset/movie.mp4" AssetPack="assets1" />
<AndroidAsset Include="Asset/movie2.mp4" AssetPack="assets1" />
</ItemGroup>
```

In this case the additional `AssetPack` attribute is used to tell the
build system which pack to place this asset in. Since auto import of items
is common now we need a way for a user to add this additional attribute
to auto included items. Fortunately we are able to use the following.

```xml
<ItemGroup>
<AndroidAsset Update="Asset/movie.mp4" AssetPack="assets1" />
<AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
<AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>
```

This code uses the `Update` attribute to tell MSBuild that we are going
to update a specific item. Note in the sample we do NOT need to include
an `Update` for the `data.xml`, since this is auto imported it will still
end up in the main feature in the aab.

Additional attributes can be used to control what type of asset pack is
produced. The only extra one supported at this time is `DeliveryType`,
this can have a value of `InstallTime`, `FastFollow` or `OnDemand`.
Additional attributes do not need to be included on ALL items. Any one
will do, only the `AssetPack` attribute will be needed.
See Google's [documentation](https://developer.android.com/guide/playcore/asset-delivery#asset-updates) for details on what each item does.

```xml
<ItemGroup>
<AndroidAsset Update="Asset/movie.mp4" AssetPack="assets1" DeliveryType="InstallTime" />
<AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
<AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>
```

If the `AssetPack` attribute is not present, the default behavior will
be to include the asset in the main application package.

If however you have a large number of assets it might be more efficient to make use of the `base` asset pack setting. In this scenario you update ALL assets to be in a single asset pack then use the `AssetPack="base"` metadata to declare which specific assets end up in the base aab file. With this you can use wildcards to move most assets into the asset pack.

```xml
<ItemGroup>
<AndroidAsset Update="Assets/*" AssetPack="assets1" />
<AndroidAsset Update="Assets/movie.mp4" AssetPack="base" />
<AndroidAsset Update="Assets/some.png" AssetPack="base" />
</ItemGroup>
```

In this example, `movie.mp4` and `some.png` will end up in the `base` aab file, but ALL the other assets
will end up in the `assets1` asset pack.

## Implementation Details

There are a few changes we need to make in order to support this feature.
One of the issues we will hit is the build times when dealing with large assets.
Current the assets which are to be included in the `aab` are COPIED
into the `$(IntermediateOutputPath)assets` directory. This folder is
then passed to `aapt2` for the build process.

The new system adds a new directory `$(IntermediateOutputPath)assetpacks`.
This directory would contain a subdirectory for each `pack` that the
user wants to include.

```dotnetcli
assetpacks/
assets1/
assets/
movie1.mp4
feature2/
assets/
movie2.mp4
```

All the building of the `pack` zip file would take place in these subfolders.
The name of the pack will be based on the main "packagename" with the asset pack
name appended to the end. e.g `com.microsoft.assetpacksample.assets1`.

During the build process we identify ALL the `AndroidAsset` items which
define an `AssetPack` attribute. These files are then copied to the
new `$(IntermediateOutputPath)assetpacks` directory rather than the
existing `$(IntermediateOutputPath)assets` directory. This allows us to
continue to support the normal `AndroidAsset` behavior while adding the
new system.

Once we have collected and copied all the assets we then use the new
`GetAssetPacks` Task to figure out which asset packs we need to create.
We then call the `CreateDynamicFeatureManifest` to create a required
`AndroidManifest.xml` file for the asset pack. This file will end
up in the same `$(IntermediateOutputPath)assetpacks` directory.
We call this Task `CreateDynamicFeatureManifest` because it can be used
to create any feature pack if and when we get to implement full feature
packs.

```dotnetcli
assetpacks/
assets1/
AndroidManifest.xml
assets/
movie1.mp4
feature2/
AndroidManifest.xml
assets/
movie2.mp4
```

We can then call `aapt2` to build these packs into `.zip` files. A new
task `Aapt2LinkAssetPack` takes care of this. This is a special version
of `Aapt2Link` which implements linking for asset packs only.
It also takes care of a few problems which `aapt2` introduces. For some
reason the zip file that is created has the `AndroidManifest.xml` file
in the wrong place. It creates it in the root of the zip file, but the
`bundletool` expects it to be in a `manifest` directory.
`bundletool` will error out if its not in the right place.
So `Aapt2LinkAssetPack` takes care of this for us. It also removes a
`resources.pb` which gets added. Again, `bundletool` will error if this
file is in the zip file.

Once the zip files have been created they are then added to the
`AndroidAppBundleModules` ItemGroup. This will ensure that when the
final `.aab` file is generated they are included as asset packs.

32 changes: 32 additions & 0 deletions Documentation/guides/building-apps/build-items.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,38 @@ or library project is built.
Supports [Android Assets](https://developer.android.com/guide/topics/resources/providing-resources#OriginalFiles),
files that would be included in the `assets` folder in a Java Android project.

The `AndroidAsset` ItemGroup also supports additional metadata for generating [Asset Packs](https://developer.android.com/guide/playcore/asset-delivery). Adding the `AssetPack` attribute to and `AndroidAsset` will automatically generate an asset pack of that name. This feature is only supported when using the `.aab`
`AndroidPackageFormat`. The following example will place `movie2.mp4` and `movie3.mp4` in separate asset packs.

```xml
<ItemGroup>
<AndroidAsset Update="Asset/movie.mp4" />
<AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
<AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>
```

This feature can be used to include large files in your application which would normally exceed the max
package size limits of Google Play.

If you have a large number of assets it might be more efficient to make use of the `base` asset pack.
In this scenario you update ALL assets to be in a single asset pack then use the `AssetPack="base"` metadata
to declare which specific assets end up in the base aab file. With this you can use wildcards to move most
assets into the asset pack.

```xml
<ItemGroup>
<AndroidAsset Update="Assets/*" AssetPack="assets1" />
<AndroidAsset Update="Assets/movie.mp4" AssetPack="base" />
<AndroidAsset Update="Assets/some.png" AssetPack="base" />
</ItemGroup>
```

In this example, `movie.mp4` and `some.png` will end up in the `base` aab file, but ALL the other assets
will end up in the `assets1` asset pack.

The additional metadata is only supported on .NET Android 9 and above.

## AndroidAarLibrary

The Build action of `AndroidAarLibrary` should be used to directly
Expand Down
1 change: 1 addition & 0 deletions Documentation/guides/building-apps/build-process.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,7 @@ Extension points include:
- [`$(AfterGenerateAndroidManifest)](~/android/deploy-test/building-apps/build-properties.md#aftergenerateandroidmanifest)
- [`$(BeforeGenerateAndroidManifest)](~/android/deploy-test/building-apps/build-properties.md#beforegenerateandroidmanifest)
- [`$(BeforeBuildAndroidAssetPacks)`](~/android/deploy-test/building-apps/build-properties.md#beforebuildandroidassetpacks)
A word of caution about extending the build process: If not
written correctly, build extensions can affect your build
Expand Down
19 changes: 19 additions & 0 deletions Documentation/guides/building-apps/build-properties.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -832,6 +832,18 @@ APK root directory. The format of the path is `lib\ARCH\wrap.sh` where
+ `x86_64`
+ `x86`

## AndroidIncludeAssetPacksInPackage

This property controls if an Asset Packs build automatically are auto
included in the final `.aab` file. It will default to `true`.

In certain cases the user might want to release an interim release. In
these cases the user does not NEED to update the asset pack. Especially
if the contents of the asset pack have not changed. This property allows
the user to skip the asset packs if they are not required.

Added in .NET 9

## AndroidInstallJavaDependencies

The default value is `true` for command line builds. When set to `true`, enables
Expand Down Expand Up @@ -1674,6 +1686,13 @@ as support for `$(AotAssemblies)` will be removed in a future release.

Extra options to pass to `aprofutil`.

## BeforeBuildAndroidAssetPacks

MSBuild Targets listed in this
property will run directly before `_BuildAssetPacks`.

Added in .NET 9

## BeforeGenerateAndroidManifest

MSBuild Targets listed in this
Expand Down
1 change: 1 addition & 0 deletions Documentation/guides/messages/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ package from all the users on device and try again. If that does not work you ca
Fast Deployment is not currently supported on this device.
Please file an issue with the exact error message using the 'Help->Send Feedback->Report a Problem' menu item in Visual Studio
or 'Help->Report a Problem' in Visual Studio for Mac.
+ [XA0138](xa0138.md): @(AndroidAsset) build action does not support 'AssetPack' Metadata in Library Projects.

## XA1xxx: Project related

Expand Down
13 changes: 13 additions & 0 deletions Documentation/guides/messages/xa0138.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
title: Xamarin.Android error XA0138
description: XA0138 error code
ms.date: 02/05/2024
---
# Xamarin.Android error XA0138

## Issue

@(AndroidAsset) build action does not support 'AssetPack' or 'DeliveryType' Metadata in Library Projects.

## Solution

Remove the 'AssetPack' or 'DeliveryType' Metadata from your `AndroidAsset` build Items.
1 change: 1 addition & 0 deletions build-tools/installers/create-installers.targets
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@
<_MSBuildFiles Include="$(MicrosoftAndroidSdkOutDir)Xamarin.Android.Aapt2.targets" />
<_MSBuildFiles Include="$(MicrosoftAndroidSdkOutDir)Xamarin.Android.Analysis.targets" />
<_MSBuildFiles Include="$(MicrosoftAndroidSdkOutDir)Xamarin.Android.Application.targets" />
<_MSBuildFiles Include="$(MicrosoftAndroidSdkOutDir)Xamarin.Android.Assets.targets" />
<_MSBuildFiles Include="$(MicrosoftAndroidSdkOutDir)Xamarin.Android.Bindings.ClassParse.targets" />
<_MSBuildFiles Include="$(MicrosoftAndroidSdkOutDir)Xamarin.Android.Bindings.Core.targets" />
<_MSBuildFiles Include="$(MicrosoftAndroidSdkOutDir)Xamarin.Android.Bindings.Maven.targets" />
Expand Down
Loading

0 comments on commit 7d5ec40

Please sign in to comment.