Configuration Sample

Article
11/06/2021

The Configuration sample demonstrates the use of a configuration file to make a service discoverable.

Service Configuration

The configuration file in this sample demonstrates two features:

Making the service discoverable over a standard UdpDiscoveryEndpoint.
Adjusting discovery-related information for the service's application endpoint and adjusting some of the discovery-related settings on the standard endpoint.

To enable discovery, a few changes must be made in the application configuration file for the service:

A discovery endpoint must be added to the <service> element. This is a standard UdpDiscoveryEndpoint endpoint. This is a system endpoint that the runtime associates with the discovery service. The discovery service listens for messages on this endpoint.
A <serviceDiscovery> behavior is added to the <serviceBehaviors> section. This enables the service to be discovered at run time and uses the discovery endpoint mentioned previously to listen for discovery Probe and Resolve messages. With these two additions, the service is discoverable at the discovery endpoint specified.

The following config snippet shows a service with an application endpoint and a discovery endpoint defined:

<services>
        <service name="Microsoft.Samples.Discovery.CalculatorService"
                 behaviorConfiguration="calculatorServiceBehavior">
          <endpoint address=""
                    binding="wsHttpBinding"
                    contract="Microsoft.Samples.Discovery.ICalculatorService"
                    behaviorConfiguration="endpointBehaviorConfiguration" />
          <endpoint name="udpDiscovery"
                    kind="udpDiscoveryEndpoint"
                endpointConfiguration="adhocDiscoveryEndpointConfiguration"/>        </service>
      </services>

To take advantage of announcements, you will need to add an announcement endpoint. To do this, modify the configuration file as shown in the following code.

<serviceDiscovery>
            <announcementEndpoints>
              <endpoint kind="udpAnnouncementEndpoint"/>
            </announcementEndpoints>
          </serviceDiscovery>

Adding an announcement endpoint to the discovery service behavior creates a default announcement client for the service. This guarantees that the service will send an online and offline announcement when the service is opened and closed respectively.

This configuration file goes beyond just those simple steps by modifying additional behaviors. It is possible to control discovery-related information by using specific endpoints. That is, a user can control whether an endpoint can be discovered and the user can also mark that endpoint with Scopes and custom XML metadata. To do this, the user must add a behaviorConfiguration property to the application endpoint. In this case, the following property is added to the application endpoint.

behaviorConfiguration="endpointBehaviorConfiguration"

Now, through the behavior configuration element, you can control discovery-related attributes. In this case, two scopes are added to the application endpoint.

<endpointBehaviors>
          <behavior name="endpointBehaviorConfiguration">
            <endpointDiscovery>
              <scopes>
                <add scope="http://www.example.com/calculator"/>
                <add scope="ldap:///ou=engineering,o=examplecom,c=us"/>
              </scopes>
            </endpointDiscovery>

          </behavior>
        </endpointBehaviors>

For more information about scopes, see Discovery Find and FindCriteria.

You can also control specific details of the discovery endpoint. This is done through the StandardEndpointsSection. In this sample, the version of the protocol used is modified as well as adding a maxResponseDelay attribute as shown in the following code example.

<standardEndpoints>
   <udpDiscoveryEndpoint>
      <standardEndpoint name="adhocDiscoveryEndpointConfiguration" discoveryVersion="WSDiscovery11" maxResponseDelay="00:00:00.600" />
   </udpDiscoveryEndpoint>
</standardEndpoints>

The following is the complete configuration file used in this example:

<configuration>
    <system.serviceModel>

      <services>
        <service name="Microsoft.Samples.Discovery.CalculatorService"
                 behaviorConfiguration="calculatorServiceBehavior">
          <endpoint address=""
                    binding="wsHttpBinding"
                    contract="Microsoft.Samples.Discovery.ICalculatorService"
                    behaviorConfiguration="endpointBehaviorConfiguration" />
         <!-- Define the discovery endpoint -->
<endpoint name="udpDiscovery" kind="udpDiscoveryEndpoint" endpointConfiguration="adhocDiscoveryEndpointConfiguration"/>        </service>
      </services>

      <behaviors>

        <serviceBehaviors>
          <behavior name="calculatorServiceBehavior">

            <!-- Add an announcement endpoint -->
            <serviceDiscovery>
              <announcementEndpoints>
                <endpoint kind="udpAnnouncementEndpoint"/>
              </announcementEndpoints>
            </serviceDiscovery>
          </behavior>
        </serviceBehaviors>

        <endpointBehaviors>
          <behavior name="endpointBehaviorConfiguration">
            <!-- Add scopes used to identify the service -->
            <endpointDiscovery>
              <scopes>
                <add scope="http://www.example.com/calculator"/>
                <add scope="ldap:///ou=engineering,o=examplecom,c=us"/>
              </scopes>
            </endpointDiscovery>

          </behavior>
        </endpointBehaviors>

      </behaviors>

      <standardEndpoints>
        <udpDiscoveryEndpoint>
         <!-- Configure the UDP discovery endpoint -->
          <standardEndpoint name="adhocDiscoveryEndpointConfiguration" discoveryVersion="WSDiscovery11" maxResponseDelay="00:00:00.600" />
        </udpDiscoveryEndpoint>
      </standardEndpoints>

    </system.serviceModel>
