How to Configure a WCF-NetTcp Receive Location

You can configure a WCF-NetTcp receive location either programmatically or by using the BizTalk Administration console.

Configuration properties

The BizTalk Explorer Object Model enables you to create and configure receive locations programmatically. The BizTalk Explorer Object Model exposes theIReceiveLocation receive location configuration interface that has a TransportTypeData read/write property. This property accepts a WCF-NetTcp receive location configuration property bag in the form of a name-value pair of XML strings. To set this property in the BizTalk Explorer Object Model, you must set the InboundTransportLocation property of the IReceiveLocation interface.

The TransportTypeData property of the IReceiveLocation interface does not have to be set. If it is not set, the WCF-NetTcp adapter uses the default values for the WCF-NetTcp receive location configuration as indicated in the following table.

The following table lists the configuration properties that you can set in the BizTalk Explorer Object Model for the WCF-NetTcp receive location.

Property name Type Description
Identity XML Blob

Example:

<identity>

<userPrincipalName value="username@contoso.com" />

</identity>
Specify the identity of the service that this receive location provides. The values that can be specified for the Identity property differ according to the security configuration. These settings enable the client to authenticate this receive location. In the handshake process between the client and service, 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.
OpenTimeout System.TimeSpan Specify a time span value that indicates the interval of time provided for a channel open operation to complete.

Default value: 00:01:00
SendTimeout System.TimeSpan Specify a time span value that indicates the interval of time provided for a send operation to complete. 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
CloseTimeout System.TimeSpan Specify a time span value that indicates the interval of time provided for a channel close operation to complete.

Default value: 00:01:00
MaxReceivedMessageSize Integer Specify the maximum size, in bytes, for a message (including headers) that 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-NetTcp adapter leverages the NetTcpBinding class in the buffered transfer mode to communicate with an endpoint. For the buffered transport mode, the NetTcpBinding.MaxBufferSize property is always equal to the value of this property.

Default value: 65536
EnableTransaction Boolean Specify whether a message is submitted to the MessageBox database using the transaction flowed from clients. If this property is set to True, the clients are required to submit messages using the transaction protocol specified in the TransactionProtocol property. If the clients submit messages outside the transactional scope then this receive location returns an exception back to the clients, and no messages are suspended.

The option is available only for one-way receive locations. If the clients submit messages in a transactional context for request-response receive locations, then an exception is returned back to the clients and no messages are suspended.

Default value: False
TransactionProtocol Enum

- OleTransaction
- WS-AtomicTransaction
Specify the transaction protocol to be used with this receive location.

Default value: OleTransaction
LeaseTimeout System.TimeSpan Specify the maximum lifetime of an active pooled connection. After the specified time elapses, the connection closes after the current request is serviced.

The WCF-NetTcp adapter leverages the NetTcpBinding class to communicate with an endpoint. When using the NetTcpBinding in load-balanced scenarios, consider reducing the default lease time-out. For more information about load balancing when using the NetTcpBinding, see the appropriate topic in See Also.

Default value: 00:05:00
MaxConcurrentCalls Integer Specify the number of concurrent calls to a single service instance. Calls in excess of the limit are queued. The range of this property is from 1 to Int32.MaxValue.

Default value: 200
SecurityMode Enum

- None
- Message
- Transport
- TransportWithMessageCredential

For more information about the member names for the SecurityMode property, see the Security mode property in the WCF-NetTcp Transport Properties Dialog Box, Receive, Security tab in the UI guidance and developers API namespace reference.
Specify the type of security that is used.

Default value: Transport
TransportClientCredentialType Enum

- None
- Windows
- Certificate

For more information about the member names for the TransportClientCredentialType property, see the Transport client credential type property in the WCF-NetTcp Transport Properties Dialog Box, Receive, Security tab in the UI guidance and developers API namespace reference.
Specify the type of credential to be used when performing the client authentication.

Default value: Windows
TransportProtectionLevel Enum

- None: No protection.
- Sign: Messages are signed.
- EncryptAndSign: Messages are encrypted and signed.
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.

Default value: EncryptAndSign
MessageClientCredentialType Enum

- None
- Windows
- UserName
- Certificate

For more information about the member names for the MessageClientCredentialType property, see the Message client credential type property in the WCF-NetTcp Transport Properties Dialog Box, Receive, Security tab in the UI guidance and developers API namespace reference.
Specify the type of credential to be used when performing client authentication using message-based security.

Default value: Windows
AlgorithmSuite Enum

For more information about the member names for the AlgorithmSuite property, see the Algorithm suite property in the WCF-NetTcp Transport Properties Dialog Box, Receive, Security tab in the UI guidance and developers API namespace reference.
Specify the message encryption and key-wrap algorithms. These algorithms map to those specified in the Security Policy Language (WS-SecurityPolicy) specification.

