Merge pull request #812 from AvaloniaUI/788-documentation-on-custom-markup-extension-including-new-optionsmarkupextensions

luke-whos-here · web-flow · commit 1e1f7eea5701 · 2025-12-19T09:59:41.000Z
788 documentation on custom markup extension including new optionsmarkupextensions
diff --git a/docs/concepts/markupextensions/index.md b/docs/concepts/markupextensions/index.md
@@ -1,12 +1,22 @@
 ﻿---
-id: markupextensions
-title: Markup Extensions
+id: index
+title: Markup extensions
+description: Markup extensions are simple classes that provide values to XAML properties at runtime. They provide a convenient, reusable option for code-based customization of properties.
 ---
 
-A `MarkupExtension` allows code-based customization of setter logic to a target property in a convenient, reusable 
-syntax within XAML. Curly braces are used to differentiate the usage from plain text.
+Markup extensions are simple classes that provide values to XAML properties at runtime. They provide a convenient, reusable option for code-based customization of properties.
 
-Avalonia provides the following:
+## About markup extensions
+
+A classic markup extension is any class that:
+
+- Implements `object? ProvideValue(IServiceProvider?)`
+- Optionally inherits from `MarkupExtension` (not required in Avalonia)
+- Is used from XAML via the `{ns:Extension ...}` syntax
+
+In Avalonia, `ProvideValue` is allowed to return **any** type. This means the result can be strongly typed, as the returned value is assigned directly to the target property.
+
+Avalonia provides the following markup extensions:
 
 | MarkupExtension                                                                                  | Assigns to Property                                                |
 |--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
@@ -21,7 +31,7 @@ Avalonia provides the following:
 
 ## Compiler intrinsics
 
-These technically fall outside of `MarkupExtension`s as part of the XAML compiler, but the XAML syntax is the same.
+These technically fall outside of `MarkupExtension` as part of the XAML compiler, but the XAML syntax is the same.
 
 | Intrinsic | Assigns to Property   |
 |-----------|-----------------------|
@@ -31,14 +41,13 @@ These technically fall outside of `MarkupExtension`s as part of the XAML compile
 | x:Static  | Static member value   |
 | x:Type    | `System.Type` literal |
 
-The `x:True` and `x:False` literals have use cases where the target binding property is `object` and you need 
-to provide a boolean. In these scenarios that lack type information, providing "True" remains a `string`.
+The `x:True` and `x:False` literals have use cases where the target binding property is `object` and you need to provide a boolean. In these scenarios that lack type information, providing "True" remains a `string`.
 
 ```xml
 <Button Command="{Binding SetStateCommand}" CommandParameter="{x:True}" />
 ```
 
-## Creating MarkupExtensions
+## Creating markup extensions
 
 Derive from `MarkupExtension` or add one of the following signatures which are supported via duck-typing:
 
@@ -49,11 +58,44 @@ object ProvideValue();
 object ProvideValue(IServiceProvider provider);
 ```
 
-When strong types are used instead of `object`, you will receive compile-time errors when there is a mismatch in the 
-XAML use of constructor parameters, properties, or the return value in `ProvideValue`. When returning `object`, the 
-actual type returned must match the target property's type else an `InvalidCastException` is thrown at runtime.
+Here is a basic example with a markup extension used for localization:
+
+```csharp
+public class LocExtension
+{
+    public string Key { get; set; } = "";
+
+    public string ProvideValue(IServiceProvider serviceProvider)
+    {
+        // Simplified localization lookup
+        return LocalizationService.GetString(Key) ?? Key;
+    }
+}
+```
+
+```xml
+<TextBlock Text="{local:Loc Key=WelcomeMessage}" />
+```
+
+When strong types are used instead of `object`, you will receive compile-time errors when there is a mismatch in the  XAML use of constructor parameters, properties, or the return value in `ProvideValue`. When returning `object`, the actual type returned must match the target property's type, else an `InvalidCastException` is thrown at runtime.
 
-### Receiving Literal Parameters
+### Using `IServiceProvider`
+
+The `IServiceProvider` passed to `ProvideValue` exposes XAML context services, enabling the extension to understand where it is used.
+
+Common standard services include:
+
+- **`IProvideValueTarget`** — gives access to the target object and property.
+- **`IRootObjectProvider`** — provides the XAML document’s root object.
+
+Avalonia also provides additional, XAML-IL specific services:
+
+- **`IAvaloniaXamlIlParentStackProvider`** — exposes the parent object stack during XAML parsing.
+- **`IAvaloniaXamlIlXmlNamespaceInfoProvider`** — provides namespace metadata.
+
+These services are optional, but essential for more advanced or context-aware extensions.
+
+### Receiving literal parameters
 
 When parameters are required, use a constructor to receive each parameter in order.
 
@@ -84,13 +126,11 @@ public class MultiplyLiteral
 <TextBlock Text="This has FontSize=40" FontSize="{namespace:MultiplyLiteral 10, 8, Third=0.5}" />
 ```
 
-### Receiving Parameters From Bindings
+### Receiving parameters from bindings
+
+A common scenario is to transform data coming in from a binding and updating the target property. When all parameters  come from bindings, this is straightforward by creating a `MultiBinding` with an `IMultiValueConverter`.
 
