WCF Discovery Object Model

WCF Discovery consists of a set of types that provide a unified programming model that allows you to write services that are discoverable at runtime and clients that find and use these services.

Making a Service Discoverable and Finding Services

To make a WCF service discoverable, add a ServiceDiscoveryBehavior to the ServiceDescription of the service host and add a discovery endpoint. If a service is configured to send announcement messages (by adding an AnnouncementEndpoint) the announcement is sent when the service host is opened and closed.

A client that wants to listen for service announcement messages hosts an announcement service and adds one or more announcement endpoints. The announcement service receives announcement messages and raises announcement events.

A client uses the DiscoveryClient class to search for available services. The client application instantiates the DiscoveryClient class, passing in a discovery endpoint that specifies where to send discovery messages. The client calls the Find method, which sends a Probe request. Services listening for discovery messages receive this Probe request. If the service matches the criteria specified in the Probe, it sends a ProbeMatch message back to the client.

Object Model

The WCF Discovery API defines the following classes:

• AnnouncementClient

• AnnouncementEndpoint

• AnnouncementService

• DiscoveryClient

• DiscoveryEndpoint

• DiscoveryClientBindingElement

• DiscoveryMessageSequenceGenerator

• ServiceDiscoveryMode

• DiscoveryProxy

• DiscoveryService

• DiscoveryVersion

• DynamicEndpoint

• EndpointDiscoveryBehavior

• EndpointDiscoveryMetadata

• FindCriteria

• FindRequestContext

• FindResponse

• ResolveCriteria

• ResolveResponse

• ServiceDiscoveryBehavior

• ServiceDiscoveryExtension

• UdpAnnouncementEndpoint

• UdpDiscoveryEndpoint

AnnouncementClient

The AnnouncementClient class provides synchronous and asynchronous methods for sending announcement messages. There are two types of announcement messages, Hello and Bye. A Hello message is sent to indicate that a service has become available and a Bye message is sent to indicate that an existing service has become unavailable. The developer creates an AnnouncementClient instance, passing an instance of AnnouncementEndpoint as a constructor parameter.

AnnouncementEndpoint

AnnouncementEndpoint represents a standard endpoint with a fixed announcement contract. It is used by a service or client to send and receive announcement messages. By default, the AnnouncementEndpoint class is set to use the WS_Discovery 11 protocol version.

AnnouncementService

AnnouncementService is a system-provided implementation of an announcement service that receives and processes announcement messages. When a Hello or Bye message is received, the AnnouncementService instance calls the appropriate virtual method OnBeginOnlineAnnouncement or OnBeginOfflineAnnouncement, which raises announcement events.

DiscoveryClient

The DiscoveryClient class is used by a client application to find and resolve available services. It provides synchronous and asynchronous methods for finding and resolving services based on the specified FindCriteria and ResolveCriteria respectively. The developer creates a DiscoveryClient instance and provides an instance of DiscoveryEndpoint as a constructor parameter.

To find a service, the developer invokes the synchronous or asynchronous Find method, which provides a FindCriteria instance that contains the search criteria to use. The DiscoveryClient creates a Probe message with the appropriate headers, and sends the find request. Because there can be more than one outstanding Find request at any time, the client correlates the received responses and validates the response. It then delivers the results to the caller of the Find operation using FindResponse.

To resolve a known service, the developer invokes the synchronous or asynchronous Resolve method that provides an instance of ResolveCriteria that contains the EndpointAddress of the known service. The DiscoveryClient creates the Resolve message with the appropriate headers and sends the resolve request. The received response is correlated against the outstanding resolve requests and the result is delivered to the caller of the Resolve operation using ResolveResponse.

If a discovery proxy is present on the network and the DiscoveryClient sends the discovery request in a multicast fashion, the discovery proxy can respond with the multicast suppression Hello message. The DiscoveryClient raises the ProxyAvailable event when it receives Hello messages in response to outstanding Find or Resolve requests. The ProxyAvailable event contains the EndpointDiscoveryMetadata about the discovery proxy. It is up to the developer to use this information to switch from Ad hoc to Managed mode.

DiscoveryEndpoint

DiscoveryEndpoint represents a standard endpoint with a fixed discovery contract. It is used by a service or client to send or receive discovery messages. By default, DiscoveryEndpoint is set to use Managed mode and the WSDiscovery11 WS-Discovery version.

DiscoveryMessageSequenceGenerator

DiscoveryMessageSequenceGenerator is used to generate a DiscoveryMessageSequence when the service is sending out Discovery or Announcement messages.

DiscoveryService

The DiscoveryService abstract class provides a framework for receiving and processing Probe and Resolve messages. When a Probe message is received, DiscoveryService creates an instance of FindRequestContext based on the incoming message and invokes the OnBeginFind virtual method. When a Resolve message is received, DiscoveryService invokes the OnBeginResolve virtual method. You can inherit from this class to provide a custom Discovery Service implementation.

DiscoveryProxy

