This documentation is archived and is not being maintained.

AmbientPropertyValue Class

Reports information about an ambient property, as part of an IAmbientProvider implementation.


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

public class AmbientPropertyValue

The AmbientPropertyValue type exposes the following members.

Public methodAmbientPropertyValueInitializes a new instance of the AmbientPropertyValue class.

Public propertyRetrievedPropertyGets the XAML type system identifier (XamlMember) that represents the ambient property.
Public propertyValueGets the value of the ambient property.

Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)

AmbientPropertyValue represents an information item that is returned by calling an IAmbientProvider service method. The GetAll methods return enumerations or arrays of AmbientPropertyValue items; the GetFirst methods return a single AmbientPropertyValue.

About Ambient Properties

An ambient property is a property whose property value should be available to value converter usage in the XAML node structure and to the object graph underneath it. The ambient concept is relevant for a XAML processor during the object-writing phase of the load path or the serialization phase of a save path.

A type can also be attributed as ambient. In this case, all properties that use the attributed type are reported as ambient.

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

By its language definition, 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 usage 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. It is up to each type converter or markup extension to determine how the ambient property value should be interpreted and applied to the object graph location where the type converter or markup extension is used.

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 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.

.NET Framework

Supported in: 4

.NET Framework Client Profile

Supported in: 4

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.