Default value: Basic256
ServiceCertificate String Specify the thumbprint of the X.509 certificate for this receive location that the clients use to authenticate the service. The certificate to be used for this property must be installed into the My store in the Current User location. Note: You must install the service certificate into the Current User location of the user account for the receive handler hosting this receive location.

The default is an empty string.
UseSSO Boolean Specify whether to use Enterprise Single Sign-On (SSO) to retrieve client credentials to issue an SSO ticket. For more information about the security configurations supporting SSO, see the section, "Enterprise Single Sign-On Supportability for the WCF-NetTcp Receive Adapter" in the WCF-NetTcp Transport Properties Dialog Box, Receive, Security tab in the UI guidance and developers API namespace reference.
InboundBodyLocation Enum

- UseBodyElement - 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.
- UseEnvelope - Create the BizTalk message body part from the entire SOAP Envelope of an incoming message.
- UseBodyPath - Use the body path expression in the InboundBodyPathExpression property 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.

For more information about how to use the InboundBodyLocation property, see Specifying the Message Body for the WCF Adapters.
Specify the data selection for the SOAP Body element of incoming WCF messages.

Default value: UseBodyElement
InboundBodyPathExpression String

For more information about how to use the InboundBodyPathExpression property, see WCF Adapters Property Schema and Properties.
Specify 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 InboundBodyLocation property is set to UseBodyPath.

The default is an empty string.
InboundNodeEncoding Enum

- 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 InboundBodyPathExpression.
Specify the type of encoding that the WCF-NetTcp receive adapter uses to decode the node identified by the body path expression specified in InboundBodyPathExpression. This property is required if the InboundBodyLocation property is set to UseBodyPath.

Default value: XML
OutboundBodyLocation Enum

- UseBodyElement - Use the BizTalk message body part to create the content of the SOAP Body element for an outgoing response message.
- UseTemplate - Use the template supplied in the OutboundXMLTemplate property to create the content of the SOAP Body element for an outgoing response message.

For more information about how to use the OutboundBodyLocation property, see Specifying the Message Body for the WCF Adapters.
Specify the data selection for the SOAP Body element of outgoing WCF messages. This property is valid only for request-response receive locations.

Default value: UseBodyElement
OutboundXMLTemplate String

For more information about how to use the OutboundXMLTemplate property, see Specifying the Message Body for the WCF Adapters.
Specify the XML-formatted template for the content of the SOAP Body element of an outgoing response message. This property is required if the OutboundBodyLocation property is set to UseTemplate. This property is valid only for request-response receive locations.

The default is an empty string.
SuspendMessageOnFailure Boolean Specify whether to suspend the request message that fails inbound processing due to a receive pipeline failure or a routing failure.

Default value: True
IncludeExceptionDetailInFaults Boolean Specify whether to include managed exception information in the detail of SOAP faults returned to the client for debugging purposes.

Default: False

Configure a WCF-NetTcp Receive Location with the BizTalk Administration Console

You can set WCF-NetTcp receive location adapter variables in the BizTalk Administration console. If properties are not set in the receive location, the default receive handler values set in the BizTalk Administration console are used.

Note

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

Configure variables for a WCF-NetTcp receive location

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

  2. In the BizTalk Administration console, in the left pane, click the Receive Port node. Then in the right pane, right-click the receive port that is associated with an existing receive location or that you want to associate with a new receive location, and then click Properties.

  3. In the Receive Port Properties dialog box, in the left pane, select Receive Locations, and then in the right pane, double-click an existing receive location or click Newto create a new receive location.

  4. In the Receive Location Properties dialog box, in the Transport section next to Type, select WCF-NetTcp from the drop-down list, and then click Configure.

  5. In the WCF-NetTcp Transport Properties dialog box, on the General tab, configure the endpoint address and the service identity for the WCF-NetTcp receive location. For more information about the General tab in the WCF-NetTcp Transport Properties dialog box, see the WCF-NetTcp Transport Properties Dialog Box, Receive, General tab in the UI guidance and developers API namespace reference.

  6. In the WCF-NetTcp Transport Properties dialog box, on the Binding tab, configure the time-out and transaction properties. For more information about the Binding tab in the WCF-NetTcp Transport Properties dialog box, see the WCF-NetTcp Transport Properties Dialog Box, Receive, Binding tab in the UI guidance and developers API namespace reference.

  7. In the WCF-NetTcp Transport Properties dialog box, on the Security tab, define the security capabilities of the WCF-NetTcp receive location. For more information about the Security tab in the WCF-NetTcp Transport Properties dialog box, see the WCF-NetTcp Transport Properties Dialog Box, Receive, Security tab in the UI guidance and developers API namespace reference.

  8. In the WCF-NetTcp Transport Properties dialog box, on the Messages tab, specify the data selection for the SOAP Body element. For more information about the Messages tab in the WCF-NetTcp Transport Properties dialog box, see the WCF-NetTcp Transport Properties Dialog Box, Receive, Messages tab in the UI guidance and developers API namespace reference.

