Berichtfilters

Voor het implementeren van inhoudsgebaseerde routering gebruikt de Routeringsservice MessageFilter implementaties die specifieke secties van een bericht inspecteren, zoals het adres, de eindpuntnaam of een specifieke XPath-instructie. Als geen van de berichtfilters van .NET Framework 4.6.1 aan uw behoeften voldoet, kunt u een aangepast filter maken door een nieuwe implementatie van de basisklasse MessageFilter te maken.

Wanneer u de routeringsservice configureert, moet u filterelementen (FilterElement objecten) definiëren die het type MessageFilter en eventuele ondersteunende gegevens beschrijven die nodig zijn om het filter te maken, zoals specifieke tekenreekswaarden waarnaar in het bericht moet worden gezocht. Houd er rekening mee dat het maken van de filterelementen alleen de afzonderlijke berichtfilters definieert; als u de filters wilt gebruiken om berichten te evalueren en te routeren, moet u ook een filtertabel (FilterTableEntryCollection) definiëren.

Elke vermelding in de filtertabel verwijst naar een filterelement en geeft het clienteindpunt aan waarnaar een bericht wordt doorgestuurd als het bericht overeenkomt met het filter. Met de vermeldingen in de filtertabel kunt u ook een verzameling back-upeindpunten (BackupEndpointCollection) opgeven, waarmee een lijst met eindpunten wordt gedefinieerd waarnaar het bericht wordt verzonden in het geval van een overdrachtsfout bij het verzenden naar het primaire eindpunt. Deze eindpunten worden geprobeerd in de opgegeven volgorde totdat één slaagt.

Berichtfilters

De berichtfilters die door de routeringsservice worden gebruikt, bieden algemene functionaliteit voor het selecteren van berichten, zoals het evalueren van de naam van het eindpunt waarnaar een bericht is verzonden, de SOAP-actie of het adres- of adresvoorvoegsel waarnaar het bericht is verzonden. Filters kunnen ook worden gekoppeld aan een AND voorwaarde, zodat berichten alleen worden doorgestuurd naar een eindpunt als het bericht overeenkomt met beide filters. U kunt ook aangepaste filters maken door uw eigen implementatie van MessageFilter.

De volgende tabel bevat de FilterType waarden die worden gebruikt door de Routeringsservice, de klasse die het specifieke berichtfilter implementeert en de vereiste FilterData parameters.

Filtertype	Beschrijving	Betekenis van filtergegevens	Voorbeeldfilter
Actie	Hiermee wordt de ActionMessageFilter klasse gebruikt om berichten met een specifieke actie te vergelijken.	De actie waarop moet worden gefilterd.	<filter name="action1" filterType="Action" filterData="http://namespace/contract/operation" />
EndpointAddress	Hiermee wordt de EndpointAddressMessageFilter klasse gebruikt, waarbij IncludeHostNameInComparison == true berichten met een specifiek adres overeenkomen.	Het adres waarop moet worden gefilterd (in de kop Aan).	<filter name="address1" filterType="EndpointAddress" filterData="http://host/vdir/s.svc/b" />
EndpointAddressPrefix	Hiermee wordt de PrefixEndpointAddressMessageFilter klasse gebruikt, waarbij IncludeHostNameInComparison == true berichten met een specifiek adresvoorvoegsel overeenkomen.	Het adres dat moet worden gefilterd bij het gebruik van het langste voorvoegsel dat overeenkomt.	<filter name="prefix1" filterType="EndpointAddressPrefix" filterData="http://host/" />
And	Gebruikt de StrictAndMessageFilter klasse die altijd beide voorwaarden evalueert voordat deze worden geretourneerd.	filterData wordt niet gebruikt; in plaats daarvan filter1 en filter2 hebben de namen van de bijbehorende berichtfilters (ook in de tabel), die samen ensamen moeten worden geplaatst.	<filter name="and1" filterType="And" filter1="address1" filter2="action1" />
Aanpassen	Een door de gebruiker gedefinieerd type dat de MessageFilter klasse uitbreidt en een constructor heeft die een tekenreeks neemt.	Het kenmerk customType is de volledig gekwalificeerde typenaam van de klasse die moet worden gemaakt; filterData is de tekenreeks die moet worden doorgegeven aan de constructor bij het maken van het filter.	<filter name="custom1" filterType="Custom" customType="CustomAssembly.CustomMsgFilter, CustomAssembly" filterData="Custom Data" />
EndpointName	Hiermee wordt de EndpointNameMessageFilter klasse gebruikt om berichten te vergelijken op basis van de naam van het service-eindpunt waarop ze zijn aangekomen.	De naam van het service-eindpunt, bijvoorbeeld: 'serviceEndpoint1'. Dit moet een van de eindpunten zijn die beschikbaar zijn in de routeringsservice.	<filter name="stock1" filterType="Endpoint" filterData="SvcEndpoint" />
MatchAll	Maakt gebruik van de MatchAllMessageFilter klasse. Dit filter komt overeen met alle binnenkomende berichten.	filterData wordt niet gebruikt. Dit filter komt altijd overeen met alle berichten.	<filter name="matchAll1" filterType="MatchAll" />
Xpath	Hiermee wordt de XPathMessageFilter klasse gebruikt om specifieke XPath-query's binnen het bericht te vinden.	De XPath-query die moet worden gebruikt bij overeenkomende berichten.	<filter name="XPath1" filterType="XPath" filterData="//ns:element" />

