Fixes: https://github.com/xamarin/xamarin-android/issues/6310
Context: 60d9b98938
Context: https://github.com/dotnet/fsharp/issues/12640
Context: 103b5a755c Optimize ResourceIdManager.UpdateIdValues() invocations
Context: 9e6ce03ca2 Adds $(AndroidLinkResource)
Context: 522d7fb61f
Context: 9c0437866c (AndroidEnablePreloadAssemblies crash)
Context: d521ac0280 (Styleables array values)
Replace the existing `Resource.designer.cs` generation code with a
new system that relies on Reference Assemblies. This results in
smaller apps and faster startup.
~~ Bind `@(AndroidResource)` values as fields ~~
The original approach to binding `@(AndroidResource)` values was to
Do What Java Does™: there are two "styles" of `Resource.designer.cs`
files, one for Library projects, and one for App projects.
`Resource.designer.cs` for Library projects involves mutable read/write
fields:
[assembly: Android.Runtime.ResourceDesignerAttribute ("ExampleLib.Resource", IsApplication=false)]
namespace ExampleLib;
partial class Resource {
partial class String {
public static int app_name = 2130771968;
static String() {
global::Android.Runtime.ResourceIdManager.UpdateIdValues();
}
}
partial class Styleable {
public static int[] MyLibraryWidget = new int[]{…};
static Styleable() {
global::Android.Runtime.ResourceIdManager.UpdateIdValues();
}
}
}
`Resource.designer.cs` for App projects involves *`const`* fields:
[assembly: Android.Runtime.ResourceDesignerAttribute ("App.Resource", IsApplication=true)]
namespace App;
partial class Resource {
partial class String {
public const int app_name = 2130968576;
static String() {
global::Android.Runtime.ResourceIdManager.UpdateIdValues();
}
}
partial class Styleable {
public static int[] MyLibraryWidget = new int[]{…}; // still read+write, not const
static Styleable() {
global::Android.Runtime.ResourceIdManager.UpdateIdValues();
}
}
}
There is a field each Android `resource` in the project *and* any
`resource`s declared in a referenced assembly or `.aar` files.
This can result in 1000's of fields ending up in each `Resource` class.
Because we only know the final `Id` values at app packaging time,
library projects could not know those values at build time. This meant
that we needed to update those library values at startup with the ones
that were compiled into the final application project. This is handled
by the `Resource.UpdateIdValues()` method. This method is called by
reflection on app startup and contains code to set the read/write
fields for *all* `Resource` types from *all referenced assemblies*:
partial class Resource {
public static void UpdateIdValues() {
global::ExampleLib.Resource.String.app_name = String.app_name;
// plus all other resources
}
}
**Pros**:
* It's a "known good" construct, as it's what Java does!
(Or *did*, circa 12 years ago…)
**Cons**:
* There is a semantic difference between the use of the `Resource`
types between Library and App projects: in an App project, you
can use Resource IDs in switch `case`s, e.g.
`case Resource.String.app_name: …`.
This is not possible in Library projects.
* As the App `Resource.UpdateIdValues()` method references *all*
fields from all referenced libraries, the linker is not able to
remove any of the fields. This pattern is linker hostile.
This results in larger `.apk` sizes, though this can be optimized
via [`$(AndroidLinkResources)`][0] (9e6ce03c, d521ac02).
* As the App `Resource.UpdateIdValues()` method references *all*
fields from all referenced libraries, the method can be *huge*;
it depends on how many resources the App and all dependencies
pull in. We have seen cases where the size of
`Resource.UpdateIdValues()` would cause the interpreter to crash,
breaking certain Hot Reload scenarios.
(Fixed in dotnet/runtime@60d9b989).
* The `Resource.UpdateIdValues()` method needs to be invoked during
process startup, *before* any assemblies try to use their
`Resource.…` values, and the method is looked up via *Reflection*.
This means System.Reflection is part of the app startup path,
which has overheads.
(This overhead is also removed via `$(AndroidLinkResources)`.)
~~ Bind `@(AndroidRoesource)` values as properties ~~
Replace the "bind resources as fields" approach with a new system
with significant differences:
1. Android resource ids are bound as read-only *properties*, and
2. The `Resource` class is placed into a *separate assembly*,
`_Microsoft.Android.Resource.Designer.dll`.
The new `$(AndroidUseDesignerAssembly)` MSBuild property controls
which Android resource approach is used; if True -- the default for
.NET 8 -- then `_Microsoft.Android.Resource.Designer.dll` will be
used. If False, then the previous "bind resource ids as fields"
approach will be used. This property is only valid for Library
projects; App projects must use the property-oriented approach.
This new approach takes advantage of [Reference Assemblies][1].
Reference Assemblies are designed to be replaced at runtime, and are
generally used to provide placeholder API's which can be swapped out
later.
Library projects will generate a Reference Assembly for
`_Microsoft.Android.Resource.Designer.dll` which contains read-only
properties for each `@(AndroidResource)` within the project and all
dependencies. This is otherwise identical to the "fields" approach,
*except* that the namespace is predefined, its a new assembly, and
properties are used instead of fields, *as if* it contained:
// _Microsoft.Android.Resource.Designer.dll for Library project
[assembly: System.Runtime.CompilerServices.ReferenceAssemblyAttribute]
namespace Microsoft.Android.Resource.Designer;
public partial class Resource {
public partial class String {
public static int app_name => 0;
}
public partial class Styleable {
public static int[] MyLibraryWidget => nullptr;
}
}
Also note that `_Microsoft.Android.Resource.Designer.dll` is produced
*with Mono.Cecil* as a pre-build action; no C# source is generated.
The Library assembly references the generated
`_Microsoft.Android.Resource.Designer.dll`.
The generated `_Microsoft.Android.Resource.Designer.dll` should
***NOT*** be shipped with NuGet packages.
App projects will generate the "real"
`_Microsoft.Android.Resource.Designer.dll`, also as a pre-build step,
and the "real" assembly will contain actual values for resource ids.
The App-built `_Microsoft.Android.Resource.Designer.dll` will also
have `[assembly:InternalsVisibleToAttribute]` to the App assembly:
// _Microsoft.Android.Resource.Designer.dll for App project
[assembly: System.Runtime.CompilerServices.InternalsVisibleToAttribute ("App…")]
namespace Microsoft.Android.Resource.Designer;
public partial class Resource {
public partial class String {
public static int app_name => 2130968576;
}
public partial class Styleable {
static int[] MyLibraryWidget = new[]{…};
public static int[] MyLibraryWidget => MyLibraryWidget;
}
}
This approach has a number of benefits
1. All the property declarations are in one place and are not
duplicated (-ish… more on that later).
As a result the size of the app will be reduced.
2. Because we no longer need the `Resource.UpdateIdValues()` method,
start up time will be reduced.
3. The linker can now do its job and properly link out unused
properties. This further reduces application size.
4. F# is now fully supported. See also: dotnet/fsharp#12640.
~~ Styleable Arrays ~~
Styleable resources may be arrays; see e.g. d521ac02. Via the power
of Cecil (and not using C# as an intermediate codegen), the binding
of styleable arrays in the "Bind `@(AndroidRoesource)` values as
properties" world order involves a static field containing the array
data, and a public property which returns the private field, which
has the same name:
public partial class Resource {
public partial class Styleable {
static int[] MyLibraryWidget = new[]{…};
public static int[] MyLibraryWidget => MyLibraryWidget;
}
}
CIL-wise, *yes*, the field and the property have the same name (?!),
but because properties actually have `get_` method prefix, there will
actually be a `MyLibraryWidget` field and a `get_MyLibraryWidget()`
method, so there are no name collisions.
*Note*: ***The styleable array is not copied***. This means it is
global mutable data, i.e. one can do this:
Microsoft.Android.Resource.Designer.Resource.Styleable.MyLibraryWidget[0] = 42;
***DO NOT DO THIS***. It will introduce runtime errors.
The e.g. `Resource.Styleable.MyLibraryWidget` property must be an
`int[]` in order to maintain compatibility, as these are often
passed to methods which take `int[]` as the parameter type. We thus
cannot instead use e.g. `IEnumeragble<int>` as the property type.
Additionally, the array isn't copied for performance reasons.
We do not think that this will be a problem in practice, as the
previous "Bind `@(AndroidRoesource)` values as fields" strategy
*also* had mutable `int[]` fields, and suffers from the same
safety concerns, and the world hasn't ended…
~~ Source Compatibility ~~
In the "bind resource ids as fields" approach, the `Resource` class
was in the default namespace for the Library project, set via the
[`$(RootNamespace)`][2] MSBuild property. In order to maintain
source compatibility, Library projects will have a generated
`__Microsoft.Android.Resource.Designer.cs` file which contains a new
`Resource` declaration which *inherits* from the `Resource` type in
`_Microsoft.Android.Resource.Designer.dll`:
// Generated __Microsoft.Android.Resource.Designer.cs in Library projects
namespace ExampleLib;
public class Resource : Microsoft.Android.Resource.Designer.Resource {
}
This allows existing code such as `ExampleLib.Resource.String.app_name`
to continue to compile.
App projects also expect a `Resource` class in `$(RootNamespace)`,
*and* expect the values to be `const`. To support this, the generated
`_Microsoft.Android.Resource.Designer.dll` *actually* has two sets
of `Resource` types, one with properties, and an *`internal`*
`ResourceConstant` type:
// _Microsoft.Android.Resource.Designer.dll for Library project
[assembly: System.Runtime.CompilerServices.InternalsVisibleToAttribute ("App…")]
namespace Microsoft.Android.Resource.Designer;
internal partial class ResourceConstant {
public partial class String {
public const int app_name = 2130968576;
}
}
public partial class Resource {
public partial class String {
public static int app_name => ResourceConstant.String.app_name;
}
}
App projects *also* have a generated
`__Microsoft.Android.Resource.Designer.cs`, which has a `Resource` type
which inherits from `ResourceConstant`. This is why the App-built
`_Microsoft.Android.Resource.Designer.dll` needs
`[assembly: InternalsVisibleToAttribute]`:
// Generated __Microsoft.Android.Resource.Designer.cs in App projects
namespace App;
public class Resource : Microsoft.Android.Resource.Designer.ResourceConstant {
}
This allows existing App code to use `App.Resource.String.app_name`
in `case` statements.
~~ Binary Compatibility ~~
Binary compatibility is maintained via a new
`MonoDroid.Tuner.FixLegacyResourceDesignerStep` linker step.
`FixLegacyResourceDesignerStep` rewrites Library assemblies to replace
`Resource.…` field access with property access to
`Microsoft.Android.Resource.Designer.Resource.…` in
`_Microsoft.Android.Resource.Designer.dll`. Much of this code
overlaps with the existing logic of `$(AndroidLinkResources)`, and
allows existing Library assemblies to participate in the property-
oriented system.
~~ Internals ~~
The new build system introduces a number of new Tasks and Targets to
bring this all together. It also unify's some code between the field-
oriented and property-oriented approaches which would otherwise be
duplicated. The field-oriented system will be maintained for now for
backward compatibility, however the property-oriented system will be
enabled by default for .net 8.
The property-oriented system is mostly contained in
`Xamarin.Android.Resource.Designer.targets`. The entry point for this
set of targets is `_BuildResourceDesigner`, which will only be run if
the `$(AndroidUseDesignerAssembly)` MSBuild property is `True`, as it
will be for .NET 8+.
New tasks are as follows.
- `<GenerateRtxt/>` is responsible for scanning the resource
directory and generating an `aapt2`-compatible `R.txt` file.
This will be used by `<GenerateResourceDesignerAssembly/>`.
- `<GenerateResourceCaseMap/>` is responsible for generating a
`casemap.txt` file which will map the all lower case android
resources to the casing required for the C# code. Android requires
ALL resources be lower case, but our system allows the user to
define the case using any system then want. This task handles
generating this mapping between what the android system needs and
what the user is expecting. Its output is used by the
`<GenerateResourceDesignerAssembly/>` task when generating the IL
in `_Microsoft.Android.Resource.Designer.dll`.
It is also used by the old system to generate the same file.
- `<GenerateResourceDesignerIntermediateClass/>` is responsible for
generating the `__Microsoft.Android.Resource.Designer.cs` file in
`$(IntermediateOutputPath)`.
- `<GenerateResourceDesignerAssembly/>` is the key to the whole
property-oriented approach. This task will read the `R.xt` file
and generate a `_Microsoft.Android.Resource.Designer.dll` assembly
in `$(IntermediateOutputPath)`. This task is called in two places.
The first is in `_GenerateResourceDesignerAssembly`, this is called
as part of the build which happens just before `CoreCompile` and
only for design time builds.
It is also called in `_UpdateAndroidResgen` which happens as part
of the build and runs just after `aapt2` is called. This ensures
we always use the most up to date version of `R.txt` to generate
the new assembly.
Because we are using the `R.txt` file to drive the generation of the
new assembly, we needed some way for that to work when `aapt2` was
not being run. This usually happens on a first time design time build.
The field-oriented approach has a `<GenerateResourceDesigner/>` task
which is responsible for both scanning the resources and generating a
design time `Resource.designer.cs` file. While we could have
duplicated the code it made more sense to split out the resource
scanner into its own class. We now have a new `<GenerateRtxt/>` task
which is responsible for scanning the resources and generating an
`R.txt` file. This is only used when we are not doing a full build
with `aapt2`. This new task lets us generate the needed `R.txt` which
can then be used by both the old and new system to generate their
respective outputs.
As part of this we have two other classes: `RtxtReader` and
`RtxtWriter`. The `RtxtReader` unify's the code which was used to read
the values of the `R.txt` into one class which can be used by both
approaches. The `RtxtWriter` is responsible for writing the `R.txt`
file for design time builds. Again it will be used by both the old
and new system.
The `_AddResourceDesignerFiles` target is responsible for ensuring that
the new assembly and `__Microsoft.Android.Resource.Designer.cs` get
added to the correct item groups. These are `@(ReferencePath)` for the
assembly and `@(Compile)` for the source file. In the case of F# the
`__Microsoft.Android.Resource.Designer.fs` file which gets generated
has to be added to the `@(CompileBefore)` ItemGroup, this is so that
the types are resolved in the correct order.
To ensure that the new assembly is added to the final application we
have to introduce the `_AddResourceDesignerToPublishFiles` target.
This target makes sure that the new assembly is added to the
`@(ResolvedFileToPublish)` ItemGroup. It also adds the require
MetaData items such as `%(IsTrimmable)` and `%(PostprocessAssembly)`
which are required to get the assembly linked correctly.
~~ Results ~~
Results are most visible when lots of Android Resources are used.
For a [Sample app][3] app which uses lots of resources, we see the
following improvements to the **ActivityTaskManager: Displayed** time:
| Before (ms) | After (ms) | Δ (%) | Notes |
| ----------: | ----------: | --------: | ------------------------------------ |
| 340.500 | 313.250 | -8.00% ✓ | defaults; 64-bit build |
| 341.950 | 316.200 | -7.53% ✓ | defaults; profiled AOT; 64-bit build |
| 345.950 | 324.600 | -6.17% ✓ | defaults; 32-bit build |
| 341.000 | 323.050 | -5.26% ✓ | defaults; profiled AOT; 32-bit build |
[0]: https://learn.microsoft.com/en-us/xamarin/android/deploy-test/building-apps/build-properties#androidlinkresources
[1]: https://learn.microsoft.com/en-us/dotnet/standard/assembly/reference-assemblies
[2]: https://learn.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-properties?view=vs-2022
[3]: https://github.com/dellis1972/DotNetAndroidTest
dc3ccf28cd