FilternFiltering

Der Windows Communication Foundation (WCF)-Filtersystem können deklarative Filtern Nachrichten vergleichen und funktionsbezogene Entscheidungen treffen zu können.The Windows Communication Foundation (WCF) filtering system can use declarative filters to match messages and make operational decisions. Sie können anhand von Filtern einen Teil der Nachricht untersuchen und so bestimmen, was mit der Nachricht geschehen soll.You can use filters to determine what to do with a message by examining part of the message. Ein Warteschlangenprozess kann beispielsweise eine XPath 1.0-Abfrage verwenden, um das Prioritätselement eines bekannten Headers im Hinblick darauf zu prüfen, ob eine Nachricht in der Warteschlange an den Anfang verschoben werden soll.A queuing process, for example, can use an XPath 1.0 query to check the priority element of a known header to determine whether to move a message to the front of the queue.

Das Filtersystem besteht aus einer Reihe von Klassen, die effizient können bestimmen, die von einer Reihe von Filtern werden true für eine bestimmte WCF-Nachricht.The filtering system is composed of a set of classes that can efficiently determine which of a set of filters are true for a particular WCF message.

Das Filtersystem ist eine Kernkomponente des WCF-messaging; Es ist äußerst schnell ausgeführt werden sollen.The filtering system is a core component of WCF messaging; it is designed to be extremely fast. Jede filterimplementierung wurde für eine bestimmte Art von Vergleich WCF-Nachrichten optimiert.Each filter implementation has been optimized for a particular kind of matching against WCF messages.

Das Filtersystem ist nicht threadsicher.The filtering system is not thread safe. Sperrsemantik muss von der Anwendung verarbeitet werden.The application must handle any locking semantics. Es unterstützt jedoch mehrere Reader und einen Writer.It does, however, support a multi-reader, single writer.

Anwendung des FiltersystemsWhere Filtering Fits

Die Filterung wird nach Eingang einer Nachricht durchgeführt und ist Teil des Prozesses, durch den eine Nachricht an die richtige Anwendungskomponente verteilt wird.Filtering is performed after a message is received and is part of the process of dispatching the message to the proper application component. Das Filtersystem ist Filtersystem als die Anforderungen des mehrere WCF-Subsysteme, einschließlich messaging, routing, Sicherheit, Ereignisbehandlung und systemverwaltung.The design of the filtering system addresses the requirements of several WCF subsystems, including messaging, routing, security, event handling, and system management.

FilterFilters

Das Filtermodul besteht aus zwei primären Komponenten: Filtern und Filtertabellen.The filter engine has two primary components, filters and filter tables. Ein Filter trifft anhand von benutzerdefinierten logischen Bedingungen boolesche Entscheidungen bezüglich der Nachricht.A filter makes Boolean decisions about a message based on user-specified logical conditions. Filter implementieren die MessageFilter-Klasse.Filters implement the MessageFilter class.

Mit den Match-Methoden wird ermittelt, ob eine Nachricht zu einem Filter passt.The Match methods are used to determine if a message satisfies a filter. Eine der Methoden prüft den Nachrichtenheader, kann jedoch nicht den Nachrichtentext überprüfen.One of the methods tests the message's header, but cannot inspect the message body. Die andere Methode nimmt einen Nachrichtenpuffer als Eingabeparameter und kann den Nachrichtentext überprüfen.The other method takes a message buffer as an input parameter and can inspect the message body.

Filter werden im Allgemeinen nicht einzeln überprüft, sondern als Teil einer Filtertabelle, bei der es sich um eine durch die CreateFilterTable-Methode erstellte generische Klasse handelt.Filters are not usually tested individually, but as part of a filter table, which is a generic class that the CreateFilterTable method creates.

Die verschiedenen Filter sind jeweils für den Vergleich einer bestimmten Art von boolescher Bedingung optimiert.The several kinds of filters each specialize in matching on a particular kind of Boolean condition. Nach der Erstellung eines Filters können die vom Filter verwendeten Kriterien nicht mehr geändert werden. Soll ein Filter andere Kriterien verwenden, erstellen Sie einen neuen Filter und löschen den bestehenden.Once you construct a filter, you cannot change the criteria that a filter uses; to modify a filter's criteria, construct a new one and delete the existing filter.

AktionsfilterAction Filters

