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 run time 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
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 ServiceDiscoveryMode.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 Enabled 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 MaxResults, 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.
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 ServiceDiscoveryMode.Adhoc mode.