NachrichtenfilterMessage Filters

Um das inhaltsbasierte Routing zu implementieren, verwendet der Routingdienst MessageFilter-Implementierungen, die bestimmte Abschnitte einer Nachricht überprüfen, z. B. Adresse, Endpunktname oder eine bestimmte XPath-Anweisung.To implement content-based routing, the Routing Service uses MessageFilter implementations that inspect specific sections of a message, such as the address, endpoint name, or a specific XPath statement. Wenn keiner der von .NET Framework 4.6.1.NET Framework 4.6.1 bereitgestellten Nachrichtenfilter Ihren Anforderungen entspricht, können Sie einen benutzerdefinierten Filter erstellen, indem Sie eine neue Implementierung der MessageFilter-Basisklasse erstellen.If none of the message filters provided with .NET Framework 4.6.1.NET Framework 4.6.1 meet your needs, you can create a custom filter by creating a new implementation of the base MessageFilter class.

Beim Konfigurieren des Routingdiensts müssen Sie Filterelemente definieren (FilterElement Objekte), die den Typ des beschreiben MessageFilter sowie alle unterstützungsdaten erforderlich zum Erstellen des Filters, z. B. bestimmte Zeichenfolgenwerte, gesucht werden soll für in der Nachricht.When configuring the Routing Service, you must define filter elements (FilterElement objects) that describe the type of MessageFilter and any supporting data required to create the filter, such as specific string values to search for within the message. Beachten Sie, dass beim Erstellen der Filterelemente nur die einzelnen Nachrichtenfilter definiert werden. Um die Filter zum Auswerten und Weiterleiten von Nachrichten zu verwenden, müssen Sie zusätzlich eine Filtertabelle definieren (FilterTableEntryCollection).Note that creating the filter elements only defines the individual message filters; to use the filters to evaluate and route messages you must also define a filter table (FilterTableEntryCollection).

Jeder Eintrag in der Filtertabelle verweist auf ein Filterelement und gibt den Clientendpunkt an, an den eine Nachricht weitergeleitet wird, wenn sich für die Nachricht eine Übereinstimmung mit dem Filter ergibt.Each entry in the filter table references a filter element and specifies the client endpoint that a message will be routed to if the message matches the filter. Die Filtertabelleneinträge ermöglichen Ihnen auch das Angeben einer Auflistung von Sicherungsendpunkten (BackupEndpointCollection). Damit wird eine Liste von Endpunkten definiert, an die die Nachricht im Falle eines Übertragungsfehlers gesendet wird, sofern das Senden an den primären Endpunkt erfolgt.The filter table entries also allow you to specify a collection of backup endpoints (BackupEndpointCollection), which defines a list of endpoints that the message will be transmitted to in the event of a transmission failure when sending to the primary endpoint. Diese Endpunkte werden in der angegebenen Reihefolge abgearbeitet, bis ein Sendevorgang erfolgreich ist.These endpoints will be tried in the order specified until one succeeds.

NachrichtenfilterMessage Filters

Die vom Routingdienst verwendeten Nachrichtenfilter stellen allgemeine Funktionen zur Auswahl von Nachrichten bereit. Beispiele hierfür sind das Auswerten des Namens eines Endpunkts, an den eine Nachricht gesendet wurde, die SOAP-Aktion oder die Adresse bzw. das Adresspräfix, an die bzw. das die Nachricht gesendet wurde.The message filters used by the Routing Service provide common message selection functionality, such as evaluating the name of the endpoint that a message was sent to, the SOAP action, or the address or address prefix that the message was sent to. Filter können auch mit einer AND-Bedingung verknüpft werden, sodass Nachrichten nur dann an einen Endpunkt weitergeleitet werden, wenn die Nachricht mit beiden Filtern zu Übereinstimmungen führt.Filters can also be joined with an AND condition, so that messages will only be routed to an endpoint if the message matches both filters. Sie können benutzerdefinierte Filter auch erstellen, indem Sie eine eigene Implementierung von MessageFilter erstellen.You can also create custom filters by creating your own implementation of MessageFilter.

In der folgenden Tabelle sind der jeweils vom Routingdienst verwendete FilterType und die Klasse aufgeführt, die den spezifischen Nachrichtenfilter implementiert. Außerdem ist der erforderliche FilterData-Parameter angegeben.The following table lists the FilterType used by the Routing Service, the class that implements the specific message filter, and the required FilterData parameters.