ActionMessageFilter enthält eine Liste mit Aktionszeichenfolgen.The ActionMessageFilter contains a list of action strings. Falls eine der Aktionen in der Filterliste mit dem Action-Header in der Nachricht bzw. im Nachrichtenpuffer übereinstimmt, gibt die Match-Methode true zurück.If any of the actions in the filter’s list matches the Action header in the message or message buffer, the Match method returns true. Falls die Liste leer ist, gilt der Filter als ein Filter, bei dem es nur Übereinstimmungen gibt, das heißt, jede Nachricht bzw. jeder Nachrichtenpuffer liefert eine Übereinstimmung, und von Match wird true zurückgegeben.If the list is empty, the filter is considered a match-all filter and any message or message buffer matches and Match returns true. Falls keine der Aktionen in der Filterliste mit dem Action-Header in der Nachricht bzw. im Nachrichtenpuffer übereinstimmt, gibt die Match-Methode false zurück.If none of the actions in the filter’s list matches the Action header in the message or message buffer, Match returns false. Falls die Nachricht keine Aktion enthält und die Filterliste nicht leer ist, gibt die Match-Methode false zurück.If there is no action in the message and the filter’s list is non-empty, then Match returns false.

EndpunktadressenfilterEndpoint Address Filters

EndpointAddressMessageFilter filtert Nachrichten und Nachrichtenpuffer auf Grundlage einer Endpunktadresse entsprechend der Headerauflistung.The EndpointAddressMessageFilter filters messages and message buffers based on an endpoint address, as represented in their header collection. Damit eine Nachricht einen solchen Filter passieren kann, müssen die folgenden Voraussetzungen erfüllt sein:For a message to pass such a filter, the following conditions must be met:

  • Der Adress-URI (Uniform Resource Identifier) des Filters muss dem Adress-URI im To-Header der Nachricht entsprechen.The filter’s address Uniform Resource Identifier (URI) must be the same as the one in the message To header.

  • Jedem Endpunktparameter in der Adresse des Filters (address.Headers-Auflistung) muss ein Header in der Nachricht zugeordnet werden können.Each endpoint parameter in the address of the filter (address.Headers collection) must find a header in the message to map on. Auch bei zusätzlichen Headern in der Nachricht oder im Nachrichtenpuffer bleibt die Übereinstimmung true.Extra headers in the message or message buffer are acceptable for the match to remain true.

Präfixfilter für EndpunktadressenPrefix Endpoint Address Filters

  1. PrefixEndpointAddressMessageFilter funktioniert wie EndpointAddressMessageFilter, mit der Ausnahme, dass sich die Übereinstimmung in einem Präfix des Nachrichten-URIs befinden kann.The PrefixEndpointAddressMessageFilter functions just like the EndpointAddressMessageFilter filter, except that the match can be on a prefix of the message URI. Z. B. einen Filter, die Angabe der Adresse http://www.adatum.com entspricht an adressierten http://www.adatum.com/userA.For example, a filter specifying the address http://www.adatum.com matches messages addressed to http://www.adatum.com/userA.

XPath-NachrichtenfilterXPath Message Filters

XPathMessageFilter überprüft anhand eines XPath-Ausdrucks, ob ein XML-Dokument bestimmte Elemente, Attribute, Text oder andere syntaktische XML-Konstrukte enthält.An XPathMessageFilter uses an XPath expression to determine whether an XML document contains specific elements, attributes, text, or other XML syntactic constructs. Der Filter ist so optimiert, dass er sehr effizient bei einer eng gefassten Teilmenge von XPath funktioniert.The filter is optimized to be extremely efficient for a strict subset of XPath. Die XML Path Language wird beschrieben, der W3C XML Path Language 1.0-Spezifikation.The XML Path Language is described in the W3C XML Path Language 1.0 specification.

Im Allgemeinen wird der Inhalt einer SOAP-Nachricht von einer Anwendung mithilfe von XPathMessageFilter an einem Endpunkt abgefragt. Anschließend wird auf Grundlage des Abfrageergebnisses die entsprechende Aktion eingeleitet.Typically, an application uses an XPathMessageFilter at an endpoint to query the contents of a SOAP message and then takes the appropriate action based on the results of that query. Ein Warteschlangenprozess kann beispielsweise mithilfe einer XPath-Abfrage das Prioritätselement eines bekannten Headers im Hinblick darauf untersuchen, ob eine Nachricht in der Warteschlange an den Anfang verschoben werden soll.A queuing process, for example, may use an XPath query to inspect the priority element of a known header to decide whether to move a message to the front of the queue.

