IMessageFilterTable<TFilterData> Interface

Definition

An interface that defines the contract that a filter table must implement to inspect messages with query criteria derived from one or more filters.

generic <typename TFilterData>
public interface class IMessageFilterTable : System::Collections::Generic::ICollection<System::Collections::Generic::KeyValuePair<System::ServiceModel::Dispatcher::MessageFilter ^, TFilterData>>, System::Collections::Generic::IDictionary<System::ServiceModel::Dispatcher::MessageFilter ^, TFilterData>, System::Collections::Generic::IEnumerable<System::Collections::Generic::KeyValuePair<System::ServiceModel::Dispatcher::MessageFilter ^, TFilterData>>
public interface IMessageFilterTable<TFilterData> : System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<System.ServiceModel.Dispatcher.MessageFilter,TFilterData>>, System.Collections.Generic.IDictionary<System.ServiceModel.Dispatcher.MessageFilter,TFilterData>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<System.ServiceModel.Dispatcher.MessageFilter,TFilterData>>
type IMessageFilterTable<'FilterData> = interface
    interface IDictionary<MessageFilter, 'FilterData>
    interface ICollection<KeyValuePair<MessageFilter, 'FilterData>>
    interface seq<KeyValuePair<MessageFilter, 'FilterData>>
    interface IEnumerable
Public Interface IMessageFilterTable(Of TFilterData)
Implements ICollection(Of KeyValuePair(Of MessageFilter, TFilterData)), IDictionary(Of MessageFilter, TFilterData), IEnumerable(Of KeyValuePair(Of MessageFilter, TFilterData))

Type Parameters

TFilterData

The type of data associated with each filter in the table.

Derived
Implements

Remarks

The filter table is a core component of the filter engine. The primary use of the filter engine in Windows Communication Foundation (WCF) is to match application logic to messages by finding all the filters that match a message.

A filter table allows multiple filters to be matched against a single message more efficiently than they can be matched separately. A filter table associates filter data with filters. The table is a collection of key-value pairs, where the key is the MessageFilter, and the value is the associated filter data. Filter data can be any data of the type specified in the generic parameter and can be used to specify what actions to take if a message is matched by a filter in the table.

Filter table entries can be accessed using the IDictionary<TKey,TValue> functionality that IMessageFilterTable<TFilterData> inherits.

Note that a filter instance can only be added to a given IMessageFilterTable<TFilterData> once. To add multiple instances of this filter to the same filter table, use a filter constructor to create additional instances.

A filter matches a message when the message satisfies the query criteria of the filter. There are four overloaded matching methods. The data returned is either the filter data or the MessageFilter objects themselves. This data is returned whether multiple matches are allowed or only a single match. The following table shows this information for each overload.

Method Name Matches Data Returned
GetMatchingValue Single FilterData
GetMatchingFilter Single MessageFilter
GetMatchingValues Multiple FilterData
GetMatchingFilters Multiple MessageFilter objects

Each method contains two overloads. The difference between the two overloads is that one takes a Message parameter and is not permitted to examine the contents of the body; the other takes a MessageBuffer parameter and can examine any part of the message. If you call a method with the message parameter, and the filter table contains a filter that examines the content of the message body, an exception is thrown. If you are unsure about the filters in a table, call the overload that takes a message buffer.

Message headers are automatically buffered and can be inspected by a filter without being consumed. But if the body is to be inspected by a filter, then the entire message must be buffered because an unbuffered message body is consumed by a query and its contents destroyed.

The following classes implement IMessageFilterTable<TFilterData>:

Properties

Count

Gets the number of elements contained in the ICollection<T>.

(Inherited from ICollection<T>)
IsReadOnly

Gets a value indicating whether the ICollection<T> is read-only.

(Inherited from ICollection<T>)
Item[TKey]

Gets or sets the element with the specified key.

(Inherited from IDictionary<TKey,TValue>)
Keys

Gets an ICollection<T> containing the keys of the IDictionary<TKey,TValue>.

(Inherited from IDictionary<TKey,TValue>)
Values

Gets an ICollection<T> containing the values in the IDictionary<TKey,TValue>.

(Inherited from IDictionary<TKey,TValue>)

Methods

Add(T)

Adds an item to the ICollection<T>.

(Inherited from ICollection<T>)
Add(TKey, TValue)

Adds an element with the provided key and value to the IDictionary<TKey,TValue>.

(Inherited from IDictionary<TKey,TValue>)
Clear()

Removes all items from the ICollection<T>.

(Inherited from ICollection<T>)
Contains(T)

Determines whether the ICollection<T> contains a specific value.

(Inherited from ICollection<T>)
ContainsKey(TKey)

Determines whether the IDictionary<TKey,TValue> contains an element with the specified key.

(Inherited from IDictionary<TKey,TValue>)
CopyTo(T[], Int32)

