Benutzerdefinierte FilterCustom Filters

Mit benutzerdefinierten Filtern können Sie eine Übereinstimmungslogik definieren, was mit den vom System bereitgestellten Nachrichtenfiltern nicht möglich ist.Custom filters allow you to define matching logic that cannot be accomplished using the system-provided message filters. Sie können z. B. einen benutzerdefinierten Filter erstellen, der einen Hashwert für ein bestimmtes Nachrichtenelement erstellt und dann untersucht, um zu ermitteln, ob der Filter "true" oder "false" zurückgeben soll.For example, you might create a custom filter that hashes a particular message element and then examines the value to determine whether the filter should return true or false.

ImplementierungImplementation

Ein benutzerdefinierter Filter ist eine Implementierung der abstrakten MessageFilter-Basisklasse.A custom filter is an implementation of the MessageFilter abstract base class. Beim Implementieren des benutzerdefinierten Filters kann der Konstruktor optional einen einzelnen Zeichenfolgenparameter akzeptieren.When implementing your custom filter, the constructor can optionally accept a single string parameter. Dieser Parameter enthält die Konfigurationsinformationen, die an den MessageFilter-Konstruktor übergeben werden, um alle Werte bzw. die Konfiguration bereitzustellen, die der Filter zur Laufzeit zur Ermittlung von Übereinstimmungen benötigt.This parameter contains the configuration information that is passed to the MessageFilter constructor in order to provide any values or configuration that the filter needs at runtime in order to perform matches. Dies kann z. B. verwendet werden, um einen Wert bereitzustellen, nach dem der Filter innerhalb der ausgewerteten Nachricht sucht.For example, this might be used to provide a value that the filter looks for within the message being evaluated. Das folgende Beispiel veranschaulicht eine grundlegende Implementierung eines benutzerdefinierten Nachrichtenfilters, der einen Zeichenfolgenparameter akzeptiert:The following example demonstrates a basic implementation of a custom message filter that accepts a string parameter:

public class MyMessageFilter: MessageFilter  
{  
    string filterData;  
    public MyMessageFilter(string filterData)  
    {  
        if(string.IsNullOrEmpty(filterData)  
            throw new ArgumentNullException("filterData");  
        this.filterData=filterData;  
    }  
    public override bool Match(System.ServiceModel.Channels.Message message)  
    {  
        ...  
        return retValue;  
    }  
    public override bool Match(System.ServiceModel.Channels.MessageBuffer buffer)  
    {  
        ...  
        return retValue;  
    }  
}  

Hinweis

In einer wirklichen Implementierung enthält die Übereinstimmung Methode(n) Logik, die die Nachricht, um festzustellen, ob dieser Nachrichtenfilter zurückgeben soll untersucht "true" oder "false".In an actual implementation, the Match method(s) contains logic that will examine the message to determine if this message filter should return true or false.

LeistungPerformance

Wenn ein benutzerdefinierter Filter implementiert wird, ist es wichtig, die maximale Zeitspanne zu berücksichtigen, die für den Abschluss der Auswertung einer Meldung durch den Filter erforderlich ist.When implementing a custom filter, it is important to take into consideration the maximum length of time required for the filter to complete the evaluation of a message. Da eine Meldung möglicherweise mit mehreren Filtern ausgewertet wird, bevor eine Übereinstimmung gefunden wird, ist es wichtig sicherzustellen, dass die Clientanforderung kein Timeout zurückgibt, bevor alle Filter ausgewertet werden können.Since a message may be evaluated against multiple filters before a match is found, it is important to ensure that the client request does not time out before all filters can be evaluated. Daher sollte ein benutzerdefinierter Filter nur den erforderlichen Code für die Auswertung des Inhalts oder die Attribute einer Meldung enthalten, damit bestimmt werden kann, ob es eine Entsprechung für die Filterkriterien findet.Therefore a custom filter should contain only the code necessary to evaluate the contents or attributes of a message in order to determine if it matches the filter criteria.

Im Allgemeinen sollten Sie bei der Implementierung eines benutzerdefinierten Filters Folgendes vermeiden:In general, you should avoid the following when implementing a custom filter:

  • E/A, z. B. Speichern von Daten auf einem Datenträger oder in einer Datenbank.IO, such as saving data to disk or to a database.

  • Unnötige Verarbeitungsvorgänge, z. B. Ausführung von Schleifen für mehrere Datensätze in einem Dokument.Unnecessary processing, such as looping over multiple records in a document.

  • Blockieren von Vorgängen, z. B. Aufrufe, die das Abrufen einer Sperre für freigegebene Ressourcen oder das Ausführen von Suchabfragen für eine Datenbank enthalten.Blocking operations, such as calls that involve obtaining a lock on shared resources or performing lookups against a database.

Vor der Verwendung eines benutzerdefinierten Filters in einer Produktionsumgebung sollten Sie Leistungstests ausführen, um die durchschnittliche erforderliche Zeit zur Auswertung einer Meldung zu bestimmen.Before using a custom filter in a production environment, you should run performance tests to determine the average length of time that the filter takes to evaluate a message. In Kombination mit der durchschnittlichen Verarbeitungszeit der anderen in der Filtertabelle verwendeten Filter können Sie so genau den maximalen Timeoutwert bestimmen, der von der Clientanwendung angegeben werden sollte.When combined with the average processing time of the other filters used in the filter table, this will allow you to accurately determine the maximum timeout value that should be specified by the client application.

VerwendungUsage

Um den benutzerdefinierten Filter mit dem Routingdienst zu verwenden, müssen Sie es der Filtertabelle hinzufügen durch angeben einen neuen Filtereintrag vom Typ "Custom", den voll qualifizierten Typnamen des Nachrichtenfilters und den Namen der Assembly.In order to use your custom filter with the Routing Service, you must add it to the filter table by specifying a new filter entry of type "Custom," the fully qualified type name of the message filter, and the name of your assembly. Wie bei anderen MessageFilters auch, können Sie unter "filterData" eine Zeichenfolge angeben, die an den Konstruktor des benutzerdefinierten Filters übergeben wird.As with other MessageFilters, you can specify the string filterData that will be passed to your custom filter’s constructor.

In den folgenden Beispielen wird veranschaulicht, wie Sie einen benutzerdefinierten Filter mit dem Routingdienst verwenden:The following examples demonstrate using a custom filter with the Routing Service:

<!--ROUTING SECTION -->  
<routing>  
  <filters>  
    <filter name="CustomFilter1" filterType="Custom"   
            customType="CustomAssembly.MyMessageFilter,   
            CustomAssembly" filterData="custom data" />  
  </filters>  
  <filterTables>  
    <table name="routingTable1">  
      <filters>  
        <add filterName="CustomFilter1" endpointName="CalculatorService" />  
      </filters>  
    </table>  
  </filterTables>  
</routing>  
RoutingConfiguration rc = new RoutingConfiguration();  
List<ServiceEndpoint> endpointList = new List<ServiceEndpoint>();  
endpointList.Add(client);  
rc.FilterTable.Add(new MyMessageFilter("CustomData"), endpointList);