FiltertabellenFilter Tables

In Filtertabellen werden Schlüssel-Wert-Paare gespeichert, wobei ein Filter der Schlüssel ist und zugehörige Daten der Wert sind.Filter tables are used to store key-value pairs, where a filter is the key and some associated data is the value. Die Filterdaten können verwendet werden, um die Aktionen anzugeben, die durchgeführt werden, wenn eine Nachricht mit dem Filter übereinstimmt und es sich bei der Art der Filterdaten um den generischen Parameter für die Filtertabellenklasse handelt.The filter data can be used to indicate what actions to take if a message matches the filter and the type of the filter data is the generic parameter for the filter table class. Die Filterdaten können Routingregeln, Sitzungs- und Sicherheitsstatus, Kanallistener usw. umfassen.The filter data can consist of routing rules, session security state, listeners on a channel, and so on. Die Daten können verwendet werden, wenn eine Datenflusssteuerung erforderlich ist.The data can be used where data flow control is necessary.

Filtertabellen implementieren die generische Schnittstelle IMessageFilterTable<TFilterData>.Filter tables implement the generic interface IMessageFilterTable<TFilterData>.

Filtertabellen verfügen über mehrere Methoden, die eine Nachricht mit allen Filtern in der Tabelle vergleichen und eine nicht sortierte Auflistung der passenden Filter bzw. Daten zurückgeben.Filter tables have several methods that match a message against all the filters in the table and return an unordered collection of matching filters or data. Einige Vergleichsmethoden suchen mehrere Übereinstimmungen und geben alle passenden Elemente zurück.Some of the match methods are multiple-match and return all matching items. Andere Methoden suchen nur eine Übereinstimmung, geben nur ein Element zurück und lösen eine MultipleFilterMatchesException aus, wenn mehr als ein Filter passt.Others are single-match, returning only one item, and throw a MultipleFilterMatchesException if more than one filter matches.

NachrichtenfiltertabelleMessage Filter Table

MessageFilterTable<TFilterData> ist die allgemeinste Implementierung von IMessageFilterTable<TFilterData>.The MessageFilterTable<TFilterData> is the most general implementation of IMessageFilterTable<TFilterData>. Sie können alle Arten von Filtern in der Tabelle speichern.You can store filters of all types in the table.

Sie können Filtern eine numerische Priorität zuweisen, wobei die höchste Priorität durch die höchste Zahl angegeben wird.You can assign numeric priorities to filters, where the highest priority is signified by the highest number. Verschiedene Arten von Filtern können die gleiche Priorität haben.Multiple types of filters can have the same priority. Ein bestimmter Filtertyp kann auch in verschiedenen Prioritätsstufen erscheinen.A particular type of filter can appear in more than one priority level.

Der Vergleich beginnt mit der höchsten Priorität. Sobald passende Filter mit der angegebenen Priorität gefunden werden, werden keine weiteren Filter mit einer niedrigeren Priorität mehr überprüft.Matching is done starting with the highest priority, and once matching filters are found with a given priority, no filters with lower priorities are examined. Wenn Sie also eine Vergleichsmethode für einen einzelnen Filter verwenden und mehrere Filter mit einer Nachricht übereinstimmen, jedoch verschiedene Prioritätsstufen aufweisen, wird keine Ausnahme ausgelöst, und der Filter mit der höchsten Priorität wird zurückgegeben.Therefore, if you are using a single-filter match method, and more than one filter matches a message, but each matching filter has a different priority, then no exception is thrown and the filter with the highest priority is returned. Ebenso geben Vergleichsmethoden für mehrere Filter nur die passenden Filter mit der höchsten Priorität zurück.Similarly, a multiple-filter match method returns only those matching filters with the highest priority.

XPath-NachrichtenfiltertabelleXPath Message Filter Table

XPathMessageFilterTable<TFilterData> ist für deklarative XPath-Filter optimiert, daher handelt es sich beim Tabellenschlüssel um einen XPathMessageFilter.The XPathMessageFilterTable<TFilterData> is optimized for declarative XPath filters, so the table key is a XPathMessageFilter.

