Prefixes and Mappings for Silverlight Libraries
Microsoft Silverlight will reach end of support after October 2021. Learn more.
This topic describes the concepts of the default Silverlight XAML namespace and the reason why you might need to create mappings for additional XAML namespaces when you define parts of a Silverlight-based application in XAML.
This topic contains the following sections.
- XAML Namespace Mappings
- Prefixes for Mappings of Silverlight Libraries Shown in the Silverlight Documentation
- The Silverlight Default XAML Namespace
- Mapping Other XAML Namespaces from Core Libraries
- XAML for SDK Client Libraries
- XAML for Silverlight Toolkit
- XAML for Silverlight SDK Assemblies when Targeting Silverlight 3
- Related Topics
XAML Namespace Mappings
Silverlight XAML generally uses a default XAML namespace with the URI https://schemas.microsoft.com/winfx/2006/xaml/presentation. This XAML namespace maps to the types defined in core Silverlight assemblies such as System.Windows. However, the .NET Framework Class Library for Silverlight also includes the reference for assemblies and types that are outside the core Silverlight assemblies. Such types are usable in Silverlight XAML, but using them requires that you map the CLR namespaces and assemblies to a prefix and a XAML namespace. Typically you do this in the root element of a XAML page. Then you use that prefix in other XAML usages in that page to reference the types in your mapping. For more information, see Silverlight XAML Namespaces, and Mapping XAML Namespaces as Prefixes. Visual Studio XAML editing includes a feature that presents a dropdown when you define a new xmlns value that helps simplify the mapping process.
XAML usage as well as XAML examples found in the Silverlight documentation typically use certain prefix strings for XAML namespaces as a convention. XAML usages or XAML examples in the Silverlight documentation often omit showing a root element and the mappings for brevity, and instead only show the prefix in usage. The conventional prefix and the mappings that are required can be determined by looking at the table in the next section. For more information on other conventions used for describing XAML syntax in the Silverlight documentation, see XAML Usage Syntax.
The prefixes used in usage and examples align with prefix recommendations that are declared as an assembly-level attribute in the Silverlight SDK client library assemblies as well as possibly assemblies from other sources, and these prefix recommendations are often promoted by development tools.
Prefixes for Mappings of Silverlight Libraries Shown in the Silverlight Documentation
The libraries that define classes that are used in Silverlight XAML can be in one of the following classifications:
Libraries that are part of the Silverlight core install. All Silverlight clients have these libraries, and you never have to distribute or package these libraries in order to access their classes. Examples of a core library are mscorlib, and System.Windows.
Libraries that are part of the Silverlight SDK install. These libraries have a subclassification of SDK client and SDK server libraries; only the SDK client libraries are relevant for XAML. Examples of SDK client libraries are System.Windows.Controls, and System.Windows.Data.
The Silverlight Toolkit. The Silverlight Toolkit provides libraries and other developer resources to Silverlight developer resources, and can provide new releases of the Silverlight Toolkit that are not necessarily synchronized to the Silverlight core release schedule. Sometimes, libraries or individual types that were included in past Silverlight Toolkit releases are incorporated into either SDK client or Silverlight core libraries in a subsequent release. An example of a library that is in the Silverlight Toolkit is System.Windows.Controls.DataVisualization.Toolkit. Note that the types from the Silverlight Toolkit are not documented directly in this documentation set. Instead, the Silverlight Toolkit distributes its own class library documentation. However, the general techniques for XAML usage of Silverlight Toolkit types is discussed in an upcoming section.
Third-party libraries. To reference a type from a third-party library in XAML, you must map a XAML namespace. For more information, see Silverlight XAML Namespaces, and Mapping XAML Namespaces as Prefixes.
The Silverlight Default XAML Namespace
The Silverlight default XAML namespace is identified by https://schemas.microsoft.com/winfx/2006/xaml/presentation when seen in xmlns mappings. For legacy support reasons, the https://schemas.microsoft.com/client/2007/ identifier is treated as equivalent for identifying the Silverlight default XAML namespace.
All of the types that are referenced through the Silverlight default XAML namespace https://schemas.microsoft.com/winfx/2006/xaml/presentation come from one library, System.Windows.
The Silverlight default XAML namespace references multiple CLR namespaces. The following is a list of CLR namespaces that contain types that can be referenced through the Silverlight default XAML namespace, so long as the types in question are found in the Silverlight core library System.Windows:
System.Windows.Automation (for AutomationProperties attached properties)
Mapping Other XAML Namespaces from Core Libraries
There are other types defined by Silverlight core libraries that are sometimes relevant for Silverlight applications and their XAML usage, but which are not defined within the System.Windows assembly. These types are therefore not included in the default XAML namespace. To use types from outside the default XAML namespace, you must map a prefix to a XAML namespace. For the other core libraries, this means that you must map the XAML namespace with a clr-namespace and assembly component, rather than referencing a URI-style namespace identifier.For more information, see Silverlight XAML Namespaces, and Mapping XAML Namespaces as Prefixes.
One set of types that is often used in Silverlight XAML are the CLR types that align to language primitives. For example, String is the CLR type that represents a string. These types are defined in the System CLR namespace and mscorlib assembly. Typically, the prefix sys: is declared for this XAML namespace mapping, and that convention is sometimes used in this documentation, or related Silverlight sample code. For example: xmlns:sys="clr-namespace:System;assembly=mscorlib" is the mapping that can qualify a XAML usage such as <sys:Int32>42</sys:Int32>. Language primitives for XAML usage are often found as part of a resource dictionary, such that frequently-used primitive values exist in only one place in an application. For more information, see Resource Dictionaries.
Which types from within a mapping are actually XAML-usable is a separate concept that is not documented fully in this topic. As a general rule, the type must be public and must support a default constructor. For more information, see XAML and Custom Classes (the same CLR rules that apply to XAML usage of a custom type also apply to any existing class from a core library).
XAML for SDK Client Libraries
As of Silverlight 4, the various libraries that are distributed as part of the Silverlight Client SDK all share a common XAML namespace. The identifier for this XAML namespace is:
https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk
The typical prefix that maps this XAML namespace is sdk:.
If you use the Toolbox and the Silverlight visual designer for Visual Studio 2010, you can drag the controls for types from SDK client libraries into the design surface. If this is the first usage of an SDK client type from that XAML page, Visual Studio 2010 automatically adds a XAML namespace definition to your XAML, on the root element:
xmlns:sdk="https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk"
https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk includes types from the following assemblies, and namespaces from those assemblies:
Assembly |
CLR Namespace |
|---|---|
System.Windows.Controls |
|
System.Windows.Controls.Data |
|
System.Windows.Controls.Data.Input |
|
System.Windows.Controls.Input |
|
System.Windows.Controls.Navigation |
|
System.Windows.Data |
|
.gif "Note") Note: |
|---|
The preceding table is provided for convenience only. The definitive behavior for XAML namespaces is declared with CLR attributes on the assemblies that have an intended XAML usage, and is interpreted by XAML consumers such as the various components of Visual Studio 2010. |
Rather than using Toolbox and the Silverlight visual designer for Visual Studio 2010, you can also manually define your own mapping for https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk, and use that XAML namespace's mapping to reference SDK client types from your XAML.
If you want to use a CLR namespace and SDK client library combination that is not part of https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk, you must specifically map it as documented in the topic Silverlight XAML Namespaces, and Mapping XAML Namespaces as Prefixes.
| Note: |
|---|
System.Windows.Controls.Primitives CLR namespace types from the System.Windows.Controls assembly are not part of the https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk XAML namespace. To use the types that come from the System.Windows.Controls library and the System.Windows.Controls.Primitives CLR namespace, you must map a XAML namespace for them and use a prefix. For more information, see Prefixes and Mappings for Silverlight Libraries. The System.Windows.Controls.Primitives namespace generally contains types that are only used for templating and compositing of the primary SDK client library controls. |
Control Template XAML
Default control templates might still use the Silverlight 3-style mappings, because the default control templates might support Silverlight 3 usages and more current XAML usages simultaneously. The Silverlight XAML parser supports any Silverlight 3-style mapping, so long as it resolves correctly to a backing type in a Silverlight assembly. You can use Silverlight 3-style mappings and URI-style mappings interchangeably in your XAML, even in the same file and to the same type.
The Visual Studio design surface behavior is that if an existing Silverlight 3-style mapping exists to a CLR-namespace/assembly combination, the generated XAML will reuse that mapping. Only if no mapping exists will the sdk: prefix mapping be generated. Thus, if you are working with the default control template starting points as found in this documentation, you can use the existing Silverlight 3-style mappings consistently in your new control template. Visual Studio and related tools or processes (such as F1, markup compile, or run-time loading) can resolve the type using either Silverlight 3-style mappings or URI-style mappings.
XAML for Silverlight Toolkit
As of Silverlight 4, the Silverlight Toolkit libraries also share a common XAML namespace. The identifier for this XAML namespace is:
https://schemas.microsoft.com/winfx/2006/xaml/presentation/toolkit
The typical prefix that maps this XAML namespace is toolkit:.
If you use the Toolbox and the Silverlight visual designer for Visual Studio 2010, you can drag the controls for types from Silverlight Toolkit into the design surface. If this is the first usage of a Toolkit type from that XAML page, Visual Studio 2010 automatically adds a XAML namespace definition to your XAML, on the root element:
xmlns:toolkit="https://schemas.microsoft.com/winfx/2006/xaml/presentation/toolkit"
Because the Silverlight Toolkit types are not documented here, this topic does not provide a table that lists the assembly and CLR namespaces for https://schemas.microsoft.com/winfx/2006/xaml/presentation/toolkit. For more information, see the documentation that is distributed with the Silverlight Toolkit.
You can also use reflection tools such as .NET Reflector to examine the Silverlight Toolkit assemblies, and read the same CLR attributes that the assemblies use to promote their XAML characteristics to designers and markup compilers. Open the assembly in .NET Reflector, disassemble it, and check for the values of any XmlnsDefinitionAttribute applied to the assembly. For XAML usages of Toolkit types that are not within https://schemas.microsoft.com/winfx/2006/xaml/presentation/toolkit, you must specifically map the assembly and defining CLR namespace to a XAML namespace and prefix.
XAML for Silverlight SDK Assemblies when Targeting Silverlight 3
In the Silverlight 3 versions of SDK client assemblies, the XAML namespace https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk is not defined. Instead, the assemblies declare prefixes that are suggested if you create specific XAML namespace mappings to the CLR namespaces in the assembly.
If you use the Toolbox and the Silverlight visual designer for Visual Studio 2010, you can drag the controls for types from SDK client libraries into the design surface. If this is the first usage of an SDK client library type from that XAML page, Visual Studio 2010 automatically adds a XAML namespace definition to your XAML, on the root element. For Silverlight 3, this XAML namespace declaration is defined by providing CLR namespace and assembly for the control's backing type. Different assembly/CLR-namespace combinations from the client libraries have different prefixes. For example, a DataGrid defines and uses a data: prefix when introduced to your XAML, whereas a Calendar defines and uses a controls: prefix.
You can also define mappings manually in the XAML, and the same prefixes are promoted in the Visual Studio UI. For more information on defining XAML namespace mappings manually, see Silverlight XAML Namespaces, and Mapping XAML Namespaces as Prefixes.
In the XAML usage as shown in .NET Framework Class Library for Silverlight reference topics, only the syntax that uses sdk: prefix and https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk XAML namespace is shown. However, you might encounter Silverlight 3-style XAML with the specific CLR-namespace mappings even when targeting Silverlight 4 or later. For example, default control templates might still use the Silverlight 3-style mappings.
The following table lists the XAML namespace prefixes and their mappings that are used by convention, and are promoted by assembly-level attribution in the SDK client libraries for Silverlight 3:
Prefix |
Assembly |
CLR namespace |
|---|---|---|
controls |
System.Windows.Controls |
|
common |
System.Windows.Controls |
|
controlsPrimitives |
System.Windows.Controls |
|
data |
System.Windows.Controls.Data |
|
dataInput |
System.Windows.Controls.Data.Input |
|
dataPrimitives |
System.Windows.Controls.Data |
|
input |
System.Windows.Controls.Input |
|
navigation |
System.Windows.Controls.Navigation |
|
uriMapper |
System.Windows.Controls.Navigation |
Notes
common is relevant for only one class: HierarchicalDataTemplate.
input is relevant for only one class: AutoCompleteBox.
The default templates from the System.Windows.Controls.Data.Input assembly map and use the prefix ctl rather than dataInput.