Custom Markup Extensions

Analogy categoryAnalogies

What a Markup Extension Is

A markup extension is any class deriving from MarkupExtension that XAML parsers recognize inside curly-brace syntax, like {Binding Path=Name} or {StaticResource MyBrush} — both are markup extensions built into the framework. Writing a custom one means subclassing MarkupExtension and overriding ProvideValue(IServiceProvider serviceProvider), which returns the actual object the parser substitutes at the location where the extension was used.

🏏

Cricket analogy: A markup extension is like the shorthand notation 'c Dhoni b Bumrah' on a scorecard — a compact bracketed syntax that the scoring system parses and expands into a full dismissal record, the way {Binding} expands into a full binding object.

Building a Simple Custom Extension

A minimal custom extension exposes its configuration as constructor parameters or public properties — for example an EnumValuesExtension(Type enumType) that returns Enum.GetValues(enumType) — and the XAML parser instantiates the extension class itself, calls any property setters matched to attributes inside the curly braces, then calls ProvideValue once to get the final value. Because the extension class is instantiated fresh for every usage site by default, expensive setup logic in the constructor runs once per {MyExtension} occurrence in the document.

🏏

Cricket analogy: A custom extension like EnumValuesExtension is like a scoring template that gets a fresh copy filled out for every single dismissal entered on the scorecard, so setup work like formatting the header happens anew for each entry.

Using IServiceProvider for Context

The IServiceProvider passed into ProvideValue can be queried for services like IProvideValueTarget, which reveals which object and property the extension is being applied to, enabling context-aware extensions — for instance a markup extension that inspects the target property's type and returns a differently formatted value depending on whether it's being applied to a Brush property or a string property. This is the same mechanism {Binding} itself uses internally to know which DependencyProperty it's feeding.

🏏

Cricket analogy: Querying IProvideValueTarget is like a substitute fielder checking the electronic scoreboard to see exactly which position they're filling in for before running onto the field, so they know whether to stand at slip or at deep cover.

When to Use a Markup Extension vs. a Converter

A custom markup extension is the right tool when you need to produce a value at parse time from static or design-time-available data — like looking up a localized string by key, or generating a color from a hex constant — whereas an IValueConverter is the right tool when transforming a value that flows through a live Binding at runtime, such as converting a boolean into a Visibility. Reaching for a markup extension when a simple StaticResource or converter would do adds unnecessary complexity, since custom extensions require compiled C# code and can't be edited by a XAML-only designer tool.

🏏

Cricket analogy: Choosing a markup extension for parse-time lookups is like consulting a printed fixture list to fill in tomorrow's opponent before the match starts, whereas a converter is like the live scoreboard operator translating each ball's outcome into a run tally as play happens.

csharp

public class EnumValuesExtension : MarkupExtension
{
    public Type EnumType { get; set; }

    public EnumValuesExtension() { }
    public EnumValuesExtension(Type enumType) => EnumType = enumType;

    public override object ProvideValue(IServiceProvider serviceProvider)
    {
        if (EnumType == null || !EnumType.IsEnum)
            throw new InvalidOperationException("EnumType must be set to an enum type.");

        return Enum.GetValues(EnumType);
    }
}

Because the XAML parser instantiates a fresh extension object at every usage site, it's safe (and normal) to store per-usage configuration in constructor parameters or properties — just avoid relying on any shared mutable state across separate {MyExtension} occurrences in the same document.

Every custom markup extension must expose either a public parameterless constructor or a public constructor whose parameters match the positional arguments used in curly-brace syntax — otherwise the XAML parser can't instantiate it and you'll get a XamlParseException at load time.

A custom markup extension subclasses MarkupExtension and overrides ProvideValue(IServiceProvider).
The parser instantiates a fresh extension object at every usage site by default, calling property setters before ProvideValue.
IServiceProvider can supply IProvideValueTarget, revealing which object/property the extension targets for context-aware behavior.
{Binding} and {StaticResource} are themselves built-in markup extensions using the same MarkupExtension base class.
Use a markup extension for parse-time/static-data lookups; use an IValueConverter for runtime-flowing bound values.
Every custom extension needs a constructor whose signature matches how it's invoked in curly-brace syntax.
Markup extensions require compiled C# code, adding complexity compared to a plain StaticResource or converter.