Die XPathMessageFilterTable<TFilterData>-Klasse optimiert den Vergleich für eine XPath-Teilmenge, durch die die meisten Messaging-Szenarien abgedeckt werden und die zudem die vollständige XPath 1.0-Grammatik unterstützt.The XPathMessageFilterTable<TFilterData> class optimizes matching for a subset of XPath that covers most of the messaging scenarios and also supports the full XPath 1.0 grammar. Sie verfügt über optimierte Algorithmen für einen effizienten Parallelvergleich.It has optimized algorithms for efficient parallel matching.

Diese Tabelle verfügt über mehrere spezielle Match-Methoden, die mit XPathNavigator und SeekableXPathNavigator arbeiten.This table has several specialized Match methods that operate over an XPathNavigator and a SeekableXPathNavigator. SeekableXPathNavigator erweitert die XPathNavigator-Klasse durch Hinzufügen einer CurrentPosition-Eigenschaft.A SeekableXPathNavigator extends the XPathNavigator class by adding a CurrentPosition property. Diese Eigenschaft ermöglicht es, Positionen innerhalb des XML-Dokuments zu speichern und rasch zu laden, ohne den Navigator klonen zu müssen (eine ressourcenintensive Speicherbelegung, die XPathNavigator für einen solchen Vorgang benötigt).This property allows positions within the XML document to be saved and loaded quickly without having to clone the navigator, an expensive memory allocation that the XPathNavigator requires for such an operation. Das WCF XPath-Modul muss häufig die Position des Cursors im Verlauf der Ausführung von Abfragen von XML-Dokumenten aufzeichnen also die SeekableXPathNavigator bietet eine wichtige Optimierung der Nachrichtenverarbeitung.The WCF XPath engine must frequently record the position of the cursor in the course of executing queries on XML documents, so the SeekableXPathNavigator provides an important optimization for message processing.

KundenszenarienCustomer Scenarios

Sie können die Filterung verwenden, wenn Sie eine Nachricht basierend auf den darin enthaltenen Daten an verschiedene Verarbeitungsmodule senden möchten.You can use filtering any time you want to send a message to different processing modules depending on data contained in the message. Zwei typische Szenarien sind die Weiterleitung einer Nachricht auf Grundlage ihres Aktionscodes und das Demultiplexing eines Nachrichtenstroms basierend auf der Endpunktadresse der Nachricht.Two typical scenarios are routing a message based on its action code and de-multiplexing a stream of messages based on the messages' endpoint address.

RoutingRouting

Der Listener eines Endpunkts hört Nachrichten ab, die einen oder mehrere Aktionscodes im SOAP-Header der Nachricht aufweisen.The listener of an endpoint listens for messages that have one or more action codes in the message's SOAP header. Diese Funktion wird durch Erstellen eines ActionMessageFilter implementiert, indem ein Array mit den Aktionscodes an den Konstruktor übergeben wird.You implement this by creating an ActionMessageFilter by passing an array that contains the action codes to its constructor. Dieser Filter wird für die Registrierung bei ListenerFactory verwendet, das heißt, dass nur Nachrichten, deren Aktion mit einer der Aktionen im Filter übereinstimmt, zu diesem Endpunkt geleitet werden.It uses that filter to register with the ListenerFactory, so only messages whose action matches one of those in the filter get to that particular endpoint.

DemultiplexingDe-multiplexing

Falls ein ServiceListener auf mehrere Endpunkte verzweigt, gibt es nur eine Möglichkeit, ein Demultiplexing für die Nachrichten durchzuführen und herauszufinden, ob sie zu einer bestimmten Endpunktadresse gehören: Sie müssen mehrere EndpointAddressMessageFilter verwenden, die Nachrichten über eine Suche in den im Header gespeicherten Informationen für die registrierten Endpunkte auswählen.When multiple endpoints fan out from the same ServiceListener off the wire, the only way to de-multiplex messages and know whether they belong to a certain endpoint address, is to use EndpointAddressMessageFilters, which select messages toward the registered endpoints by performing a lookup on the information stored in the headers. In diesen Filtern weisen nur die Nachrichten, die passieren dürfen, die notwendigen Header auf, die den folgenden beiden Punkten entsprechen:In these filters, only those messages that pass have all necessary headers that correspond to both:

Siehe auchSee Also

Datenübertragung und SerialisierungData Transfer and Serialization