In het volgende voorbeeld worden filtervermeldingen gedefinieerd die gebruikmaken van de berichtfilters XPath, EndpointName en PrefixEndpointAddress. In dit voorbeeld ziet u ook hoe u een aangepast filter gebruikt voor de vermeldingen RoundRobinFilter1 en RoundRobinFilter2.

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

Notitie

Als u een filter definieert, worden berichten niet geëvalueerd op basis van het filter. Het filter moet worden toegevoegd aan een filtertabel, die vervolgens wordt gekoppeld aan het service-eindpunt dat wordt weergegeven door de routeringsservice.

Naamruimtetabel

Wanneer u een XPath-filter gebruikt, kunnen de filtergegevens die de XPath-query bevatten, extreem groot worden vanwege het gebruik van naamruimten. Om dit probleem te verhelpen biedt de Routeringsservice de mogelijkheid om uw eigen naamruimtevoorvoegsels te definiëren met behulp van de naamruimtetabel.

De naamruimtetabel is een verzameling NamespaceElement objecten die de naamruimtevoorvoegsels definieert voor algemene naamruimten die kunnen worden gebruikt in een XPath. Hier volgen de standaardnaamruimten en naamruimtevoorvoegsels die zijn opgenomen in de naamruimtetabel.

Voorvoegsel	Naamruimte
s11	http://schemas.xmlsoap.org/soap/envelope
s12	http://www.w3.org/2003/05/soap-envelope
wsaAugust2004	http://schemas.xmlsoap.org/ws/2004/08/addressing
wsa10	http://www.w3.org/2005/08/addressing
SM	http://schemas.microsoft.com/serviceModel/2004/05/xpathfunctions
tempuri	http://tempuri.org
Ser	http://schemas.microsoft.com/2003/10/Serialization

Wanneer u weet dat u een specifieke naamruimte in uw XPath-query's gebruikt, kunt u deze toevoegen aan de naamruimtetabel, samen met een uniek voorvoegsel voor de naamruimte en het voorvoegsel gebruiken in een XPath-query in plaats van de volledige naamruimte. In het volgende voorbeeld wordt een voorvoegsel van 'aangepast' gedefinieerd voor de naamruimte "http://my.custom.namespace", die vervolgens wordt gebruikt in de XPath-query 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>  

Tabellen filteren

