How to Configure a WCF-WebHttp Receive Location

 

This section provides information on how to configure a WCF-WebHttp Receive Location using the BizTalk Server Administration Console.

System_CAPS_ICON_note.jpg Note

Before completing the following procedure you must have already added a one-way receive port. For more information, see How to Create a Receive Port.

To configure a WCF-WebHttp receive location

  1. In the BizTalk Server Administration console, expand BizTalk Server Administration, expand BizTalk Group, expand Applications, and then expand the application under you want to create a receive location.

  2. In the left pane, click the Receive Ports node and in the right pane, right-click the receive port with which you want to associate the new receive location, and then click Properties.

  3. In the left pane of the Receive Port Properties dialog box, select Receive Locations, and in the right pane click New to create a new receive location.

  4. In the Receive Location Properties dialog box, in the Transport section, select WCF-WebHttp from the Type drop-down list, and then click Configure to configure the transport properties for the receive location.

  5. In the WCF-WebHttp Transport Properties dialog box, on the General tab, configure the endpoint address for the REST interface from where the message is received.

    Use thisTo do this
    Address (URI)Required. Specify the URI on which BizTalk Server can receive HTTP-based RESTful messages.
    Endpoint IdentityOptional. Specify the endpoint identity. These settings enable the endpoint to authenticate this receive location. In the handshake process between the endpoint and the receive location, the Windows Communication Foundation (WCF) infrastructure will ensure that the identity of the expected service matches the values of this element.

    The default is an empty string.
    HTTP Method and URL MappingBTS Operation Mapping allows users to map incoming HTTP requests to BTS Operation in the message context, based on the incoming HTTP Method and the URL sub-path. The incoming HTTP Method and the URL sub-path are matched against a set of HTTP method and the URI Template. If a match is found, the adapter promotes the BTS.Operation property to the BizTalk Message Context with the value specified in the message.

    You can specify HTTP method to URL mapping as a singular format or a multi-mapping format. The multi-mapping format resembles the following:

     <BtsHttpUrlMapping> <Operation Name = "DelCust" Method="DELETE" Url="/Customer/12345</BtsHttpUrlMapping>

    In the above snippet, notice that the customer ID is provided as a constant value, which is 12345. However, there could be scenarios when the customer ID, or any other query variable, must be determined at runtime. To enable such scenarios, you must provide the variable component of the URL within curly brackets { }. For example, in the above snippet, if you specify the customer ID as a variable, it would look like:

     <BtsHttpUrlMapping> <Operation Name = "DelCust" Method="DELETE" Url="/Customer/{ID}</BtsHttpUrlMapping>

    In such a case, you must also specify where the value for the variable ID must be picked from at runtime. You specify that using Variable Mapping.

    Note
    Within the URL field, any special XML characters must be "escaped". This ensures that the special XML characters are processed, and preserved by the port. For example, the & special character must be escaped as &amp;.

    From:
    Url=”/Customer?{ID}& group=Location”
    To:
    Url=”/Customer?{ID}&amp;group=Location”
    Variable MappingIf you specified variables for the HTTP Method URL Mapping, you must specify what the variable maps to at runtime. Click the Edit button to launch the Variable Mapping dialog box. Under the Variable column, the dialog box lists the variables that you defined for HTTP Method and URL Mapping. In the Property Name field you must specify the name of the property that provides the value to be associated to the variable. You must have already defined/promoted this property as part of your solution. You must also provide the namespace for the property in the Property Namespace field.
  6. In the WCF-WebHttp Transport Properties dialog box, on the Binding tab, configure the time-out and encoding-related properties.

    Use thisTo do this
    Open timeout (hh:mmss)Specify a time span value that indicates the interval of time provided for a channel open operation to complete. This value should be greater than or equal to System.TimeSpan.Zero.

    Default value: 00:01:00

    Maximum value: 23:59:59
    Send timeout (hh:mmss)Specify a time span value that indicates the interval of time provided for a send operation to complete. This value should be greater than or equal to System.TimeSpan.Zero. If you use a request-response receive port, this value specifies a time span for the whole interaction to complete, even if the client returns a large message.

    Default value: 00:01:00

    Maximum value: 23:59:59
    Close timeout (hh:mmss)Specify a time span value that indicates the interval of time provided for a channel close operation to complete. This value should be greater than or equal to System.TimeSpan.Zero.

    Default value: 00:01:00

    Maximum value: 23:59:59
    Maximum received message size (bytes)Specify the maximum size, in bytes, for a message including headers, which can be received on the wire. The size of the messages is bounded by the amount of memory allocated for each message. You can use this property to limit exposure to denial of service (DoS) attacks.

    The WCF-WebHttp adapter leverages the WebHttpBinding class in the buffered transfer mode to communicate with an endpoint. For the buffered transport mode, the WebHttpBinding.MaxBufferSize property is always equal to the value of this property.

    Default value: 65536

    Maximum value: 2147483647
    Max concurrent callsSpecify the number of concurrent calls to a single service instance. Calls in excess of the limit are queued. Setting this value to 0 is equivalent to setting it to Int32.MaxValue.

    The default is 200.
  7. In the WCF-WebHttp Transport Properties dialog box, on the Security tab, define the security capabilities of the WCF-WebHttp receive location.

    Use thisTo do this
    Security modeSpecify the type of security that is used. Valid values include the following:

    - None: Messages are not secured during transfer.

    - Transport: Security is provided using the HTTPS transport. The SOAP messages are secured using HTTPS. To use this mode, you must set up Secure Sockets Layer (SSL) in Microsoft Internet Information Services (IIS).

    - TransportWithMessageCredential: Integrity, confidentiality, and service authentication are provided by the HTTPS transport. To use this mode, you must set up Secure Sockets Layer (SSL) in Microsoft Internet Information Services (IIS).

    The default is Transport.
    Transport client credential typeSpecify the type of credential to be used when performing the client authentication. Valid values include the following:

    - None: No authentication occurs at the transport level.

    - Basic: Basic authentication. In Basic authentication, user names and passwords are sent in plain text over the network. You must create the domain or local user accounts corresponding to the credentials.

    - Digest: Digest authentication. This authentication method operates much like Basic authentication, except that passwords are sent across the network as a hash value for additional security. Digest authentication is available only on domains with domain controllers running Windows Server operating systems authentication. You must create the domain or local user accounts corresponding to client credentials.

    - Ntlm: NTLM authentication. Clients can send the credentials without sending a password to this receive location. You must create the domain or local user accounts corresponding to client credentials.

    - Windows: Windows integrated authentication. Windows Communication Foundation negotiates Kerberos or NTLM, preferring Kerberos if a domain is present. If you want to use Kerberos it is important to have the client identify the service with a service principal name (SPN). You must create the domain or local user accounts corresponding to client credentials.

    - Certificate: Client authentication using the client certificate. The CA certificate chain for the client X.509 certificates must be installed in the Trusted Root Certification Authorities certificate store of this computer so that the clients can be authenticated to this receive location.

     NoteThe Transport client credential type property must match the authentication scheme of the IIS virtual directory hosting this receive location. For example, if the property is set to Windows, you also need to enable Integrated Windows authentication for the virtual directory that hosts it. Similarly if the property is set to None, you must allow anonymous access to the virtual directory that hosts this receive location.

    The default is Windows.
    Service certificate -ThumbprintSpecify the thumbprint of the X.509 certificate for this receive location that the clients use to authenticate the service. The thumbprint can be selected by navigating the My store in the Current User location with the Browse button.

     Note You must install the service certificate into the Current User location of the user account for the receive handler hosting this receive location.

    Minimum length: 0

    Maximum length: 40

    The default is an empty string.
  8. In the WCF-WebHttp Transport Properties dialog box, on the Messages tab, specify the data selection for the SOAP Body element.

    Use thisTo do this
    Outbound HTTP HeadersSpecifies the HTTP headers that are stamped on the response message, if any.
    Disable location on failureSpecify whether to disable the receive location that fails inbound processing due to a receive pipeline failure or a routing failure.

    The default is cleared.
    Suspend request message on failureSpecify whether to suspend the request message that fails inbound processing due to a receive pipeline failure or a routing failure.

    The default value is cleared.
    Include exception detail in faultsSpecify whether to return SOAP faults when an error occurs to easy debugging.

    The default value is cleared.
  9. Click OK.

  10. Enter the appropriate values in the Receive Location Properties dialog box to complete the configuration of the receive location and click OK to save settings. For information about the Receive Locations Properties dialog box, see How to Create a Receive Location.

WCF-WebHttp Adapter

Community Additions

Show: