Skip to content

Commit a6d2efa

Browse files
jeromelabanjeromelaban
authored
docs: Add docs aggregation (#71)
1 parent a7c211c commit a6d2efa

File tree

4 files changed

+87
-69
lines changed

4 files changed

+87
-69
lines changed

‎README.md

Lines changed: 1 addition & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -9,72 +9,4 @@ This task is generally used to allow for separate resource dictionary authoring
99
To limit the impact of the traversal, this task task takes all resource dictionaries found in a specific MSBuild item group, and merges them into a single file. This file is then generally either named `Themes\Generic.xaml` or referenced as a merged dictionary from another `Themes\Generic.xaml` file.
1010

1111
## Using the task
12-
13-
Include the following block:
14-
15-
```xml
16-
<PropertyGroup>
17-
<_Uno_XamlMerge_Task_Version>1.0.0</_Uno_XamlMerge_Task_Version>
18-
</PropertyGroup>
19-
<ItemGroup>
20-
<PackageReference Include="Uno.XamlMerge.Task" Version="$(_Uno_XamlMerge_Task_Version)" />
21-
</ItemGroup>
22-
```
23-
24-
Then select the resource dictionaries to be merged:
25-
```xml
26-
<ItemGroup>
27-
<XamlMergeInput Include="Styles\**\*.xaml" Exclude="Styles\Generic.xaml" />
28-
</ItemGroup>
29-
```
30-
31-
> Note: The `Exclude` portion is only needed if some of your dictionaries still need to be referenced explicitly as some libraries require valid full path, such as [Uno.Themes](https://github.com/unoplatform/uno.themes).
32-
33-
Then add the following block at the end your project library or app:
34-
35-
```xml
36-
<Import Project="$(NuGetPackageRoot)uno.xamlmerge.task\$(_Uno_XamlMerge_Task_Version)\build\Uno.XamlMerge.Task.targets"
37-
Condition="'$(TargetFramework)' == '' and '$(TargetFrameworks)'!='' and exists('$(NuGetPackageRoot)\uno.xamlmerge.task\$(_Uno_XamlMerge_Task_Version)')" />
38-
```
39-
40-
The generated file is called `Generated\mergedpages.xaml` by default, but can be overriden as follows:
41-
42-
```xml
43-
<PropertyGroup>
44-
<XamlMergeOutputFile>Themes\Generic.xaml</XamlMergeOutputFile>
45-
</PropertyGroup>
46-
```
47-
Otherwise, the generated file can be referenced as follows:
48-
```xml
49-
<ResourceDictionary
50-
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
51-
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
52-
xmlns:local="using:TestLibrary">
53-
54-
<ResourceDictionary.MergedDictionaries>
55-
<ResourceDictionary Source="ms-appx:///REPLACE_ME/Generated/mergedpages.xaml" />
56-
</ResourceDictionary.MergedDictionaries>
57-
</ResourceDictionary>
58-
```
59-
60-
## Multiple generated files
61-
There are scenarios where placing groups of XAML files in separate merged file are useful, particularly when IL Linking must be used.
62-
63-
In this case, the project file must be defined as follows:
64-
```xml
65-
<ItemGroup>
66-
<!-- Output files -->
67-
<XamlMergeOutputFiles Include="Generated\MergedPart1.xaml" />
68-
<XamlMergeOutputFiles Include="Generated\MergedPart2.xaml" />
69-
70-
<!-- Input files, with the `MergeFile` metadata -->
71-
<XamlMergeInput Include="Styles\Part1\**\*.xaml" Exclude="Styles\Generic.xaml" MergeFile="MergedPart1.xaml" />
72-
<XamlMergeInput Include="Styles\Part2\**\*.xaml" Exclude="Styles\Generic.xaml" MergeFile="MergedPart2.xaml" />
73-
</ItemGroup>
74-
```
75-
76-
In this case, the `XamlMergeOutputFile` cannot be used, as the `XamlMergeOutputFiles` is defined.
77-
78-
## Troubleshooting
79-
- Make sure that all namespaces definitions across files are of the same values. (e.g. `xlmns:ns1="http://site1"` and `xlmns:ns1="http://site2"` in two different files will fail)
80-
- If you include the same resource dictionary (e.g. Colors.xaml) file in multiple merged files (generally used to have a file for custom brushes and colors), you can remove those multiple inclusions.
12+
See [our documentation](doc/using-xamlmerge.md) for more details on how to use this task.

‎doc/toc.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
- name: Uno the Xaml Merge task
2+
topicHref: using-xamlmerge.md
3+
- name: Troubleshooting
4+
href: troubleshooting.md

‎doc/troubleshooting.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Troubleshooting
2+
- Make sure that all namespaces definitions across files are of the same values. (e.g. `xlmns:ns1="http://site1"` and `xlmns:ns1="http://site2"` in two different files will fail)
3+
- If you include the same resource dictionary (e.g. Colors.xaml) file in multiple merged files (generally used to have a file for custom brushes and colors), you can remove those multiple inclusions.

‎doc/using-xamlmerge.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Uno.XamlMerge.Task
2+
An msbuild task which enables the merging of WinUI XAML resource dictionaries into a single flat ResourceDictionary.
3+
4+
This code is derived from WinUI's [`BatchMergeXaml`](https://github.com/microsoft/microsoft-ui-xaml/blob/a1ace7957abc19bce86141203560e15a737ccac7/tools/CustomTasks/BatchMergeXaml.cs) class, to be reused in any WinUI and Uno Platform Controls library.
5+
6+
## Why merge ResourceDictionary instances ?
7+
This task is generally used to allow for separate resource dictionary authoring (which makes them easier to load and read) to avoid impacting resources lookup runtime performance. In WinUI, ResourceDictionary resolution is performed through a graph traversal of MergedDictionaries, which generally implies that a worse case resolution can require as many lookups as there are dictionaries.
8+
9+
To limit the impact of the traversal, this task task takes all resource dictionaries found in a specific MSBuild item group, and merges them into a single file. This file is then generally either named `Themes\Generic.xaml` or referenced as a merged dictionary from another `Themes\Generic.xaml` file.
10+
11+
## Using the task
12+
13+
Include the following block:
14+
15+
```xml
16+
<PropertyGroup>
17+
<_Uno_XamlMerge_Task_Version>1.0.0</_Uno_XamlMerge_Task_Version>
18+
</PropertyGroup>
19+
<ItemGroup>
20+
<PackageReference Include="Uno.XamlMerge.Task" Version="$(_Uno_XamlMerge_Task_Version)" />
21+
</ItemGroup>
22+
```
23+
24+
Then select the resource dictionaries to be merged:
25+
```xml
26+
<ItemGroup>
27+
<XamlMergeInput Include="Styles\**\*.xaml" Exclude="Styles\Generic.xaml" />
28+
</ItemGroup>
29+
```
30+
31+
> Note: The `Exclude` portion is only needed if some of your dictionaries still need to be referenced explicitly as some libraries require valid full path, such as [Uno.Themes](https://github.com/unoplatform/uno.themes).
32+
33+
Then add the following block at the end your project library or app:
34+
35+
```xml
36+
<Import Project="$(NuGetPackageRoot)uno.xamlmerge.task\$(_Uno_XamlMerge_Task_Version)\build\Uno.XamlMerge.Task.targets"
37+
Condition="'$(TargetFramework)' == '' and '$(TargetFrameworks)'!='' and exists('$(NuGetPackageRoot)\uno.xamlmerge.task\$(_Uno_XamlMerge_Task_Version)')" />
38+
```
39+
40+
The generated file is called `Generated\mergedpages.xaml` by default, but can be overriden as follows:
41+
42+
```xml
43+
<PropertyGroup>
44+
<XamlMergeOutputFile>Themes\Generic.xaml</XamlMergeOutputFile>
45+
</PropertyGroup>
46+
```
47+
Otherwise, the generated file can be referenced as follows:
48+
```xml
49+
<ResourceDictionary
50+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
51+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
52+
xmlns:local="using:TestLibrary">
53+
54+
<ResourceDictionary.MergedDictionaries>
55+
<ResourceDictionary Source="ms-appx:///REPLACE_ME/Generated/mergedpages.xaml" />
56+
</ResourceDictionary.MergedDictionaries>
57+
</ResourceDictionary>
58+
```
59+
60+
## Multiple generated files
61+
There are scenarios where placing groups of XAML files in separate merged file are useful, particularly when IL Linking must be used.
62+
63+
In this case, the project file must be defined as follows:
64+
```xml
65+
<ItemGroup>
66+
<!-- Output files -->
67+
<XamlMergeOutputFiles Include="Generated\MergedPart1.xaml" />
68+
<XamlMergeOutputFiles Include="Generated\MergedPart2.xaml" />
69+
70+
<!-- Input files, with the `MergeFile` metadata -->
71+
<XamlMergeInput Include="Styles\Part1\**\*.xaml" Exclude="Styles\Generic.xaml" MergeFile="MergedPart1.xaml" />
72+
<XamlMergeInput Include="Styles\Part2\**\*.xaml" Exclude="Styles\Generic.xaml" MergeFile="MergedPart2.xaml" />
73+
</ItemGroup>
74+
```
75+
76+
In this case, the `XamlMergeOutputFile` cannot be used, as the `XamlMergeOutputFiles` is defined.
77+
78+
## Further reading
79+
- [Troubleshooting the generation](troubleshooting.md)

0 commit comments

Comments
 (0)