FiltertypFilter Type BeschreibungDescription Bedeutung der FilterdatenFilter Data Meaning BeispielfilterExample Filter
AktionAction Verwendet die ActionMessageFilter-Klasse, um eine Übereinstimmung für Nachrichten zu erzielen, die eine bestimmte Aktion enthalten.Uses the ActionMessageFilter class to match messages containing a specific action. Die Aktion, nach der gefiltert werden soll.The action to filter upon. <Filtername = "action1" FilterType = "Action" unter "filterdata" = "http://namespace/contract/operation" / ><filter name="action1" filterType="Action" filterData="http://namespace/contract/operation" />
EndpointAddressEndpointAddress Verwendet die EndpointAddressMessageFilter -Klasse, mit IncludeHostNameInComparison == true mit Nachrichten, die mit einer bestimmten Adresse übereinstimmen.Uses the EndpointAddressMessageFilter class, with IncludeHostNameInComparison == true to match messages containing a specific address. Die Adresse, nach der gefiltert werden soll (im To-Header).The address to filter upon (in the To header). <filter name="address1" filterType="EndpointAddress" filterData="http://host/vdir/s.svc/b" /><filter name="address1" filterType="EndpointAddress" filterData="http://host/vdir/s.svc/b" />
EndpointAddressPrefixEndpointAddressPrefix Verwendet die PrefixEndpointAddressMessageFilter -Klasse, mit IncludeHostNameInComparison == true Nachrichten mit einem bestimmten Adresspräfix übereinstimmen.Uses the PrefixEndpointAddressMessageFilter class, with IncludeHostNameInComparison == true to match messages containing a specific address prefix. Die Adresse, nach der unter Verwendung der längsten Präfixübereinstimmung gefiltert werden soll.The address to filter upon using longest prefix matching. <filter name="prefix1" filterType="EndpointAddressPrefix" filterData="http://host/" /><filter name="prefix1" filterType="EndpointAddressPrefix" filterData="http://host/" />
AndAnd Verwendet die StrictAndMessageFilter-Klasse, die vor der Rückgabe immer beide Bedingungen auswertet.Uses the StrictAndMessageFilter class that always evaluates both conditions before returning. "filterdata" wird nicht verwendet. Stattdessen filter1 und "filter2" haben die Namen der entsprechenden Nachrichtenfilter (ebenfalls in der Tabelle), die ausgeführt werden ANDEd zusammen.filterData is not used; instead filter1 and filter2 have the names of the corresponding message filters (also in the table), which should be ANDed together. <filter name="and1" filterType="And" filter1="address1" filter2="action1" /><filter name="and1" filterType="And" filter1="address1" filter2="action1" />
BenutzerdefiniertCustom Ein benutzerdefinierter Typ, der die MessageFilter-Klasse erweitert und über einen Konstruktor verfügt, der eine Zeichenfolge verwendet.A user-defined type that extends the MessageFilter class and has a constructor taking a string. Das customType-Attribut ist der vollqualifizierte Typname der zu erstellenden Klasse. "filterData" ist die Zeichenfolge, die beim Erstellen des Filters an den Konstruktor übergeben werden soll.The customType attribute is the fully qualified type name of the class to create; filterData is the string to pass to the constructor when creating the filter. <Filtername = "custom1" FilterType = "Custom" customType="CustomAssembly.CustomMsgFilter, CustomAssembly" unter "filterdata" = "Benutzerdefinierte Daten" / ><filter name="custom1" filterType="Custom" customType="CustomAssembly.CustomMsgFilter, CustomAssembly" filterData="Custom Data" />
EndpointNameEndpointName Verwendet die EndpointNameMessageFilter-Klasse, um für Nachrichten basierend auf dem Namen des Dienstendpunkts, an dem diese empfangen wurden, eine Übereinstimmung zu erzielen.Uses the EndpointNameMessageFilter class to match messages based on the name of the service endpoint they arrived on. Der Name des Dienstendpunkts, z. B.: "serviceEndpoint1".The name of the service endpoint, for example: "serviceEndpoint1". Hierbei sollte es sich um einen der Endpunkte handeln, die vom Routingdienst verfügbar gemacht werden.This should be one of the endpoints exposed on the Routing Service. <filter name="stock1" filterType="Endpoint" filterData="SvcEndpoint" /><filter name="stock1" filterType="Endpoint" filterData="SvcEndpoint" />
MatchAllMatchAll Verwendet die MatchAllMessageFilter-Klasse.Uses the MatchAllMessageFilter class. Dieser Filter führt für alle eingehenden Nachrichten zu Übereinstimmungen.This filter matches all arriving messages. "filterData" wird nicht verwendet.filterData is not used. Dieser Filter führt immer zu Übereinstimmungen mit allen Nachrichten.This filter will always match all messages. <filter name="matchAll1" filterType="MatchAll" /><filter name="matchAll1" filterType="MatchAll" />
XPathXPath Verwendet die XPathMessageFilter-Klasse, um für bestimmte XPath-Abfragen in der Nachricht Übereinstimmungen zu ermitteln.Uses the XPathMessageFilter class to match specific XPath queries within the message. Die XPath-Abfrage, die beim Ermitteln von Übereinstimmungen für Nachrichten verwendet wird.The XPath query to use when matching messages. <filter name="XPath1" filterType="XPath" filterData="//ns:element" /><filter name="XPath1" filterType="XPath" filterData="//ns:element" />

