Article
11/17/2011

IMarkupExtension<T> Interface

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Provides an interface for XAML markup extension implementations that can be supported by Silverlight XAML processors.

Namespace: System.Xaml
Assembly: System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public Interface IMarkupExtension(Of Out T As Class)

public interface IMarkupExtension<out T>
where T : class

Type Parameters

outT
The type of the object that is returned by the ProvideValue(IServiceProvider) implementation. T must be a reference type and cannot be a value type.

This type parameter is covariant. That is, you can use either the type you specified or any type that is more derived. For more information about covariance and contravariance, see 2678dc63-c7f9-4590-9ddc-0a4df684d42e.

The IMarkupExtension<T> type exposes the following members.

Methods

	Name	Description
	ProvideValue	Returns an object that is provided as the value of the target property for the markup extension.

Top

Remarks

To create a custom markup extension, implement the IMarkupExtension<T> interface and the ProvideValue method.

The Silverlight XAML parser can identify a markup extension if it implements the IMarkupExtension<T> interface and/or derives from MarkupExtension.

In order to be identified, the type name for a custom markup extension must be available in an XML namespace that qualifies the XAML usage. This typically means that you should map a prefix for the XML namespace, using the form that specifies an assembly name and a CLR namespace within that assembly. For more information about XML namespaces for XAML, see Silverlight XAML Namespaces, and Mapping XAML Namespaces as Prefixes. In the XAML usage for your markup extension, the prefix should then immediately follow the left curly brace character { that enters the markup extension sequence.

There are two ways to pass information to a custom markup extension:

Through public properties of the markup extension class.
Through values obtained through the services that are passed via the serviceProvider parameter of ProvideValue once the markup extension is invoked by a XAML processor.

Note:
Unlike WPF, custom markup extensions for Silverlight XAML do not support a positional parameter usage.

Using Properties to Pass Information to a Custom Markup Extension

To use properties to pass information to a custom markup extension, add public properties to the class that implements the custom markup extension. By default, any values passed as named parameters of a markup extension are considered to be of type String. However, you also can use primitive types that the Silverlight native XAML parser type conversion can handle, for example Int32. Each property that you use for passing values to the markup extension must support a public setter. It is this public setter that the Silverlight XAML parser uses to set the values upon markup extension usage. The names of the properties must match exactly the names of the arguments in the markup extension.

Use a comma as a separator between named arguments of a markup extension. Literal commas must be escaped. White space as part of the value for an argument should be enclosed in quotes or escaped.

For example, consider a custom markup extension named FirstMarkupExtension that implements two public properties named Value1 and Value2. Assume that the "local" prefix is used to map the defining assembly and namespace. The ProvideValue method uses the properties to return a string.

The following code shows the FirstMarkupExtension class.

namespace FirstCME
{
    public class FirstMarkupExtension : IMarkupExtension<string>
    {
        public object Value1 { get; set; }
        public object Value2 { get; set; }

        public string ProvideValue(IServiceProvider serviceProvider)
        {
            double _val1 = Convert.ToDouble(Value1);
            double _val2 = Convert.ToDouble(Value2);
            return (_val1 + _val2).ToString();
        }
    }
}

The following shows how to access the FirstMarkupExtension in XAML.

xmlns:local="clr-namespace:FirstCME"
    ...
<TextBlock Text="{local:FirstMarkup Value1=20, Value2=30}" />

When you run this code, the value of 50 is displayed.

Note:
By convention, you typically include an "Extension" suffix for the custom markup extension class name. When you reference the custom markup extension in XAML, the "Extension" suffix is optional.

Returning the Current Markup Extensions Instance

In some cases, you will want to return an instance of the current markup extension. You can do this by having ProvideValue return the this keyword. For example, you may want to return the current markup extension because it contains state or deferred values that should not be evaluated until application run time, whereas the markup extension itself is created at parse time and does not yet have run-time state. Or, perhaps the markup extension's design has multiple properties that change based on ProvideValue behavior at parse time, and it is simpler to package these with the markup extension instance rather than a separate multi-value holding object. An example of a Silverlight markup extension that uses the returns-self pattern is Binding.

Version Information

Silverlight

Supported in: 5

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.