-A common scenario is wanting to transform data coming in from a binding and updating the target property. When all parameters 
-come from bindings, this is somewhat straightforward by creating a `MultiBinding` with an `IMultiValueConverter`. In the 
-sample below, `MultiplyBinding` requires two bound parameters. If a mix of literal and bound parameters is necessary, 
-creating an `IMultiValueConverter` would allow for passing of literals as constructor or `init` parameters. `BindingBase` 
-allows for both `CompiledBinding` and `ReflectionBinding` to be used, but does not allow literals.
+In the  sample below, `MultiplyBinding` requires two bound parameters. If a mix of literal and bound parameters is necessary,  creating an `IMultiValueConverter` would allow for passing of literals as constructor or `init` parameters. `BindingBase` allows for both `CompiledBinding` and `ReflectionBinding` to be used, but does not allow literals.
 
 ```csharp
 public class MultiplyBinding
@@ -123,15 +163,24 @@ public class MultiplyBinding
 ```
 
 :::info
-
 An alternate approach is to return an `IObservable<T>.ToBinding()` instead.
-
 :::
 
-### Returning Parameters
+### Returning parameters
+
+Avalonia’s markup extension model is flexible: `ProvideValue` may return anything.
+
+This includes:
+
+- Static .NET object
+- Typed .NET object, which can be validated at compile time when assigned to a property
+- **Binding** instances
+- **Observables (`IObservable<T>`)** for dynamic, reactive values
+
+Binding-returning or observable-returning markup extensions are supported and integrate with Avalonia’s property and data-binding systems.
+
+To make a markup extension compatible with multiple target property types, you can set `ProvideValue` to return an `object` in its method signature, so that each type can be handled individually.
 
-To make a `MarkupExtension` compatible with multiple target property types, return an `object` and handle each 
-supported type individually.
 
 ```csharp
 public object ProvideValue(IServiceProvider provider)
diff --git a/docs/concepts/markupextensions/options-markup-extensions.md b/docs/concepts/markupextensions/options-markup-extensions.md
@@ -0,0 +1,73 @@
+---
+id: options-markup-extensions
+title: Options markup extensions
+description: An options markup extension is a special type of markup extension, specialized for switch-like expressions.
+---
+
+`OptionsMarkupExtension` is a special type of markup extension, specialized for switch-like expressions. Its purpose is to provide optimization by removing branches that will never be used, allowing trimming by the compiler.
+
+## `OnPlatform` markup extension
+
+One example of an options markup extension is the built-in `OnPlatform` markup extension. This markup extension defines values per runtime platform (Windows, macOS, Linux, etc.) to optimize branches, selecting only those relevant to the platform being compiled for. 
+
+With `OnPlatform`, you can, for instance, use the `Markdown` control on Linux and the `WebView` control on other platforms. The unused control would be excluded, thus reducing the binary size.
+
+## Creating custom options markup extensions
+
+Here is an example of a custom implementation with `RuntimeInformation.ProcessArchitecture`. As shown in this example, we recommend using compiler flags or .NET runtime APIs that are effectively constant.
+
+```csharp
+public class ArchitectureExtension : IAddChild<On<object>>
+{
+    [MarkupExtensionOption(nameof(X86))] public object? X86 { get; set; }
+    [MarkupExtensionOption(nameof(X64))] public object? X64 { get; set; }
+    [MarkupExtensionOption(nameof(Arm))] public object? Arm { get; set; }
+    [MarkupExtensionOption(nameof(Arm64))] public object? Arm64 { get; set; }
+    [MarkupExtensionOption(nameof(Wasm))] public object? Wasm { get; set; }
+
+    [Content]
+    [MarkupExtensionDefaultOption]
+    public object? Default { get; set; }
+
+    public static bool ShouldProvideOption(string option)
+    {
+        var currentArch = RuntimeInformation.ProcessArchitecture;
+        return option switch
+        {
+            nameof(X86) => currentArch == Architecture.X86,
+            nameof(X64) => currentArch == Architecture.X64,
+            nameof(Arm) => currentArch == Architecture.Arm,
+            nameof(Arm64) => currentArch == Architecture.Arm64,
+            nameof(Wasm) => currentArch == Architecture.Wasm,
+            _ => false,
+        };
+    }
+
+    // Needed for the compiler.
+    public void AddChild(On<object> child) {}
+    public object? ProvideValue() => null;
+}
+```
+
+This class defines several options that are selected through the `ShouldProvideOption` static method. You can then set the options in XAML, like so:
+
+```xml
+<Border Background="{local:Architecture Default=White, X64=Green, Arm64=Red, Wasm=Blue}" />
+```
+
+### What’s the difference?
+
+The example above, in a non-optimized .NET build, is equivalent to the following code.
+
+```csharp
+border.Background = ArchitectureExtension.ShouldProvideOption("X64") ? Brushes.Green
+     : ArchitectureExtension.ShouldProvideOption("Arm64") ? Brushes.Red
+     : ArchitectureExtension.ShouldProvideOption("Wasm") ? Brushes.Blue
+     : Brushes.White;
+```
+
+Once optimized and trimmed for specific platform architecture, it is reduced to the following instead.
+
+```csharp
+border.Background = Brushes.Red; // assuming app was compiled with dotnet publish -r win-arm64;
+```
diff --git a/sidebars.js b/sidebars.js
@@ -461,7 +461,17 @@ const sidebars = {
             'concepts/the-mvvm-pattern/avalonia-ui-and-mvvm',
           ],
         },
-        'concepts/markupextensions',
+        {
+          'type': 'category',
+          'label': 'Markup extensions',
+          'link': {
+            'type': 'doc',
+            'id': 'concepts/markupextensions/index',
+          },
+          'items': [
+            'concepts/markupextensions/options-markup-extensions',
+          ],
+        },
         {
           'type': 'category',
           'label': 'ReactiveUI',