Im folgenden Beispiel werden Filtereinträge definiert, die die Nachrichtenfilter „XPath“, „EndpointName“ und „PrefixEndpointAddress“ verwenden.The following example defines filter entries that use the XPath, EndpointName, and PrefixEndpointAddress message filters. Dieses Beispiel veranschaulicht außerdem die Verwendung eines benutzerdefinierten Filters für die Einträge RoundRobinFilter1 und RoundRobinFilter2.This example also demonstrates using a custom filter for the RoundRobinFilter1 and RoundRobinFilter2 entries.

<filters>  
     <filter name="XPathFilter" filterType="XPath"   
             filterData="/s12:Envelope/s12:Header/custom:RoundingCalculator = 1"/>  
     <filter name="EndpointNameFilter" filterType="EndpointName"   
             filterData="calculatorEndpoint"/>  
     <filter name="PrefixAddressFilter" filterType="PrefixEndpointAddress"   
             filterData="http://localhost/routingservice/router/rounding/"/>  
     <filter name="RoundRobinFilter1" filterType="Custom"   
             customType="RoutingServiceFilters.RoundRobinMessageFilter,   
             RoutingService" filterData="group1"/>  
     <filter name="RoundRobinFilter2" filterType="Custom"   
             customType="RoutingServiceFilters.RoundRobinMessageFilter,   
             RoutingService" filterData="group1"/>  
</filters>  

Hinweis

Wenn Sie einfach nur einen Filter definieren, führt dies noch nicht dazu, dass Nachrichten mit diesem Filter ausgewertet werden.Simply defining a filter does not cause messages to be evaluated against the filter. Sie müssen den Filter einer Filtertabelle hinzufügen, die dann dem Dienstendpunkt zugeordnet wird, der vom Routingdienst verfügbar gemacht wird.The filter must be added to a filter table, which is then associated with the service endpoint exposed by the Routing Service.

NamespacetabelleNamespace Table

Bei einem XPath-Filter können die Filterdaten, die die XPath-Abfrage enthalten, aufgrund der Verwendung von Namespaces sehr umfangreich werden.When using an XPath filter, the filter data that contains the XPath query can become extremely large due to the use of namespaces. Um dieses Problem zu umgehen, ermöglicht der Routingdienst das Definieren Ihrer eigenen Namespacepräfixe mithilfe der Namespacetabelle.To alleviate this problem the Routing Service provides the ability to define your own namespace prefixes by using the namespace table.

Die Namespacetabelle ist eine Auflistung von NamespaceElement-Objekten, in der die Namespacepräfixe für allgemeine Namespaces definiert sind, die in einem XPath verwendet werden können.The namespace table is a collection of NamespaceElement objects that defines the namespace prefixes for common namespaces that can be used in an XPath. Unten sind die standardmäßigen Namespaces und Namespacepräfixe aufgeführt, die in der Namespacetabelle enthalten sind.The following are the default namespaces and namespace prefixes that are contained in the namespace table.

PräfixPrefix NamespaceNamespace
s11s11 http://schemas.xmlsoap.org/soap/envelope
s12s12 http://www.w3.org/2003/05/soap-envelope
wsaAugust2004wsaAugust2004 http://schemas.xmlsoap.org/ws/2004/08/addressing
wsa10wsa10 http://www.w3.org/2005/08/addressing
smsm http://schemas.microsoft.com/serviceModel/2004/05/xpathfunctions
tempuritempuri http://tempuri.org
serser http://schemas.microsoft.com/2003/10/Serialization

Wenn Sie wissen, dass Sie in den XPath-Abfragen einen bestimmten Namespace verwenden, können Sie diesen der Namespacetabelle zusammen mit einem eindeutigen Namespacepräfix hinzufügen und das Präfix statt des vollständigen Namespaces in XPath-Abfragen verwenden.When you know that you will be using a specific namespace in your XPath queries, you can add it to the namespace table along with a unique namespace prefix and use the prefix in any XPath query instead of the full namespace. Das folgende Beispiel definiert ein Namespacepräfix "Custom" für den Namespace "http://my.custom.namespace", die dann in der XPath-Abfrage unter "filterdata" verwendet wird.The following example defines a prefix of "custom" for the namespace "http://my.custom.namespace", which is then used in the XPath query contained in filterData.

