Discovery Find and FindCriteria

.NET Framework (current version)

A discovery find operation is initiated by a client to discover one or more services and is one of the main actions in discovery. Performing a find sends a WS-Discovery Probe message over the network. Services that match the criteria specified reply with WS-Discovery ProbeMatch messages. For more information about discovery messages, see the WS-Discovery specification.

The DiscoveryClient class provides the mechanism to perform find operations and makes performing discovery client operations easy. It contains a Find method, which performs a (blocking) synchronous find, and a FindAsync method, which initiates a non-blocking asynchronous find. Both methods take a FindCriteria parameter, and provide results to the user through a FindResponse object.

FindCriteria has several properties, which can be grouped into search criteria, which specify what services you are looking for, and find termination criteria (how long the search should last). A FindCriteria can contain multiple search criteria. By default, the service has to match all of the components otherwise it does not consider itself a matching service. If you want to find services that only match some of the criteria, you can implement custom find logic on the service or you can use multiple queries.

Search criteria include:

  • P:System.ServiceModel.Discovery.ContractTypeNames - Optional. The contract name of the service being searched for and the criteria typically used when searching for a service. If more than one contract name is specified, only service endpoints matching ALL contracts reply. Note that in WCF an endpoint can only support one contract.

  • P:System.ServiceModel.Discovery.Scopes - Optional. Scopes are absolute URIs that are used to categorize individual service endpoints. You may want to use this in scenarios where multiple endpoints expose the same contract and you want a way to search for a subset of the endpoints. If more than one scope is specified, only service endpoints matching ALL scopes reply.

  • P:System.ServiceModel.Discovery.ScopeMatchBy - Specifies the matching algorithm to use while matching the scopes in the Probe message with that of the endpoint. There are five supported scope-matching rules:

    • P:System.ServiceModel.Discovery.FindCriteria.ScopeMatchByExact does a basic case-sensitive string comparison.

    • P:System.ServiceModel.Discovery.FindCriteria.ScopeMatchByPrefix matches by segments separated by “/”. A search for http://contoso/building1 matches a service with scope http://contoso/building/floor1. Note that it does not match http://contoso/building100 because the last two segments do not match.

    • P:System.ServiceModel.Discovery.FindCriteria.ScopeMatchByLdap matches scopes by segments using an LDAP URL.

    • P:System.ServiceModel.Discovery.FindCriteria.ScopeMatchByUuid matches scopes exactly using a UUID string.

    • P:System.ServiceModel.Discovery.FindCriteria.ScopeMatchByNone matches only those services that do not specify a scope.

    If a scope-matching rule is not specified, P:System.ServiceModel.Discovery.FindCriteria.ScopeMatchByPrefix is used.

Termination criteria include:

  1. Duration - The maximum time to wait for replies from services on the network. The default duration is 20 seconds.

  2. MaxResults - The maximum number of replies to wait for. If MaxResults replies are received before Duration has elapsed, the find operation ends.

FindResponse has an Endpoints collection property that contains any replies sent by matching services on the network. If no services replied, the collection is empty. If one or more services replied, each reply is stored in an EndpointDiscoveryMetadata object, which contains the address, contract, and some additional information about the service.

The following example shows how to perform a find operation in code.

// Create DiscoveryClient  
DiscoveryClient discoveryClient = new DiscoveryClient(new UdpDiscoveryEndpoint());  
// Create FindCriteria  
FindCriteria findCriteria = new FindCriteria(typeof(IPrinterService));  
findCriteria.Scopes.Add(new Uri(""));  
findCriteria.Duration = TimeSpan.FromSeconds(10);   
// Find ICalculatorService endpoints              
FindResponse findResponse = discoveryClient.Find(findCriteria);  
Console.WriteLine("Found {0} ICalculatorService endpoint(s).", findResponse.Endpoints.Count)  

WCF Discovery Overview
Using the Discovery Client Channel
Discovery with Scopes
Asynchronous Find