Skip to content

Commit 89615d7

Browse files
Document implicit XAML namespace declarations for .NET 11 (#3281)
In .NET 11 (PR dotnet/maui#33834), implicit xmlns declarations are enabled by default. The compiler automatically injects the standard MAUI and x: namespace declarations, so XAML files can omit them. Changes: - docs/xaml/namespaces/index.md: Add new 'Implicit namespace declarations' section with before/after examples, moniker-gated for .NET 11 (default) and .NET 10 (preview opt-in). - docs/xaml/fundamentals/get-started.md: Add .NET 11 note near xmlns explanation and split the implicit xmlns content into version- specific moniker blocks (.NET 11 default vs .NET 10 opt-in). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 7b946b6 commit 89615d7

2 files changed

Lines changed: 101 additions & 2 deletions

File tree

docs/xaml/fundamentals/get-started.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,13 @@ The *MainPage.xaml* file has the following structure:
3030

3131
The two XML namespace (`xmlns`) declarations refer to URIs on microsoft.com. However, there's no content at these URIs, and they basically function as version identifiers.
3232

33+
::: moniker range=">=net-maui-11.0"
34+
35+
> [!NOTE]
36+
> Starting in .NET 11, these two standard namespace declarations are implicit and can be omitted from your XAML files. The compiler injects them automatically. For more information, see [Implicit namespace declarations](~/xaml/namespaces/index.md#implicit-namespace-declarations).
37+
38+
::: moniker-end
39+
3340
The first XML namespace declaration means that tags defined within the XAML file with no prefix refer to classes in .NET MAUI, for example <xref:Microsoft.Maui.Controls.ContentPage>. The second namespace declaration defines a prefix of `x`. This is used for several elements and attributes that are intrinsic to XAML itself and which are supported by other implementations of XAML. However, these elements and attributes are slightly different depending on the year embedded in the URI. .NET MAUI supports the [2009 XAML specification](/dotnet/desktop/xaml-services/xaml-2009-language-features).
3441

3542
At the end of the first tag, the `x` prefix is used for an attribute named `Class`. Because the use of this `x` prefix is virtually universal for the XAML namespace, XAML attributes such as `Class` are almost always referred to as `x:Class`. The `x:Class` attribute specifies a fully qualified .NET class name: the `MainPage` class in the `MyMauiApp` namespace. This means that this XAML file defines a new class named `MainPage` in the `MyMauiApp` namespace that derives from <xref:Microsoft.Maui.Controls.ContentPage> (the tag in which the `x:Class` attribute appears).
@@ -145,6 +152,37 @@ using XmlnsPrefixAttribute = Microsoft.Maui.Controls.XmlnsPrefixAttribute;
145152
[assembly: XmlnsPrefix("MyApp.Controls", "controls")]
146153
```
147154

155+
::: moniker-end
156+
157+
::: moniker range=">=net-maui-11.0"
158+
159+
### Implicit namespace declarations
160+
161+
Starting in .NET 11, the standard XAML namespace declarations are implicit by default — no opt-in is required. The compiler automatically injects `xmlns="http://schemas.microsoft.com/dotnet/2021/maui"` and `xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"`, so your XAML files can omit them:
162+
163+
**Before (.NET 10 and earlier)**
164+
165+
```xml
166+
<ContentPage
167+
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
168+
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
169+
x:Class="MyApp.Pages.MyContentPage">
170+
</ContentPage>
171+
```
172+
173+
**After (.NET 11)**
174+
175+
```xml
176+
<ContentPage x:Class="MyApp.Pages.MyContentPage">
177+
</ContentPage>
178+
```
179+
180+
Custom namespaces still require explicit `xmlns:` declarations. For more information, see [Implicit namespace declarations](~/xaml/namespaces/index.md#implicit-namespace-declarations).
181+
182+
::: moniker-end
183+
184+
::: moniker range="net-maui-10.0"
185+
148186
To enable the most streamlined experience (implicit default namespaces), add:
149187

150188
```xml

docs/xaml/namespaces/index.md

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
title: "XAML namespaces"
33
description: ".NET MAUI XAML uses the xmlns XML attribute for namespace declarations. The default namespace specifies that elements defined within the XAML file with no prefix refer to .NET MAUI classes."
4-
ms.date: 10/19/2023
4+
ms.date: 07/15/2025
55
---
66

77
# XAML namespaces
88

9-
XAML uses the `xmlns` XML attribute for namespace declarations. There are two XAML namespace declarations that are always within the root element of a XAML file. The first defines the default namespace:
9+
XAML uses the `xmlns` XML attribute for namespace declarations. There are two standard XAML namespace declarations that typically appear within the root element of a XAML file. The first defines the default namespace:
1010

1111
```xaml
1212
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
@@ -43,6 +43,67 @@ For more information about the `x:ClassModifier` attribute, see [Class modifiers
4343
4444
In XAML, namespace declarations inherit from parent element to child element. Therefore, when defining a namespace in the root element of a XAML file, all elements within that file inherit the namespace declaration.
4545

46+
## Implicit namespace declarations
47+
48+
::: moniker range=">=net-maui-11.0"
49+
50+
Starting in .NET 11, implicit XAML namespace declarations are enabled by default. The compiler automatically injects the two standard namespace declarations, so you no longer need to include them in the root element of your XAML files:
51+
52+
- `xmlns="http://schemas.microsoft.com/dotnet/2021/maui"` — the default .NET MAUI namespace.
53+
- `xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"` — the XAML language namespace providing `x:Class`, `x:Name`, and other intrinsic constructs.
54+
55+
This means a content page that previously required explicit namespace declarations:
56+
57+
```xaml
58+
<!-- .NET 10 and earlier: explicit namespace declarations required -->
59+
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
60+
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
61+
x:Class="MyApp.MainPage">
62+
<Label Text="Hello, World!" />
63+
</ContentPage>
64+
```
65+
66+
Can now be written without them:
67+
68+
```xaml
69+
<!-- .NET 11: standard namespaces are implicit -->
70+
<ContentPage x:Class="MyApp.MainPage">
71+
<Label Text="Hello, World!" />
72+
</ContentPage>
73+
```
74+
75+
Existing XAML files that include explicit declarations continue to compile without changes. Explicit declarations can also be used to disambiguate duplicate type names when needed.
76+
77+
> [!IMPORTANT]
78+
> Custom namespaces still require explicit `xmlns:` declarations. Only the default .NET MAUI namespace and the `x:` XAML language namespace are implicitly available.
79+
80+
For example, you still need to declare a prefix for your own CLR namespaces or third-party libraries:
81+
82+
```xaml
83+
<ContentPage x:Class="MyApp.MainPage"
84+
xmlns:local="clr-namespace:MyApp.Controls"
85+
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">
86+
<local:CustomControl />
87+
</ContentPage>
88+
```
89+
90+
::: moniker-end
91+
92+
::: moniker range="net-maui-10.0"
93+
94+
In .NET 10, implicit namespace declarations are available as a preview feature. To opt in, add the following to your project file:
95+
96+
```xml
97+
<PropertyGroup>
98+
<DefineConstants>$(DefineConstants);MauiAllowImplicitXmlnsDeclaration</DefineConstants>
99+
<EnablePreviewFeatures>true</EnablePreviewFeatures>
100+
</PropertyGroup>
101+
```
102+
103+
When enabled, you can omit the standard `xmlns` and `xmlns:x` declarations from your XAML files. Custom namespaces still require explicit `xmlns:` declarations.
104+
105+
::: moniker-end
106+
46107
## Declare namespaces for types
47108

48109
Types can be referenced in XAML by declaring a XAML namespace with a prefix, with the namespace declaration specifying the Common Language Runtime (CLR) namespace name, and optionally an assembly name. This is achieved by defining values for the following keywords within the namespace declaration:

0 commit comments

Comments
 (0)