<namespaceTable>  
     <add prefix="custom" namespace="http://my.custom.namespace/"/>  
</namespaceTable>  
<filters>  
     <filter name="XPathFilter" filterType="XPath" filterData="/s12:Envelope/s12:Header/custom:RoundingCalculator = 1"/>  
</filters>  

FiltertabellenFilter Tables

Während jedes Filterelement einen logischen Vergleich definiert, der auf eine Nachricht angewendet werden kann, stellt die Filtertabelle die Zuordnung zwischen dem Filterelement und dem Zielclientendpunkt bereit.While each filter element defines a logical comparison that can be applied to a message, the filter table provides the association between the filter element and the destination client endpoint. Bei einer Filtertabelle handelt es sich um eine benannte Auflistung von FilterTableEntryElement-Objekten, die die Zuordnung zwischen einem Filter, einem primären Zielendpunkt und einer Liste alternativer Sicherungsendpunkte definieren.A filter table is a named collection of FilterTableEntryElement objects that define the association between a filter, a primary destination endpoint, and a list of alternative backup endpoints. Die Filtertabelleneinträge ermöglichen es Ihnen auch, eine optionale Priorität für jede Filterbedingung anzugeben.The filter table entries also allow you to specify an optional priority for each filter condition. Im folgenden Beispiel werden zwei Filter definiert. Anschließend wird eine Filtertabelle definiert, in der jedem Filter ein Zielendpunkt zugeordnet wird.The following example defines two filters and then defines a filter table that associates each filter with a destination endpoint.

<routing>  
     <filters>  
       <filter name="AddAction" filterType="Action" filterData="Add" />  
       <filter name="SubtractAction" filterType="Action" filterData="Subtract" />  
     </filters>  
     <filterTables>  
       <table name="routingTable1">  
         <filters>  
           <add filterName="AddAction" endpointName="Addition" />  
           <add filterName="SubtractAction" endpointName="Subtraction" />  
         </filters>  
       </table>  
     </filterTables>      
</routing>  

Priorität bei der FilterauswertungFilter Evaluation Priority

Standardmäßig werden alle Einträge in der Filtertabelle gleichzeitig ausgewertet, und die jeweils ausgewertete Nachricht wird an die Endpunkte weitergeleitet, die den einzelnen übereinstimmenden Filtereinträgen zugeordnet sind.By default, all entries in the filter table are evaluated simultaneously, and the message being evaluated is routed to the endpoint(s) associated with each matching filter entry. Wenn sich für die Auswertung mehrerer Filter true ergibt und die Nachricht den Typ unidirektional oder duplex aufweist, wird die Nachricht per Multicast an die Endpunkte für alle übereinstimmenden Filter übermittelt.If multiple filters evaluate to true, and the message is one-way or duplex, the message is multicast to the endpoints for all matching filters. Anforderung-Antwort-Nachrichten können nicht per Multicast gesendet werden, weil nur eine Antwort an den Client zurückgegeben werden kann.Request-reply messages cannot be multicast because only one reply can be returned to the client.

Sie können eine komplexere Routinglogik implementieren, indem Sie für jeden Filter Prioritätsstufen angeben. Der Routingdienst wertet zuerst alle Filter auf höchster Prioritätsstufe aus.More complex routing logic can be implemented by specifying priority levels for each filter; the Routing Service evaluates all filters at the highest priority level first. Wenn eine Nachricht auf dieser Stufe eine Übereinstimmung mit einem Filter ergibt, werden keine Filter mit einer niedrigeren Priorität verarbeitet.If a message matches a filter of this level, no filters of a lower priority are processed. Zum Beispiel wird eine eingehende unidirektionale Nachricht zuerst für alle Filter mit der Priorität 2 ausgewertet.For example, an incoming one-way message is first evaluated against all filters with a priority of 2. Die Nachricht ergibt auf dieser Prioritätsstufe keine Übereinstimmung. Als Nächstes wird die Nachricht also mit Filtern mit der Priorität 1 verglichen.The message does not match any filter at this priority level, so next the message is compared against filters with a priority of 1. Für zwei Filter mit der Priorität 1 ergibt sich für die Nachricht eine Übereinstimmung, und da es sich um eine unidirektionale Nachricht handelt, wird diese an beide Zielendpunkte weitergeleitet.Two priority 1 filters match the message, and because it is a one-way message it is routed to both destination endpoints. Da für die Filter der Priorität 1 eine Übereinstimmung ermittelt wurde, werden keine Filter der Priorität 0 ausgewertet.Because a match was found among the priority 1 filters, no filters of priority 0 are evaluated.

