AmbientAttribute Class
 

Specifies that a property or type should be treated as ambient. The ambient concept relates to how XAML processors determine type owners of members.

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

Inheritance Hierarchy
SystemObject
   SystemAttribute
    System.Windows.MarkupAmbientAttribute

Syntax
[AttributeUsageAttribute(AttributeTargets.Class | AttributeTargets.Method | AttributeTargets.Property, 
	Inherited = true)]
public sealed class AmbientAttribute : Attribute
[AttributeUsageAttribute(AttributeTargets::Class | AttributeTargets::Method | AttributeTargets::Property, 
	Inherited = true)]
public ref class AmbientAttribute sealed : Attribute
[<Sealed>]
[<AttributeUsageAttribute(AttributeTargets.Class | AttributeTargets.Method | AttributeTargets.Property,
    Inherited = true)>]
type AmbientAttribute = 
    class
        inherit Attribute
    end
<AttributeUsageAttribute(AttributeTargets.Class Or AttributeTargets.Method Or AttributeTargets.Property,
	Inherited := True)>
Public NotInheritable Class AmbientAttribute
	Inherits Attribute
Constructors
NameDescription
System_CAPS_pubmethod AmbientAttribute

Initializes a new instance of the AmbientAttribute class.

Properties
NameDescription
System_CAPS_pubproperty

When implemented in a derived class, gets a unique identifier for this Attribute.(Inherited from Attribute.)

Methods
NameDescription
System_CAPS_pubmethod Equals

This API supports the product infrastructure and is not intended to be used directly from your code. Returns a value that indicates whether this instance is equal to a specified object.(Inherited from Attribute.)

System_CAPS_pubmethod GetHashCode

Returns the hash code for this instance.(Inherited from Attribute.)

System_CAPS_pubmethod GetType

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethod IsDefaultAttribute

When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.(Inherited from Attribute.)

System_CAPS_pubmethod Match

When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.(Inherited from Attribute.)

System_CAPS_pubmethod ToString

Returns a string that represents the current object.(Inherited from Object.)

Explicit Interface Implementations
NameDescription
System_CAPS_pubinterface System_CAPS_privmethod _AttributeGetIDsOfNames

Maps a set of names to a corresponding set of dispatch identifiers.(Inherited from Attribute.)

System_CAPS_pubinterface System_CAPS_privmethod _AttributeGetTypeInfo

Retrieves the type information for an object, which can be used to get the type information for an interface.(Inherited from Attribute.)

System_CAPS_pubinterface System_CAPS_privmethod _AttributeGetTypeInfoCount

Retrieves the number of type information interfaces that an object provides (either 0 or 1).(Inherited from Attribute.)

System_CAPS_pubinterface System_CAPS_privmethod _AttributeInvoke

Provides access to properties and methods exposed by an object.(Inherited from Attribute.)

Remarks

An ambient property is a property where the value is expected to be available in the parser context when creating an object graph, but where typical type-member lookup is suspended for purposes of the immediate XAML node set being created. There are two main scenarios for the ambient concept:

  • Some other property of the same object influences and qualifies how that object-property lookup should work.

  • The property represents a larger deferral mechanism and the ambient capabilities for looking up a member value extend to all objects contained within the current object.

This attribute can be applied to specific properties that have expected containers that enable an ambient property lookup behavior, or can be applied to a class to enable the ambient property behavior in all cases of that value type for a property.

AmbientAttribute can also be applied to a CLR method, to support attributing a XAML attachable property as ambient. This is potentially necessary because in a CLR implementation a XAML attached property is implemented/represented to reflection as an accessor pattern with get and set methods. No actual CLR property to attribute exists, so restricting usage for AttributeTargets to Property would not have enabled specifying an attachable member as ambient. For an attachable member that you want to report as ambient, attribute the get accessor. You should not attempt to attribute methods that are not specifically support methods of attachable members.

In previous versions of the .NET Framework, this class existed in the WPF-specific assembly WindowsBase. In .NET Framework 4, AmbientAttribute is in the System.Xaml assembly. For more information, see Types Migrated from WPF to System.Xaml.

Ambient types (types where AmbientAttribute is applied at type level) can be used for certain XAML processing situations where the type of a property needs to be resolved out of order.

Object Writer Scenarios

If you are defining a XAML object writer, and you encounter a property, method or type where AmbientAttribute is applied, you typically must access a service to determine the intended ambient property lookup behavior that is needed for writing out objects. For more information, see IAmbientProvider.

Value Converters

Type converters or markup extensions might need to know the ambient information in order to process properties that represent indirect type mappings, such as properties that specify members or types by string names with or without qualification. In this scenario, AmbientAttribute is not intended to be used directly for value converter code logic. Rather, the value converter should rely on the XAML writer processing behavior, which will pass IAmbientProvider in its service contexts to your value converter methods when called.

WPF Scenarios for AmbientAttribute
  • A property of a Style ( ) can qualify the necessary property name lookups that are needed to find the backing references for property names in values.

  • All content within a Resources property (items of a ResourceDictionary) as well as template content, should be able to access other peers as values. Declaring the entire Resources property as ambient invokes logic that enables this in the WPF XAML parser.

See ResourceDictionary for an example of a scenario for setting AmbientAttribute at type level.

Version Information
.NET Framework
Available since 3.0
Thread Safety

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

Return to top