IAmbientProvider Interface

Reference

Definition

Namespace:: System.Xaml

Assembly:: System.Xaml.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Represents a service that can return information items about ambient properties or ambient types to type converters and markup extensions.

public interface class IAmbientProvider

public interface IAmbientProvider

type IAmbientProvider = interface

Public Interface IAmbientProvider

Remarks

This interface represents the service that can help type converters and markup extensions to get the ambient property identifiers for the XAML type system (XamlMember objects). The service can also get the ambient property values from classes. Types can also be ambient; any member that uses that type as its value should be considered ambient.

This service is typically returned through a call to GetService, which is made against a context-specific service provider. The service provider is generally available to contexts that need it, such as the execution code of a value converter. For more information, see Type Converters and Markup Extensions for XAML and Service Contexts Available to Type Converters and Markup Extensions.

About Ambient Properties

An ambient property is a property whose property value should be available to type converter and markup extension usages that exist in the XAML node structure and in the object graph created from it. This is relevant for a XAML processor during the object-writing phase of the load path or the serialization phase of a save path.

In the load path case, the ambient property value might influence the value in the object graph of other properties that exist underneath it in a XAML node structure. When processed as a XAML node stream, the ambient concept means the ambient property value must be available to type converters and markup extensions from StartObject to EndObject. Similarly, a type converter that is used for the save path can use knowledge of the ambient property and its value. Therefore, the XAML that is produced is a better round-trip representation.

For members in general, XAML does not specify the order in which members of an object must be processed. However, any ambient property value must be processed first by the XAML reader so that the type converter and markup extension usages that are contained in other properties can access it through the IAmbientProvider service.

DependsOn is a similar concept that also influences XAML node-processing order. However, DependsOn can only be used for peer member and node relationships; it cannot influence all descendants. Also, DependsOn directly influences object graph property setting; whereas the ambient technique relies on type converters or markup extensions. In the ambient technique, there must also be a specific type converter or markup extension definition that specifies how the ambient property value should be interpreted and applied to the object.

WPF Usage Notes

An ambient property scenario that is illustrated in the WPF feature set is Style.TargetType, which can qualify the necessary property name lookups for other values. In this case, the Style.TargetType value qualifies the Setter.Property values that are located in the XAML nodes underneath it. Setter.Property uses the type converter behavior for a DependencyProperty. This behavior accesses the ambient Style.TargetType value by querying GetFirstAmbientValue from a service context that is available to type converters and markup extensions.

An ambient type scenario that is illustrated in the WPF feature set is ResourceDictionary. ResourceDictionary has a MergedDictionaries property that can contain other ResourceDictionary objects to merge, and the intended order of resource resolution for the merged scenario clashes with the order that types are loaded. ResourceDictionary applies AmbientAttribute so that a XAML processor can correctly process the references in a merged dictionary with StaticResource usages. Specifically, StaticResource is a markup extension, which calls GetAllAmbientValues.

Methods

GetAllAmbientValues(IEnumerable<XamlType>, Boolean, IEnumerable<XamlType>, XamlMember[])	Returns an enumerable set of ambient property information items for the requested set of types and properties.
GetAllAmbientValues(IEnumerable<XamlType>, XamlMember[])	Returns an enumerable set of ambient property information items for the requested set of properties.
GetAllAmbientValues(XamlType[])	Returns an enumerable set of object instances of possible ambient types for the requested types.
GetFirstAmbientValue(IEnumerable<XamlType>, XamlMember[])	Returns a single ambient property information item from the requested set of properties, based on which property is first encountered.
GetFirstAmbientValue(XamlType[])	Returns the first matching object that is a possible ambient type for the requested types.

Applies to

Jaa