Hinweis

Wenn keine Priorität angegeben wird, wird die Standardpriorität 0 verwendet.If no priority is specified, the default priority of 0 is used.

Im folgenden Beispiel wird eine Filtertabelle definiert, in der für die Filter, auf die in der Tabelle verwiesen wird, die Prioritäten von 2, 1 und 0 angegeben werden.The following example defines a filter table that specifies priorities of 2, 1, and 0 for the filters referenced in the table.

<filterTables>  
     <filterTable name="filterTable1">  
          <add filterName="XPathFilter" endpointName="roundingCalcEndpoint"   
               priority="2"/>  
          <add filterName="EndpointNameFilter" endpointName="regularCalcEndpoint"   
               priority="1"/>  
          <add filterName="PrefixAddressFilter" endpointName="roundingCalcEndpoint"   
               priority="1"/>  
          <add filterName="MatchAllMessageFilter" endpointName="defaultCalcEndpoint"   
               priority="0"/>  
     </filterTable>  
</filterTables>  

Falls sich im vorangehenden Beispiel für eine Nachricht eine Übereinstimmung mit dem XPathFilter ergibt, wird diese an den roundingCalcEndpoint weitergeleitet. Es werden dann keine weiteren Filter der Tabelle ausgewertet, weil alle anderen Filter über eine niedrigere Priorität verfügen.In the preceding example, if a message matches the XPathFilter, it will be routed to the roundingCalcEndpoint and no further filters in the table will be evaluated because all other filters are of a lower priority. Falls die Nachricht jedoch nicht zu einer Übereinstimmung mit XPathFilter führt, wird sie mit allen Filtern der nächstniedrigeren Priorität ausgewertet, also EndpointNameFilter und PrefixAddressFilter.However, if the message does not match the XPathFilter it will then be evaluated against all filters of the next lower priority, EndpointNameFilter and PrefixAddressFilter.

Hinweis

Nach Möglichkeit sollten Sie anstelle einer Priorität exklusive Filter verwenden, weil die Prioritätsauswertung die Leistung beeinträchtigen kann.When possible, use exclusive filters instead of specifying a priority because priority evaluation can result in performance degradation.

SicherungslistenBackup Lists

Für jeden Filter in der Filtertabelle kann optional eine Sicherungsliste angegeben werden, bei der es sich um eine benannte Auflistung von Endpunkten handelt (BackupEndpointCollection).Each filter in the filter table can optionally specify a backup list, which is a named collection of endpoints (BackupEndpointCollection). Diese Auflistung enthält eine sortierte Liste von Endpunkten, an die die Nachricht bei Auftreten einer CommunicationException gesendet wird, sofern das Senden an unter EndpointName angegebenen primären Endpunkt erfolgt.This collection contains an ordered list of endpoints that the message will be transmitted to in the event of a CommunicationException when sending to the primary endpoint specified in EndpointName. Das folgende Beispiel definiert eine Sicherungsliste mit dem Namen "backupserviceendpoints" definiert, die zwei Endpunkte enthält.The following example defines a backup list named "backupServiceEndpoints" that contains two endpoints.

<filterTables>  
     <filterTable name="filterTable1">  
          <add filterName="MatchAllFilter1" endpointName="Destination" backupList="backupEndpointList"/>  
     </filterTable>  
</filterTables>  
<backupLists>  
     <backupList name="backupEndpointList">  
          <add endpointName="backupServiceQueue" />  
          <add endpointName="alternateServiceQueue" />  
     </backupList>  
</backupLists>  

Im vorherigen Beispiel, wenn ein Sendeversuch an den primären Endpunkt "Destination" ein Fehler auftritt, der Routingdienst versucht senden an jeden Endpunkt in der Sequenz, die sie aufgeführt sind, zuerst an BackupServiceQueue und dann an AlternateServiceQueue gesendet, wenn die Senden an BackupServiceQueue ein Fehler auftritt.In the preceding example, if a send to the primary endpoint "Destination" fails, the Routing Service will try sending to each endpoint in the sequence they are listed, first sending to backupServiceQueue and subsequently sending to alternateServiceQueue if the send to backupServiceQueue fails. Falls für alle Sicherungsendpunkte ein Fehler auftritt, wird ein Fehler zurückgegeben.If all backup endpoints fail, a fault is returned.