Silverlight XAML Namespaces, and Mapping XAML Namespaces as Prefixes
Microsoft Silverlight will reach end of support after October 2021. Learn more.
This topic further explains the presence and purpose of the two XML / XAML namespace (xmlns) mappings as found in the root element of most Silverlight XAML files. It also describes how to produce similar mappings for using elements that are defined in your own code, and/or within separate assemblies such as those that are distributed as client libraries in the Silverlight SDK.
This topic contains the following sections.
- The Silverlight and XAML Language XAML Namespace Declarations
- Other XAML Namespaces
- Mapping Prefixes to CLR Namespaces and Assemblies
- Applying XAML Namespace Attributes to Custom Assemblies
- Related Topics
The Silverlight and XAML Language XAML Namespace Declarations
Within the root element of many XAML files, there are two xmlns declarations. The first declaration maps the Silverlight core XAML namespace as the default:
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
Notice that this is the same XAML namespace identifier that WPF uses for its default XAML namespace.
The second declaration maps a separate XAML namespace for the XAML-defined language elements, mapping it (typically) to the x: prefix:
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
This xmlns value is also identical to the one used by WPF.
The relationship between these declarations is that XAML is a language definition, and Silverlight is one implementation that uses XAML as a language and defines a specific vocabulary where its types are referenced in XAML. Silverlight in particular uses a strict subset of XAML language elements. The XAML language specifies certain language elements, and each of these should be accessible through XAML processor implementations working against the XAML namespace. Silverlight also uses a subset of the set of XAML language elements that are implemented in WPF.
The x: mapping convention for the XAML language XAML namespace is followed by project templates, sample code, and the documentation of language features within this documentation set. This XAML namespace defines several commonly used features that are necessary even for basic Silverlight-based applications. For example, in order to join any code-behind to a XAML file through a partial class, you must name that class as the x:Class attribute in the root element of the relevant XAML file. Or, any element as defined in a XAML page that you wish to access as a keyed resource in a ResourceDictionary must have the x:Key attribute set on the object element in question.
Other XAML Namespaces
In addition to the default Silverlight namespace, and the XAML language XAML namespace x:, you might also see other mapped XAML namespaces in the initial default XAML for Silverlight applications as generated by Visual Studio.
d: (https://schemas.microsoft.com/expression/blend/2008)
The d: XAML namespace is intended for designer support, specifically designer support in the XAML design surfaces of Microsoft Visual Studio and Microsoft Expression Blend. The d: XAML namespace enables designer attributes on XAML elements. These designer attributes only affect the design aspects of how XAML behaves. The designer attributes are ignored when the same XAML is loaded by the XAML parser in the Silverlight run-time, and the application runs. Generally, the designer attributes are valid on any XAML element, but in practice there are only certain scenarios where applying a designer attribute yourself is appropriate. In particular, many of the designer attributes are intended to provide a better experience for interacting with data contexts and data sources while you are working with XAML and applications that use data binding. For more information, see Design-Time Attributes in the Silverlight Designer.
mc: (https://schemas.openxmlformats.org/markup-compatibility/2006)
mc: indicates and supports a markup compatibility mode for reading XAML. Typically, the d: prefix is associated with the attribute mc:Ignorable. This technique enables run time XAML parsers to ignore the design attributes, as described previously.
vsm:
vsm: is a prefix that is sometimes seen in XAML templates. For legacy compatibility reasons, vsm: was sometimes used to demark any XAML references to the VisualStateManager class and related attached properties. For more information, see Customizing the Appearance of an Existing Control by Using a ControlTemplate.
sdk: (https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk)
sdk: is an attribute-promoted prefix for the XAML namespace https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk. That XAML namespace is shared by various libraries that are distributed with the Silverlight SDK, as part of client libraries for providing additional Silverlight behavior and controls. Note that in order to use this XAML namespace, you must be targeting Silverlight 4 or later. For more information, see Prefixes and Mappings for Silverlight Libraries.
Mapping Prefixes to CLR Namespaces and Assemblies
You can map a XAML namespace to an assembly and to the CLR namespaces within it by using a series of tokens within an xmlns prefix declaration. This is similar to how the XAML namespace value is mapped to the x: prefix, but in this case you explicitly declare the assembly and CLR namespace within that assembly that contains the types you want to use in XAML.
The syntax takes the following possible named tokens and following values:
clr-namespace: The common language runtime (CLR) namespace declared within the assembly that contains the public types to expose to XAML usage.
assembly= The assembly that defines types in the referenced CLR namespace. Do not include the file extension part of an assembly name.
Note that the character separating the clr-namespace token from its value is a colon (:) whereas the character separating the assembly token from its value is an equals sign (=). The character to use between these two tokens is a semicolon. Do not include whitespace anywhere within the mapping value. For example:
xmlns:custom="clr-namespace:SDKSample;assembly=SDKSampleLibrary"
It is possible that different assemblies each declare types in a shared CLR namespace. If this is the case, you still need to define separate mappings for each of the assemblies, but referncing the same clr-namespace: value.
Mapping to SDK Client Library Assemblies
The SDK client library assemblies use a shared XAML namespace, which has the following identifier: https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk. Typically this XAML namespace is mapped to the prefix sdk. For more information, see Prefixes and Mappings for Silverlight Libraries.
.gif "Note") Note: |
|---|
Mapping the prefix is not all that is necessary to use classes from the SDK client libraries. You must also distribute or otherwise reference the SDK client library assemblies as part of your application structure and deployment settings. For more information, see Application Structure. |
Mapping to Custom Assemblies
You can map prefixes to reference the types that are contained in any custom assembly that you create and then distribute as part of your Silverlight-based application. This same procedure might apply to any third-party assemblies that your application might distribute, such as libraries that provide third-party controls.
For example, to map a custom1 prefix that enables you to reference a CustomClasses namespace that you define in an assembly named Custom, and use classes from that namespace/assembly as object elements in XAML, your XAML page should include the following mapping on the root element:
xmlns:custom1="clr-namespace:CustomClasses;assembly=Custom"
| Note: |
|---|
If there is a path required to access the assembly based on the site origin, that path should not be included in the string following Assembly=. Paths to assemblies are only relevant for AssemblyPart.Source and ExtensionPart.Source values. |
Visual Studio XAML editing includes a feature that presents a dropdown when you define a new xmlns value in XAML that helps simplify the mapping process. For best results, reference the relevant assembly from the project first, then map a prefix from it.
Mapping to Current Assemblies
assembly can be omitted if the clr-namespace referenced is defined within the same assembly as the application code that references the custom classes (this is generally the EntryPointAssembly). Or, an equivalent syntax for altogether omitting assembly information for mapping the same assembly is to specify assembly=, with no string token following the equals sign.
Partial classes do not need to be mapped; only classes that are not the partial class of a page in your application need to be mapped if you intend to reference them as elements in XAML.
Applying XAML Namespace Attributes to Custom Assemblies
If you are an assembly author, you can apply CLR attributes to the assembly. Specialized attributes can declare XAML namespace information for consumers of the assembly’s XAML-accessible API. This enables mapping a custom XAML namespace through an identifier such as a URI, rather than mapping a specific assembly name and CLR namespace for all XAML usages. Also, multiple CLR namespaces within the assembly and even multiple assemblies can share the XAML namespace definition. APIs from several CLR namespace/assembly combinations can be subsumed into a single XAML namespace for ease of use, and clarity of markup. This technique is used by the Silverlight core assemblies, in order to declare the Silverlight default XAML namespace, and also by Silverlight client SDK assemblies, which share the namespace mapped to sdk:.
There are two CLR attributes that are relevant for custom assemblies and custom XAML namespace declaration. The attributes are assigned in the assembly information in the project for the custom assembly (assemblyInfo.cs or assemblyinfo.vb), although in Visual Studio you do not necesarily directly edit the assemblyinfo file.
XmlnsDefinitionAttribute assigns a CLR namespace to a XAML namespace identifier. The XAML namespace identifier is typically provided as a URI string, as a parallel to the XML convention of providing xmlns information through URI identifiers that relate in some way to the originator of the namespace APIs. The assembly that contains the APIs is implicitly the assembly where the attribute is applied. The CLR namespace to associate with the XAML namespace is declared in string form. A typical pattern is to declare multiple XmlnsDefinitionAttribute attributes, each of which specifies a different CLR namespace but the same XAML namespace identifier. Another possible pattern is to declare the same CLR namespace for more than one XAML namespace identifier; this is useful if your assembly supports multiple XAML vocabularies (and you want a different XAML namespace for each vocabulary), if you have XAML namespaces that represent an ongoing versioning strategy, or if you want to maintain equivalence of a base XAML namespace and a subset or superset of that namespace based on how types are organized in your libraries.
XmlnsPrefixAttribute is another CLR attribute that is typically applied only if you already have a XmlnsDefinitionAttribute that references one or more XAML namespace identifiers for the assembly. XmlnsPrefixAttribute associates a recommended prefix string with a XAML namespace identifier. The prefix can be hinted by XAML editing components in design environments, whenever the user creates or selects xmlns mappings in a XAML file. This practice promotes a consistent markup representation, and enables scenarios such as exchanging XAML fragments between different XAML files because the convention for which prefix to use for that XAML element is already established by its owning assembly.
For example, the following assembly-definition code provides the XAML namespace definition for a XAML namespace identified as https://www.contoso.com/CustomXamlLib. The assembly contains two CLR namespaces that provide type backing for this XAML namespace. The prefix "custom" is promoted as the prefix to use whenever the XAML namespace https://www.contoso.com/CustomXamlLib is mapped in a XAML file.
See Also