Hoewel elk filterelement een logische vergelijking definieert die op een bericht kan worden toegepast, biedt de filtertabel de koppeling tussen het filterelement en het doelclienteindpunt. Een filtertabel is een benoemde verzameling FilterTableEntryElement objecten die de koppeling definiëren tussen een filter, een primair doeleindpunt en een lijst met alternatieve back-upeindpunten. Met de vermeldingen in de filtertabel kunt u ook een optionele prioriteit opgeven voor elke filtervoorwaarde. In het volgende voorbeeld worden twee filters gedefinieerd en wordt vervolgens een filtertabel gedefinieerd die elk filter koppelt aan een doeleindpunt.

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

Prioriteit van filterevaluatie

Standaard worden alle vermeldingen in de filtertabel gelijktijdig geëvalueerd en wordt het bericht dat wordt geëvalueerd, doorgestuurd naar de eindpunten die zijn gekoppeld aan elke overeenkomende filtervermelding. Als er meerdere filters worden geëvalueerd trueen het bericht in één richting of dubbelzijdig is, is het bericht multicast naar de eindpunten voor alle overeenkomende filters. Aanvraag-antwoordberichten kunnen niet multicast zijn omdat er slechts één antwoord naar de client kan worden geretourneerd.

Complexere routeringslogica kan worden geïmplementeerd door prioriteitsniveaus voor elk filter op te geven; De routeringsservice evalueert eerst alle filters op het hoogste prioriteitsniveau. Als een bericht overeenkomt met een filter van dit niveau, worden er geen filters van een lagere prioriteit verwerkt. Een binnenkomend éénrichtingsbericht wordt bijvoorbeeld eerst geëvalueerd op alle filters met een prioriteit van 2. Het bericht komt niet overeen met een filter op dit prioriteitsniveau, dus vervolgens wordt het bericht vergeleken met filters met een prioriteit van 1. Twee filters met prioriteit 1 komen overeen met het bericht en omdat het eenrichtingsbericht is, wordt het doorgestuurd naar beide doeleindpunten. Omdat er een overeenkomst is gevonden tussen de filters met prioriteit 1, worden er geen filters van prioriteit 0 geëvalueerd.

Notitie

Als er geen prioriteit is opgegeven, wordt de standaardprioriteit van 0 gebruikt.

In het volgende voorbeeld wordt een filtertabel gedefinieerd waarmee prioriteiten van 2, 1 en 0 worden opgegeven voor de filters waarnaar in de tabel wordt verwezen.

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

Als in het voorgaande voorbeeld een bericht overeenkomt met het XPathFilter, wordt het doorgestuurd naar het afrondendeCalcEndpoint en worden er geen verdere filters in de tabel geëvalueerd omdat alle andere filters een lagere prioriteit hebben. Als het bericht echter niet overeenkomt met het XPathFilter, wordt het geëvalueerd op basis van alle filters van de volgende lagere prioriteit, EndpointNameFilter en PrefixAddressFilter.

Notitie

Gebruik indien mogelijk exclusieve filters in plaats van een prioriteit op te geven, omdat prioriteitsevaluatie kan leiden tot prestatievermindering.

Back-uplijsten

Elk filter in de filtertabel kan eventueel een back-uplijst opgeven, een benoemde verzameling eindpunten (BackupEndpointCollection). Deze verzameling bevat een geordende lijst met eindpunten waarnaar het bericht wordt verzonden in het geval van een CommunicationException verzending naar het primaire eindpunt dat is opgegeven in EndpointName. In het volgende voorbeeld wordt een back-uplijst met de naam 'backupServiceEndpoints' gedefinieerd die twee eindpunten bevat.

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

Als in het voorgaande voorbeeld een verzending naar het primaire eindpunt 'Bestemming' mislukt, probeert de routeringsservice elk eindpunt in de volgorde waarin ze worden vermeld, eerst te verzenden naar backupServiceQueue en vervolgens te verzenden naar alternateServiceQueue als het verzenden naar backupServiceQueue mislukt. Als alle back-upeindpunten mislukken, wordt er een fout geretourneerd.