</configuration>

Client Configuration

In the application configuration file for the client, a standardEndpoint of type dynamicEndpoint is used to utilize discovery as shown in the following config snippet.

<client>
   <!--  Create an endpoint, make kind="dynamicEndpoint" and use the endpointConfiguration to change settings of DynamicEndpoint -->
   <endpoint name="calculatorEndpoint"
             binding="wsHttpBinding"
             contract="ICalculatorService"
             kind ="dynamicEndpoint"
             endpointConfiguration="dynamicEndpointConfiguration">
   </endpoint>
</client>

When a client is using a dynamicEndpoint, the runtime performs discovery automatically. Various settings are used during discovery, such as those defined in the discoveryClientSettings section, which specifies the type of discovery endpoint to use:

<endpoint kind="udpDiscoveryEndpoint" endpointConfiguration="adhocDiscoveryEndpointConfiguration" />

The find criteria used to search for services:

<!-- Add Scopes, ScopeMatchBy, Extensions and termination criteria in FindCriteria -->
<findCriteria scopeMatchBy="http://schemas.microsoft.com/ws/2008/06/discovery/rfc" duration="00:00:10" maxResults="1">
   <scopes>
      <add scope="http://www.microsoft.com/building42/floor1"/>
   </scopes>
   <!-- These extensions are sent from the client to the service as part of the probe message -->
   <extensions>
      <CustomMetadata>This is custom metadata that is sent to the service along with the client's find request.</CustomMetadata>
   </extensions>
</findCriteria>

This sample extends this feature and modifies the FindCriteria used by the client, as well as some properties of the standard updDiscoveryEndpoint used for discovery. The FindCriteria are modified to use a scope and a specific scopeMatchBy algorithm, as well as custom termination criteria. Furthermore, the sample also shows how a client can send XML elements using Probe messages. Lastly, some changes are made to the UdpDiscoveryEndpoint, such as the version of the protocol used and UDP-specific settings as shown in the following configuration file.

<udpDiscoveryEndpoint>
        <!-- Specify the discovery protocol version and UDP transport settings. -->
        <standardEndpoint name="adhocDiscoveryEndpointConfiguration" discoveryVersion="WSDiscovery11">
          <transportSettings duplicateMessageHistoryLength="2048"
                             maxPendingMessageCount="5"
                             maxReceivedMessageSize="8192"
                             maxBufferPoolSize="262144"/>
        </standardEndpoint>
      </udpDiscoveryEndpoint>

The following is the complete client configuration used in the sample.

<configuration>
  <system.serviceModel>

    <client>
      <!--  Create an endpoint, make kind="dynamicEndpoint" and use the endpointConfiguration to change settings of DynamicEndpoint -->
      <endpoint name="calculatorEndpoint"
                binding="wsHttpBinding"
                contract="ICalculatorService"
                kind ="dynamicEndpoint"
                endpointConfiguration="dynamicEndpointConfiguration">
      </endpoint>
    </client>

    <standardEndpoints>

      <dynamicEndpoint>
        <standardEndpoint name="dynamicEndpointConfiguration">
          <discoveryClientSettings>
            <!-- Controls where the discovery happens. In this case, Probe message is sent over UdpDiscoveryEndpoint. -->
            <endpoint kind="udpDiscoveryEndpoint" endpointConfiguration="adhocDiscoveryEndpointConfiguration" />

            <!-- Add Scopes, ScopeMatchBy, Extensions and termination criteria in FindCriteria -->
            <findCriteria scopeMatchBy="http://schemas.microsoft.com/ws/2008/06/discovery/rfc" duration="00:00:10" maxResults="1">
              <scopes>
                <add scope="http://www.microsoft.com/building42/floor1"/>
              </scopes>
              <!-- These extensions are sent from the client to the service as part of the probe message -->
              <extensions>
                <CustomMetadata>This is custom metadata that is sent to the service along with the client's find request.</CustomMetadata>
              </extensions>
            </findCriteria>
          </discoveryClientSettings>
        </standardEndpoint>
      </dynamicEndpoint>

      <udpDiscoveryEndpoint>
        <!-- Specify the discovery protocol version and UDP transport settings. -->
        <standardEndpoint name="adhocDiscoveryEndpointConfiguration" discoveryVersion="WSDiscovery11">
          <transportSettings duplicateMessageHistoryLength="2048"
                             maxPendingMessageCount="5"
                             maxReceivedMessageSize="8192"
                             maxBufferPoolSize="262144"/>
        </standardEndpoint>
      </udpDiscoveryEndpoint>

    </standardEndpoints>

  </system.serviceModel>
</configuration>

To use this sample

This sample uses HTTP endpoints and to run this sample, proper URL ACLs must be added. For more information, see Configuring HTTP and HTTPS. Executing the following command at an elevated privilege should add the appropriate ACLs. You may want to substitute your Domain and Username for the following arguments if the command does not work as is. netsh http add urlacl url=http://+:8000/ user=%DOMAIN%\%UserName%
Build the solution.
Run the service executable from the build directory.
Run the client executable. Note that the client is able to locate the service.

Share via

Configuration Sample

Service Configuration

Client Configuration

To use this sample

Additional resources