Skip to content

Commit 44e132d

Browse files
StephaneDelcroixsimonrozsivaljfversluis
authored
Revise XAML compilation documentation (#3089)
* Revise XAML compilation documentation Updated the XAML compilation documentation to reflect changes in terminology and features, including XAML processing, source generation, and inflation methods. * Update docs/xaml/xamlc.md Co-authored-by: Šimon Rozsíval <simon@rozsival.com> * Apply suggestions from code review * Update docs/xaml/xamlc.md --------- Co-authored-by: Šimon Rozsíval <simon@rozsival.com> Co-authored-by: Gerald Versluis <gerald@verslu.is>
1 parent ef79c74 commit 44e132d

File tree

1 file changed

+35
-36
lines changed

1 file changed

+35
-36
lines changed

‎docs/xaml/xamlc.md‎

Lines changed: 35 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
11
---
22
title: "XAML compilation"
33
description: ".NET MAUI XAML is compiled directly into intermediate language (IL) with the XAML compiler (XAMLC)."
4-
ms.date: 02/24/2022
4+
ms.date: 11/14/2025
55
---
66

7-
# XAML compilation
7+
# XAML Processing
88

9-
.NET Multi-platform App UI (.NET MAUI) XAML is compiled directly into intermediate language (IL) with the XAML compiler (XAMLC). XAML compilation offers a number of benefits:
9+
.NET Multi-platform App UI (.NET MAUI) XAML can be processed, and inflated into a tree of objects in different ways explained here. As of net10, default inflation is runtime for debug builds, XamlC (XamlCompilation) for Release. We encourage you to try source generation and use it if it works for you. This will become the future in new projects, then in all projects, soon.
10+
11+
## XAML Compilation
12+
13+
XAML is compiled directly into intermediate language (IL) with the XAML compiler (XAMLC). XAML compilation offers a number of benefits:
1014

1115
- It performs compile-time checking of XAML, notifying you of any errors.
1216
- It removes some of the load and instantiation time for XAML elements.
@@ -17,51 +21,46 @@ XAML compilation is enabled by default in .NET MAUI apps. For apps built using t
1721
> [!IMPORTANT]
1822
> Compiled bindings can be enabled to improve data binding performance in .NET MAUI applications. For more information, see [Compiled Bindings](~/fundamentals/data-binding/compiled-bindings.md).
1923
20-
## Disable XAML compilation
21-
22-
XAML compilation can be disabled by passing `XamlCompilationOptions.Skip` to the <xref:Microsoft.Maui.Controls.Xaml.XamlCompilationAttribute>:
23-
24-
```csharp
25-
[assembly: XamlCompilation(XamlCompilationOptions.Skip)]
26-
```
24+
## XAML runtime inflation
2725

28-
In this example, XAML compilation is disabled within the assembly, with XAML errors being reported at runtime rather than compile-time.
26+
XAML can be inflated at Runtime using reflection. It has advantages, like allowing HotReload scenario, shortening build times, allow the report of diagnostics to IDE.
2927

30-
XAML compilation can also be disabled at the type level:
28+
## XAML Sourcegeneration
3129

32-
```csharp
33-
[XamlCompilation (XamlCompilationOptions.Skip)]
34-
public partial class MyPage : ContentPage
35-
{
36-
...
37-
}
38-
```
30+
Starting with net10, XAML can be transformed into C# code at compilaiton time. It provides the following benefits:
3931

40-
In this example, XAML compilation is disabled only for the `MyPage` class.
32+
- Consistency: same generated code used in Debug and Release
33+
- Speed: inflation times on device are 10000% (100 times) faster in Debug, and 25% faster on Release. The volume of allocation is reduced in the same proportion
34+
- Debug: you can see the generated code, you can break and debug it.
4135

42-
> [!WARNING]
43-
> Disabling XAML compilation is not recommended because XAML is then parsed and interpreted at runtime, which will reduce app performance.
36+
This is the recommended way going further. It will be enabled by default in the future.
4437

45-
## Enable XAML compilation
38+
## Enable Source Generation, and per file settings
4639

47-
Because XAML compilation is enabled by default in .NET MAUI apps, removing any `XamlCompilation(XamlCompilationOptions.Skip)` statements will ensure that XAML compilation is enabled.
40+
We no longer recommend using `[XamlCompilation]` attribute to enable or disable per file compilation.
4841

49-
Alternatively, XAML compilation can be forcibly enabled by passing `XamlCompilationOptions.Compile` to the <xref:Microsoft.Maui.Controls.Xaml.XamlCompilationAttribute>:
42+
You can enable XAML source generation at the project level, by setting the `MauiXamlInflator` value to `SourceGen` in your csproj file as shown here:
5043

51-
```csharp
52-
[assembly: XamlCompilation(XamlCompilationOptions.Compile)]
44+
```xml
45+
<MauiXamlInflator>SourceGen</MauiXamlInflator>
5346
```
5447

55-
In this example, XAML compilation is enabled for all of the XAML contained within the assembly, with XAML errors being reported at compile-time rather than runtime.
48+
This will use source generation for both Release and Debug configurations.
5649

57-
XAML compilation can also be enabled at the type level:
50+
You can revert to the default per file (or use wildcards) or force another inflator
5851

59-
```csharp
60-
[XamlCompilation (XamlCompilationOptions.Compile)]
61-
public partial class MyPage : ContentPage
62-
{
63-
...
64-
}
52+
```xml
53+
<ItemGroup>
54+
<MauiXaml Update="MyFile.xaml" Inflator="SourceGen" /> <!-- enable sourcegen on a single file. prefer setting it at project level -->
55+
<MauiXaml Update="Controls\**.xaml" Inflator="" /> <!-- revert to defaults for all xaml in Controls -->
56+
<MauiXaml Update="Controls\**.xaml" Inflator="Runtime" /> <!-- force runtime inflation. if you have to do this, it probably indicates a bug in both XamlC and sourcegen, please report -->
57+
</ItemGroup>
6558
```
6659

67-
In this example, XAML compilation is enabled only for the `MyPage` class.
60+
There other metadata you can set to instruct xaml sourcegenerator
61+
62+
```xml
63+
<ItemGroup>
64+
<MauiXaml Update="MyFile.xaml" Inflator="SourceGen" NoWarn="0612;0618" /> <!-- prevent the compiler to fail if the xaml use deprecated API -->
65+
</ItemGroup>
66+
```

0 commit comments

Comments
 (0)