Merge pull request #6567 from unoplatform/mergify/bp/release/stable/3…

….9/pr-6523

feat: Add optional XAML Trimming (backport #6523)

build/Uno.UI.Build.csproj

@@ -166,10 +166,9 @@
 	<Target Name="UpdateTasksSHA">
 
 		<ItemGroup>
+			<_Sha1Replace Include="..\src\SourceGenerators\Uno.UI.Tasks\**\*.cs" />
 			<_Sha1Replace Include="..\src\SourceGenerators\Uno.UI.Tasks\Uno.UI.Tasks.csproj" />
-			<_Sha1Replace Include="..\src\SourceGenerators\Uno.UI.Tasks\Assets\RetargetAssets.cs" />
 			<_Sha1Replace Include="..\src\SourceGenerators\Uno.UI.Tasks\Content\Uno.UI.Tasks.targets" />
-			<_Sha1Replace Include="..\src\SourceGenerators\Uno.UI.Tasks\ResourcesGenerator\ResourcesGenerationTask.cs" />
 		</ItemGroup>
 
     <WriteLinesToFile

build/Uno.WinUI.nuspec

@@ -419,6 +419,8 @@
 	<file src="..\src\SourceGenerators\Uno.UI.Tasks\Bin\Release\*.dll" target="buildTransitive\Uno.UI.Tasks" />
 	<file src="..\src\SourceGenerators\Uno.UI.Tasks\Bin\Release\*.pdb" target="buildTransitive\Uno.UI.Tasks" />
 
+	<file src="..\src\SourceGenerators\Uno.UI.Tasks\external\linker\*.*" target="tools\linker" />
+
 	<file src="Uno.WinUI.targets" target="buildTransitive\MonoAndroid" />
 	<file src="Uno.WinUI.targets" target="buildTransitive\xamarinios10" />
 	<file src="Uno.WinUI.targets" target="buildTransitive\xamarinmac20" />

build/run-net6-template-tests.ps1

@@ -81,3 +81,8 @@ for($i = 0; $i -lt $dotnetBuildNet6Configurations.Length; $i++)
 }
 
 popd
+
+# XAML Trimming build smoke test
+dotnet new unoapp-net6 -n MyAppXamlTrim
+& dotnet build -c Debug MyAppXamlTrim\MyAppXamlTrim.Wasm\MyAppXamlTrim.Wasm.csproj /p:UnoXamlResourcesTrimming=true
+Assert-ExitCodeIsZero

doc/articles/features/resources-trimming.md

@@ -0,0 +1,46 @@
+# XAML Resource Trimming
+
+XAML Resource and Binding trimming is an 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 eligible for resources trimming, the `UnoXamlResourcesTrimming` tag 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 at compile time. 3.8 and earlier libraries can be used in any case, but won't be eligible 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 |

doc/articles/features/using-il-linker-webassembly.md

@@ -22,7 +22,7 @@ When parts of an application fail to work, you can:
 As a troubleshooting step to determine if the linker is causing your code to break, you can also disable the linker completely by adding the following to your `csproj` file:
 ```xml
 <PropertyGroup>
-  <WasmShellILLinkerEnabled>true</WasmShellILLinkerEnabled>
+  <WasmShellILLinkerEnabled>false</WasmShellILLinkerEnabled>
 </PropertyGroup>
 ```
 Note that disabling the linker is not recommended as it can force the compiler to generate very large WebAssembly modules AOT process, and go over the browser's size limits.

doc/articles/toc.yml

@@ -313,6 +313,8 @@
           href: uno-fluent-assets.md
         - name: Lottie animations
           href: features/Lottie.md
+        - name: Working with XAML Trimming
+          href: features/resources-trimming.md
         - name: Working with cookies
           href: features/working-with-cookies.md
         - name: Using pointer cursors
@@ -464,3 +466,5 @@
           href: uno-development\troubleshooting-memory-issues.md
         - name: Troubleshooting Source Generation
           href: uno-development\troubleshooting-source-generation.md
+        - name: The XAML Trimming phase
+          href: uno-development\Uno-UI-XAML-ResourceTrimming.md

doc/articles/uno-development/Uno-UI-XAML-ResourceTrimming.md

@@ -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 Metadata 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.

src/SolutionTemplate/UnoSolutionTemplate.net6/Wasm/UnoQuickStart.Wasm.csproj

@@ -48,8 +48,8 @@
 		<PackageReference Include="Uno.Extensions.Logging.WebAssembly.Console" Version="1.0.1" />
 		<PackageReference Include="Uno.UI.WebAssembly" Version="2.2.0" />
 		<PackageReference Include="Uno.UI.RemoteControl" Version="2.2.0" Condition="'$(Configuration)'=='Debug'" />
-		<PackageReference Include="Uno.Wasm.Bootstrap" Version="2.1.0" />
-		<PackageReference Include="Uno.Wasm.Bootstrap.DevServer" Version="2.1.0" />
+		<PackageReference Include="Uno.Wasm.Bootstrap" Version="3.0.0-dev.101" />
+		<PackageReference Include="Uno.Wasm.Bootstrap.DevServer" Version="3.0.0-dev.101" />
 	</ItemGroup>
 
 	<Import Project="..\$ext_safeprojectname$.Shared\$ext_safeprojectname$.Shared.projitems" Label="Shared" Condition="Exists('..\$ext_safeprojectname$.Shared\$ext_safeprojectname$.Shared.projitems')" />