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.
The WCF Discovery API defines the following classes:
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 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 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.
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
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 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.
The DiscoveryService abstract class provides a framework for receiving and processing
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.
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 (
OnBeingOfflineAnnouncement), which raises announcement events.
The DiscoveryVersion class represents the discovery protocol version to use.
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
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.
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.
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.
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.
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.
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.
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 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.
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.
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