Configure a WCF-NetTcp Receive Location Programmatically

You can use the following format to set the properties:

<CustomProps>
  <InboundBodyPathExpression vt="8" />
  <InboundBodyLocation vt="8">UseBodyElement</InboundBodyLocation>
  <UseSSO vt="11">0</UseSSO>
  <MessageClientCredentialType vt="8">Windows</MessageClientCredentialType>
  <SendTimeout vt="8">00:01:00</SendTimeout>
  <OutboundXmlTemplate vt="8"><bts-msg-body xmlns="http://www.microsoft.com/schemas/bts2007" encoding="xml"/></OutboundXmlTemplate>
  <OpenTimeout vt="8">00:01:00</OpenTimeout>
  <AlgorithmSuite vt="8">Basic256</AlgorithmSuite>
  <SecurityMode vt="8">Message</SecurityMode>
  <TransportClientCredentialType vt="8">Windows</TransportClientCredentialType>
  <MaxReceivedMessageSize vt="3">2097152</MaxReceivedMessageSize>
  <CloseTimeout vt="8">00:01:00</CloseTimeout>
  <SuspendMessageOnFailure vt="11">0</SuspendMessageOnFailure>
  <EnableTransaction vt="11">0</EnableTransaction>
  <InboundNodeEncoding vt="8">Xml</InboundNodeEncoding>
  <IncludeExceptionDetailInFaults vt="11">0</IncludeExceptionDetailInFaults>
  <MaxConcurrentCalls vt="3">16</MaxConcurrentCalls>
  <ServiceCertificate vt="8" />
  <OutboundBodyLocation vt="8">UseBodyElement</OutboundBodyLocation>
</CustomProps>

The following code fragment illustrates creating a WCF-NetTcp receive location:

Caution

This example or guidance references sensitive information, such as a connection string or a username and password. Never hardcode these values in your code, and make sure that you protect confidential data by using the most secure authentication available. For more information, see the following documentation:

// Use BizTalk Explorer object model to create new WCF-NetTcp receive location
string server = System.Environment.MachineName;
string database = "BizTalkMgmtDb";
string connectionString = string.Format("Server={0};Database={1};Integrated Security=true", server, database);
string transportConfigData = @"<CustomProps>
  <InboundBodyLocation vt=""8"">UseBodyElement</InboundBodyLocation>
  <UseSSO vt=""11"">0</UseSSO>
  <Identity vt=""8"">
    <identity>
    <userPrincipalName value=""username@contoso.com"" />
    </identity>
  </Identity>
</CustomProps>";
//requires project reference to \Program Files\Microsoft BizTalk Server 2009\Developer Tools\Microsoft.BizTalk.ExplorerOM.dll
BtsCatalogExplorer explorer = new Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer();
explorer.ConnectionString = connectionString;
// Add a new BizTalk application
Application application = explorer.AddNewApplication();
application.Name = "SampleBizTalkApplication";
// Save
explorer.SaveChanges();

// Add a new one-way receive port
IReceivePort receivePort = application.AddNewReceivePort(false);
receivePort.Name = "SampleReceivePort";
// Add a new one-way receive location
IReceiveLocation receiveLocation = receivePort.AddNewReceiveLocation();
receiveLocation.Name = "SampleReceiveLocation";
// Find a receive handler for WCF-NetTcp
int i = 0;
for(i=0; i < explorer.ReceiveHandlers.Count; ++i)
{
    if("WCF-NetTcp" == explorer.ReceiveHandlers[i].TransportType.Name)
        break;
}
receiveLocation.ReceiveHandler = explorer.ReceiveHandlers[i];
receiveLocation.Address = "net.tcp://mycomputer/samplepath";
receiveLocation.ReceivePipeline = explorer.Pipelines["Microsoft.BizTalk.DefaultPipelines.PassThruReceive"];
receiveLocation.TransportType = explorer.ProtocolTypes["WCF-NetTcp"];
receiveLocation.TransportTypeData = transportConfigData;
// Save
explorer.SaveChanges();

See Also

Publishing Service Metadata for the WCF Receive Adapters Managing BizTalk Hosts and Host Instances How to Change Service Accounts and Passwords Installing Certificates for the WCF Adapters Specifying the Message Body for the WCF Adapters Load Balancing Configuring the WCF-NetTcp Adapter