This documentation is archived and is not being maintained.

IQueryAmbient Interface

Queries for whether a specified property should be treated as ambient in the current scope.

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

public interface IQueryAmbient

The IQueryAmbient type exposes the following members.

Public methodIsAmbientPropertyAvailableQueries for whether a specified named property can be considered ambient in the current scope.

The purpose of an ambient property mechanism is to improve parsing time by informing a XAML object writer to avoid instantiating certain objects, in cases where it is known that the objects are for values that are temporary and not useful for a typical run time application. Normally, XAML lookups or XAML processing of a property get accessor would need to instantiate such objects to fill the object graph representation with ready-to-use values.

IQueryAmbient has one member: IsAmbientPropertyAvailable.

IQueryAmbient is a parallel mechanism to AmbientAttribute. IQueryAmbient is the specialized mechanism that avoids using reflection to determine information, and can also act situationally (a given object could choose to report true or false for IsAmbientPropertyAvailable), whereas the attribute is essentially static analysis). AmbientAttribute is the general mechanism that can be used by XAML object writers and that typically correlates to the dedicated XAML type system properties IsAmbient and IsAmbient.

WPF Implementations of IQueryAmbient

In WPF, IQueryAmbient is used for the resource dictionary lookup process. The lookup process gets successive Resources values throughout the WPF logical tree, working towards the root of the resource scope until either a key is found or the key is determined to not exist in scope. Normally, doing so would require instantiating a ResourceDictionary each time to receive the results. Declaring the contents of Resources as ambient so long as Resources exists optimizes this lookup process. In WPF, this interface is implemented in the following cases:

  • FrameworkElement implements IQueryAmbient.IsAmbientPropertyAvailable to return true for all property names if it contains an existing ResourceDictionary for Resources, and so long as the query is not for the Resources property itself.

  • Style implements the same pattern for its Resources.

  • Application implements the same pattern for its Resources.

  • FrameworkContentElement implements the same pattern for its Resources.

  • FrameworkTemplate implements the same pattern for its Resources. It also reports Template content as ambient but returns false if querying for Template itself.

  • In each of these cases, the relevant Resources property (and Template) are attributed as AmbientAttribute. The typical usage is to query for the properties that are NOT the AmbientAttribute attributed properties of the object that defines the interface. In other words, so long as a resource dictionary exists in order to provide the potential run time value when the object graph is created, any other property besides the resource dictionary's property container can be treated as ambient.

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