Export (0) Print
Expand All

How to Configure a WCF-NetTcpRelay Send Port

[Unless specifically noted, the content in this topic applies to BizTalk Server 2013 and 2013 R2.]

This section provides information on how to configure a WCF-NetTcpRelay send port using the BizTalk Server Administration Console.

To configure a WCF-NetTcpRelay send port

  1. In the BizTalk Administration console, create a new send port or double-click an existing send port to modify it. For more information, see How to Create a Send Port. Configure all of the send port options and specify WCF-NetTcpRelay for the Type option in the Transport section of the General tab.

  2. On the General tab, in the Transport section, click the Configure button.

  3. In the WCF-NetTcpRelay Transport Properties dialog box, on the General tab, specify the following:

     

    Use this To do this

    Address (URI)

    Required. Specify the fully qualified URI for the send port. This will typically be in the following format:

    sb://<Namespace>.servicebus.windows.net/
    

    Maximum length: 255

    Default value: net.tcp://localhost/

    Endpoint Identity

    Optional. Specify the identity of the endpoint that this send port sends the message to. These settings enable this send port to authenticate the endpoint. In the handshake process between the endpoint and send port, the Windows Communication Foundation (WCF) infrastructure will ensure that the identity of the endpoint matches the values of this element. The values that can be specified for the Endpoint identity property differ according to the security configuration.

    The default value is cleared.

    Action

    Specify the SOAP Action header field for outgoing messages. This property can also be set through the message context property WCF.Action in a pipeline or orchestration. You can specify this value in two different ways: the single action format and the action mapping format. If you set this property in the single action format- for example, http://contoso.com/Svc/Op1- the SOAPAction header for outgoing messages is always set to the value specified in this property.

    If you set this property in the action mapping format, the outgoing SOAPAction header is determined by the BTS.Operation context property. For example, if this property is set to the following XML format and the BTS.Operation property is set to Op1, the WCF send adapter uses http://contoso.com/Svc/Op1 for the outgoing SOAPAction header.

    <BtsActionMapping>
    <Operation Name="Op1" Action="http://contoso.com/Svc/Op1" />
    <Operation Name="Op2" Action="http://contoso.com/Svc/Op2" />
    </BtsActionMapping>
    
    

    If outgoing messages come from an orchestration port, orchestration instances dynamically set the BTS.Operation property with the operation name of the port. If outgoing messages are routed with content-based routing, you can set the BTS.Operation property in pipeline components.

    Minimum length: 0

    Maximum length: 32767

    The default is an empty string.

  4. In the WCF-NetTcpRelay Transport Properties dialog box, on the Binding tab, configure the time-out and transaction properties.

     

    Use this To 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 solicit-response send port, this value specifies a time span for the whole interaction to complete, even if the service 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-NetTcpRelay adapter leverages the NetTcpRelayBinding class in the buffered transfer mode to communicate with an endpoint. For the buffered transport mode, the NetTcpRelayBindingBase.MaxBufferSize property is always equal to the value of this property.

    Default value: 65536

    Maximum value: 2147483647

  5. In the WCF-NetTcpRelay Transport Properties dialog box, on the Security tab, define the security capabilities of the WCF-NetTcpRelay send port.

     

    Use this To do this

    Security mode

    Specify the type of security that is used. Valid values include the following:

    • None: Messages are not secured during transfer.

    • Transport: Transport security is provided using TLS over TCP or SPNego. It is possible to control the protection level with this mode.

    • Message: Security is provided using SOAP message security. By default, the SOAP Body is encrypted and signed. This mode offers a variety of features, such as whether the service credentials are available at the client out of band, and the algorithm suite to use.

    • TransportWithMessageCredential: Transport security is coupled with message security. Transport security is provided by TLS over TCP, or SPNego, and ensures integrity, confidentiality, and server authentication. SOAP message security provides client authentication. To use this mode, the CA certificate chain for the service's X.509 certificate must be installed in the Trusted Root Certification Authorities certificate store of this computer so that the service can be authenticated to the send port.

      noteNote
      This security mode cannot be used with the Transport client credential type property, None.

    The default is Transport.

    Transport protection level

    Define security at the level of the TCP transport. Signing messages mitigates the risk of a third party tampering with the message while it is being transferred. Encryption provides data-level privacy during transport. Valid values include the following:

    • None: No protection.

    • Sign: Messages are signed.

    • EncryptAndSign: Messages are encrypted and signed.

    The default value is EncryptAndSign.

    Message client credential type

    Specify the type of credential to be used when performing client authentication using message-based security. This is required only if the Security mode is set to Message or TransportWithMessageCredential. Valid values include the following:

    • None: This allows the service to interact with anonymous clients. This indicates that this send port does not provide any client credential. The CA certificate chain for the service X.509 certificate must be installed in the Trusted Root Certification Authorities certificate store of this computer so that the service can be authenticated to the send port.

    • Windows: Allow the SOAP exchanges to be under the authenticated context of a Windows credential. The user account under which this send port runs is used for services to authenticate this send port. The client credential is passed through the SOAP Header element using the WSS SOAP Message Security Kerberos Token Profile 1.0 protocol. You must configure the User principal name property to the user account name running the destination service by using the Identity Editor dialog box.

    • UserName: This send port is authenticated to services with a UserName credential. The credential is passed through the SOAP Header element using the WSS SOAP Message Security UsernameToken Profile 1.0 protocol. This option requires configuring the Client credentials property. The CA certificate chain for the service X.509 certificate must be installed in the Trusted Root Certification Authorities certificate store of this computer so that the service can be authenticated to the send port.

    • Certificate: This send port is authenticated to services using the client certificate specified through the Client certificate - Thumbprint property. The credential is passed through the SOAP Header element using the WSS SOAP Message Security X509 Token Profile 1.0 protocol. The CA certificate chain for the service X.509 certificate must be installed in the Trusted Root Certification Authorities certificate store of this computer so that the service can be authenticated to the send port.

    The default is Windows.

    Algorithm suite

    Specify the message encryption and key-wrap algorithms. These algorithms map to those specified in the Security Policy Language (WS-SecurityPolicy) specification. Possible values are:

    • Basic128: Use Aes128 encryption, Sha1 for message digest, and Rsa-oaep-mgf1p for key wrap.

    • Basic128Rsa15: Use Aes128 for message encryption, Sha1 for message digest, and Rsa15 for key wrap.

    • Basic128Sha256: Use Aes256 for message encryption, Sha256 for message digest, and Rsa-oaep-mgf1p for key wrap.

    • Basic128Sha256Rsa15: Use Aes128 for message encryption, Sha256 for message digest, and Rsa15 for key wrap.

    • Basic192: Use Aes192 encryption, Sha1 for message digest, and Rsa-oaep-mgf1p for key wrap.

    • Basic192Rsa15: Use Aes192 for message encryption, Sha1 for message digest, and Rsa15 for key wrap.

    • Basic192Sha256: Use Aes192 for message encryption, Sha256 for message digest, and Rsa-oaep-mgf1p for key wrap.

    • Basic192Sha256Rsa15: Use Aes192 for message encryption, Sha256 for message digest, and Rsa15 for key wrap.

    • Basic256: Use Aes256 encryption, Sha1 for message digest, and Rsa-oaep-mgf1p for key wrap.

    • Basic256Rsa15: Use Aes256 for message encryption, Sha1 for message digest, and Rsa15 for key wrap.

    • Basic256Sha256: Use Aes256 for message encryption, Sha256 for message digest, and Rsa-oaep-mgf1p for key wrap.

    • Basic256Sha256Rsa15: Use Aes256 for message encryption, Sha256 for message digest, and Rsa15 for key wrap.

    • TripleDes: Use TripleDes encryption, Sha1 for message digest, Rsa-oaep-mgf1p for key wrap.

    • TripleDesRsa15: Use TripleDes encryption, Sha1 for message digest, and Rsa15 for key wrap.

    • TripleDesSha256: Use TripleDes for message encryption, Sha256 for message digest, and Rsa-oaep-mgf1p for key wrap.

    • TripleDesSha256Rsa15: Use TripleDes for message encryption, Sha256 for message digest, and Rsa15 for key wrap.

    The default value is Basic256.

    Client certificate -Thumbprint

    Specify the thumbprint of the X.509 certificate for authenticating this send port to a service. The thumbprint can be selected by navigating the My store in the Current User location with the Browse button.

    noteNote
    You must install the client certificate into the Current User location of the user account for the send handler hosting this send port.

    Minimum length: 0

    Maximum length: 40

    The default is an empty string.

    User name credentials

    Specify the credentials for sending messages when using UserName for the Message client credential type property. You can specify the property by clicking the Edit Credentials button.

    The default value is Do not use Single Sign-On.

    Use ACS service identity

    Select this checkbox and click Edit and provide the following values to authenticate with the Service Bus.

    • Access Control Service STS Uri – Set this to https://<Namespace>-sb.accesscontrol.windows.net/, where <namespace> is your Service Bus namespace.

    • Issuer Name – Specify the issuer name. Typically this is set to owner.

    • Issuer Key – Specify the issuer key.

  6. In the WCF-NetTcpRelay Transport Properties dialog box, on the Messages tab, specify the data selection for the SOAP Body element.

     

    Use this To do this

    Body -- BizTalk request message body

    Use the BizTalk message body part to create the content of the SOAP Body element for an outgoing message.

    This is the default setting.

    Template -- content specified by template

    Use the template supplied in the XML text box to create the content of the SOAP Body element for an outgoing message.

    The default value is cleared.

    XML

    Type the XML-formatted template for the content of the SOAP Body element of an outgoing message. This property is required if the Template -- BizTalk response message body option is selected.

    Type: String

    Minimum length: 0

    Maximum length: 32767

    The default is <bts-msg-body

    xmlns="http://www.microsoft.com/schemas/bts2007" encoding="xml"/>

    Envelope -- entire <soap:Envelope>

    Create the BizTalk message body part from the entire SOAP Envelope of an incoming. This property is valid only for solicit-response ports.

    The default value is cleared.

    Body -- contents of <soap:Body> element

    Use the content of the SOAP Body element of an incoming message to create the BizTalk message body part. If the Body element has more than one child element, only the first element becomes the BizTalk message body part. This property is valid only for solicit-response ports.

    This is the default setting.

    Path -- content located by body path

    Use the body path expression in the Body path expression text box to create the BizTalk message body part. The body path expression is evaluated against the immediate child element of the SOAP Body element of an incoming message. This property is valid only for solicit-response ports.

    The default value is cleared.

    Body path expression

    Type the body path expression to identify a specific part of an incoming message used to create the BizTalk message body part. This body path expression is evaluated against the immediate child element of the SOAP Body node of an incoming message. If this body path expression returns more than one node, only the first node is chosen for the BizTalk message body part. This property is required if the Path -- content located by body path option is selected. This property is valid only for solicit-response ports.

    Type: String

    Minimum length: 0

    Maximum length: 32767

    The default is an empty string.

    Node encoding

    Specify the type of encoding that the WCF-NetTcpRelay send adapter uses to decode for the node identified by the body path expression in the Body path expression text box. This property is required if the Path -- content located by body path option is selected. This property is valid only for solicit-response ports. Valid values include the following:

    • Base64: Base64 encoding.

    • Hex: Hexadecimal encoding.

    • String: Text encoding - UTF-8

    • XML: The WCF adapters create the BizTalk message body with the outer XML of the node selected by the body path expression in the Body path expression text box.

    The default is XML.

    Propagate fault message

    Select this check box to route the message that fails outbound processing to a subscribing application (such as another receive port or orchestration schedule). Clear the check box to suspend failed messages and generate a negative acknowledgment (NACK). This property is valid only for solicit-response ports.

    The default value is selected.

  7. Click OK and OK again to save settings.

See Also

© 2014 Microsoft Corporation. All rights reserved.

Community Additions

ADD
Show:
© 2014 Microsoft