Copies the elements of the ICollection<T> to an Array, starting at a particular Array index.

(Inherited from ICollection<T>)
GetEnumerator()

Returns an enumerator that iterates through a collection.

(Inherited from IEnumerable)
GetMatchingFilter(Message, MessageFilter)

Returns a value that indicates whether the match criterion of exactly one filter in the table is satisfied by the specified message, and returns that filter in an out parameter.

GetMatchingFilter(MessageBuffer, MessageFilter)

Returns a value that indicates whether the match criterion of exactly one filter in the table is satisfied by the specified message or buffered message, and returns that filter in an out parameter.

GetMatchingFilters(Message, ICollection<MessageFilter>)

Returns a value that indicates whether the match criterion of a filter in the table is satisfied by the specified message, and adds the matching filters to a collection.

GetMatchingFilters(MessageBuffer, ICollection<MessageFilter>)

Returns a value that indicates whether the match criterion of a filter in the table is satisfied by the specified buffered message, and adds the matching filters to a collection.

GetMatchingValue(Message, TFilterData)

Returns a value that indicates whether the match criterion of exactly one filter in the table is satisfied by the specified message, and adds the matching filter data to a collection.

GetMatchingValue(MessageBuffer, TFilterData)

Returns a value that indicates whether the match criterion of exactly one filter in the table is satisfied by the specified buffered message, and adds the matching filter data to a collection.

GetMatchingValues(Message, ICollection<TFilterData>)

Returns a value that indicates whether the match criterion of at least one filter in the table is satisfied by the specified message, and adds the FilterData of the matching filters to a collection.

GetMatchingValues(MessageBuffer, ICollection<TFilterData>)

Returns a value that indicates whether the match criterion of at least one filter in the table is satisfied by the specified buffered message, and adds the FilterData of the matching filters to a collection.

Remove(TKey)

Removes the element with the specified key from the IDictionary<TKey,TValue>.

(Inherited from IDictionary<TKey,TValue>)
TryGetValue(TKey, TValue)

Gets the value associated with the specified key.

(Inherited from IDictionary<TKey,TValue>)

Extension Methods

CopyToDataTable<T>(IEnumerable<T>)

Returns a DataTable that contains copies of the DataRow objects, given an input IEnumerable<T> object where the generic parameter T is DataRow.

CopyToDataTable<T>(IEnumerable<T>, DataTable, LoadOption)

Copies DataRow objects to the specified DataTable, given an input IEnumerable<T> object where the generic parameter T is DataRow.

CopyToDataTable<T>(IEnumerable<T>, DataTable, LoadOption, FillErrorEventHandler)

Copies DataRow objects to the specified DataTable, given an input IEnumerable<T> object where the generic parameter T is DataRow.

Cast<TResult>(IEnumerable)

Casts the elements of an IEnumerable to the specified type.

OfType<TResult>(IEnumerable)

Filters the elements of an IEnumerable based on a specified type.

AsParallel(IEnumerable)

Enables parallelization of a query.

AsQueryable(IEnumerable)

Converts an IEnumerable to an IQueryable.

Ancestors<T>(IEnumerable<T>)

Returns a collection of elements that contains the ancestors of every node in the source collection.

Ancestors<T>(IEnumerable<T>, XName)

Returns a filtered collection of elements that contains the ancestors of every node in the source collection. Only elements that have a matching XName are included in the collection.

DescendantNodes<T>(IEnumerable<T>)

Returns a collection of the descendant nodes of every document and element in the source collection.

Descendants<T>(IEnumerable<T>)

Returns a collection of elements that contains the descendant elements of every element and document in the source collection.

Descendants<T>(IEnumerable<T>, XName)

Returns a filtered collection of elements that contains the descendant elements of every element and document in the source collection. Only elements that have a matching XName are included in the collection.

Elements<T>(IEnumerable<T>)

Returns a collection of the child elements of every element and document in the source collection.

Elements<T>(IEnumerable<T>, XName)

Returns a filtered collection of the child elements of every element and document in the source collection. Only elements that have a matching XName are included in the collection.

InDocumentOrder<T>(IEnumerable<T>)

Returns a collection of nodes that contains all nodes in the source collection, sorted in document order.

Nodes<T>(IEnumerable<T>)

Returns a collection of the child nodes of every document and element in the source collection.

Remove<T>(IEnumerable<T>)

Removes every node in the source collection from its parent node.

Applies to

Thread Safety

Filter tables are thread-safe with respect to matching operations, but are not thread-safe with respect to modification. Threads that access a filter table should be synchronized by the ReaderWriterLock or similar locking semantic. This lock allows multiple reads of a filter table (for example, a match operation) to run simultaneously, but in order to write to a filter table (for example, adding a filter), a thread must wait for an exclusive lock.

All compilation is done when filters are added to the table. If you create a filter table in advance, and never edit it, locking is not necessary during a match.