The DiscoveryProxy abstract class provides a framework for receiving and processing discovery and announcement messages. You inherit from this class when you are implementing a custom discovery proxy. When a Probe message is received over multicast, the DiscoveryProxy class calls the BeginShouldRedirectFind virtual method to determine whether a multicast suppression message should to be sent. If the developer decides not to send a multicast suppression message or if the Probe message was received over unicast, it creates an instance of the FindRequestContext class based on the incoming message and invokes the OnBeginFind virtual method. When a Resolve message is received over multicast, The DiscoveryProxy class calls the ShouldRedirectResolve virtual method to determine whether a multicast suppression message should to be sent. If the developer decides not to send a multicast suppression message or if the Resolve message was received over unicast, it creates an instance of the ResolveCriteria class based on the incoming message and invokes the OnBeginResolve virtual method. When a Hello or Bye message is received, DiscoveryProxy calls the appropriate virtual method (OnBeginOnlineAnnouncement or OnBeingOfflineAnnouncement), which raises announcement events.

DiscoveryVersion

The DiscoveryVersion class represents the discovery protocol version to use.

EndpointDiscoveryBehavior

The EndpointDiscoveryBehavior class is used to control the discoverability of an endpoint, specify the extensions, additional contract type names. and the scopes associated with that endpoint. This behavior is added to an application endpoint to configure its EndpointDiscoveryMetadata. When ServiceDiscoveryBehavior is added to the service host, all the application endpoints hosted by the service host by default become discoverable. The developer can turn off discovery for a specific endpoint by setting the Enable property to false.

EndpointDiscoveryMetadata

The EndpointDiscoveryMetadata class provides a version-independent representation of an endpoint published by the service. It contains endpoint addresses, listen URIs, contract type names, scopes, metadata version and extensions specified by the service developer. The FindCriteria sent by the client during a Probe operation is matched against the EndpointDiscoveryMetadata. If the criteria matches, then the EndpointDiscoveryMetadata is returned to the client. The endpoint address in ResolveCriteria is matched against the endpoint address of EndpointDiscoveryMetadata. If the criteria matches, then the EndpointDiscoveryMetadata is returned to the client.

FindCriteria

The FindCriteria class is a version-independent class used to specify the criteria used when finding a service. It fully supports the WS-Discovery-defined criteria for matching services. It also has extensions that developers can use to specify custom values that can be used during the matching process. The developer can provide the termination criteria for the Find operation by specifying the MaxResult, which specifies the total number of services the developer is looking for or that specifies the Duration, which is the value that specifies how long the client waits for responses.

FindRequestContext

The FindRequestContext class is instantiated by the discovery service based on the Probe message it receives when a client initiates a Find operation. It contains an instance of FindCriteria that was specified by the client.

FindResponse

The FindResponse class is returned to the caller of Find with the responses of the Find operation. It is also present in FindCompletedEventArgs. It contains a collection of EndpointDiscoveryMetadata, which is the collection of discovered endpoints and a dictionary of EndpointDiscoveryMetadata and DiscoveryMessageSequence.

ResolveCriteria

The ResolveCriteria class is a version-independent class used to specify the criteria used when resolving an already known service. It contains the endpoint address of the known service. The developer can provide the termination criteria for the resolve operation by specifying the Duration, which specifies how long the client waits for responses.

ResolveResponse

The ResolveResponse is returned to the caller of the Resolve method with the response of the Resolve operation. It is also present in ResolveCompletedEventArgs. It contains an instance of EndpointDiscoveryMetadata, which is the discovered endpoints and an instance of DiscoveryMessageSequence.

ServiceDiscoveryBehavior

The ServiceDiscoveryBehavior class allows the developer to add the discovery feature to a service. You add this behavior to the ServiceHost. The ServiceDiscoveryBehavior class iterates over the application endpoints added to the service host and creates a collection of EndpointDiscoveryMetadata from the discoverable endpoints. All endpoints are discoverable by default. The discoverability of a particular endpoint can be controlled by adding the EndpointDiscoveryBehavior to that particular endpoint. If announcement endpoints are added to ServiceDiscoveryBehavior then the announcement of all discoverable endpoints is sent over each of the announcement endpoints when the service host is opened or closed.

ServiceDiscoveryExtension

The ServiceDiscoveryExtension class is created by the ServiceDiscoveryBehavior class. The endpoints that are made discoverable can be obtained from ServiceDiscoveryExtension. This class is also used to specify a custom discovery service implementation.

UdpAnnouncementEndpoint

The UdpAnnouncementEndpoint class is a standard announcement endpoint that is pre-configured for announcement over a UDP multicast binding. By default, UdpAnnouncementEndpoint is set to use the WSApril2005 WS_Discovery version.

UdpDiscoveryEndpoint

The UdpDiscoveryEndpoint class is a standard discovery endpoint that is pre-configured for discovery over a UDP multicast binding. By default, DiscoveryEndpoint is set to use the WSDiscovery11 WS-Discovery version and Adhoc mode.