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
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.
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.
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.
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.
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.
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.
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.
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