-
Notifications
You must be signed in to change notification settings - Fork 742
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Add optional XAML and Bindings Trimming
- Loading branch information
1 parent
85b01a1
commit 228bf67
Showing
30 changed files
with
1,435 additions
and
99 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # XAML Resource Trimming | ||
|
|
||
| XAML Resource and Binding trimming is a optional feature used to reduce the size of the final payload of an Uno Platform application. | ||
|
|
||
| The trimming phase happens after the compilation phase and tries to determine which UI controls are not used explicitly, and removes the associated XAML styles. The XAML styles are found through the value specified in the `TargetType` attribute. | ||
|
|
||
| As of Uno 3.9, XAML Resources Trimming is only available for WebAssembly projects. | ||
|
|
||
| ## Using XAML Resources trimming for applications | ||
|
|
||
| In order for an application to enable resources trimming, the following needs to be added in the project file: | ||
|
|
||
| ```xml | ||
| <PropertyGroup> | ||
| <UnoXamlResourcesTrimming>true</UnoXamlResourcesTrimming> | ||
| </PropertyGroup> | ||
| ``` | ||
|
|
||
| ## Enabling XAML Resources trimming for libraries | ||
| For libraries to be elligible for resources trimming, the `UnoXamlResourcesTrimming` must also be added. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| ### Aggressive trimming | ||
| The XAML trimming phase may remove controls for which the use cannot be detected statically. | ||
|
|
||
| For instance, if your application relies on the `XamlReader` class, trimmed controls will not be available and will fail to load. | ||
|
|
||
| If XAML trimming is still needed, the [IL Linker configuration](using-il-linker-webassembly.md) can be adjusted to keep controls individually or by namespace. | ||
|
|
||
| ### Size is not reduced even if enabled | ||
| The IL Linker tool is used to implement this feature, and can be [controlled with its configuration file](using-il-linker-webassembly.md). | ||
|
|
||
| For instance, if the linker configuration file contains `<assembly fullname="uno.ui" />`, none of the UI Controls will be excluded, and the final app size will remain close as without trimming. | ||
|
|
||
| Note that for libraries, Uno 3.9 or later must be used to build the library, as additional metadata needs to be added a compile time. 3.8 and earlier libraries can be used in any case, but won't be elligible for trimming and may degrade the trimming phase effect. | ||
|
|
||
|
|
||
| ## Size reduction statistics | ||
|
|
||
| As of Uno 3.9, for a `dotnet new unoapp` created app: | ||
|
|
||
| | | w/o XAML Trimming | w/ XAML Trimming | | ||
| | -------------------- | ----------------- | --------------- | | ||
| | Total IL Payload | 12.9MB | 9.12 MB | | ||
| | dotnet.wasm | 53MB | 28.9MB MB | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
28 changes: 28 additions & 0 deletions
28
doc/articles/uno-development/Uno-UI-XAML-ResourceTrimming.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # XAML Resource Trimming | ||
|
|
||
| This document provides technical details about the [XAML Resource trimming phase](../features/resources-trimming.md). | ||
|
|
||
| ## Technical Details | ||
|
|
||
| In Uno, XAML is generating C# code in order to speed up the creation of the UI. This allows for compile-time optimizations, such as type conversions or `x:Bind` integration. | ||
|
|
||
| The drawback of this approach is that code may be bundled with an app even if it's not used. In common use cases, the IL Linker is able to remove code not referenced, but in the case of XAML resources, this code is conditionally referenced through string cases only. This makes it impossible for the linker to remove that code through out-of-the-box means. | ||
|
|
||
| In order to dermine what is actually used by the application, the Uno Platform tooling runs a sequence of IL Linker passes and substitutions. | ||
|
|
||
| In order to prepare the linking pass: | ||
| - The tooling determines the presence of the `UnoXamlResourcesTrimming` msbuild property | ||
| - During the source generation, the tooling generates a `LinkerHints` class, which contains a set of properties for all `DependencyObject` inheriting classes. | ||
| - The source generation creates XAML Resources and Bindable Metadata code that conditionally uses those classes behind `LinkerHints` properties. | ||
| - The tooling also embeds an ILLinker substitution file allowing the linker to unconditionally remove the code that conditionally references those properties. For instance, for `LinkerHints.Is_Windows_UI_Xaml_Controls_Border_Available`, any block of `if (LinkerHints.Is_Windows_UI_Xaml_Controls_Border_Available)` will be removed when the `--feature Is_Windows_UI_Xaml_Controls_Border_Available false` parameter is provided to the linker. | ||
|
|
||
| Then the multiple passes of IL Linker are done: | ||
| - The first pass runs the IL Linker with all XAML resources and Binding Metadata disabled by setting all `LinkerHints` properties to false. This removes all code directly associated to those Bindable Medata and XAML Resources. This has the effect of only keeping framework code which is directly referenced from user code. | ||
| - The tooling then reads the result of the linker to determine which types in the `LinkerHints` are still available in the assemblies. | ||
| - The subsequent passes run the IL Linker with `LinkerHints` enabled only for types detected to be used during the first pass. This will enable types indirectly referenced by XAML Resources (e.g. a ScrollBar inside a ScrollViewer style) to be kept by the linker. | ||
| - The tooling then reads again the result of the linker to determine which types in the `LinkerHints` are still available in the assemblies. | ||
| - The tooling re-runs this last pass until the available types list stops changing. | ||
|
|
||
| The resulting `LinkerHints` types are now passed as features to the final linker pass (the one bundled with the .NET tooling) to generate the final binary, containing only the used types. | ||
|
|
||
| As of Uno 3.9, the Uno.UI WebAssembly assembly is 7.5MB, trimmed down to 3.1MB for a `dotnet new unoapp` template. |
Oops, something went wrong.