How to Configure a WCF-WSHttp Receive Location

Article
02/02/2021

You can configure a WCF-WSHttp 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-WSHttp 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-WSHttp adapter uses the default values for the WCF-WSHttp 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-WSHttp 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. Default value: 65536
MessageEncoding	Enum - Text - Use a text message encoder. - Mtom - Use a Message Transmission Optimization Mechanism 1.0 (MTOM) encoder.	Specify the encoder used to encode the SOAP message. Default value: Text
TextEncoding	Enum - unicodeFFF - Unicode BigEndian encoding. - utf-16 - 16-bit encoding. - utf-8 - 8-bit encoding	Specify the character set encoding to be used for emitting messages on the binding when the MessageEncoding property is set to Text. Default value: utf-8
EnableTransaction	Boolean	Specify whether a message is submitted to the MessageBox database using the transaction flowed from clients. If this property is `True`, the clients are required to submit messages using the WS-AtomicTransaction protocol. 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`
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-WSHttp 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: Message
TransportClientCredentialType	Enum - None - Basic - Ntlm - Windows - Certificate For more information about the member names for the TransportClientCredentialType property, see the Transport client credential type property in the WCF-WSHttp 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
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-WSHttp 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-WSHttp 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
NegotiateServiceCredential	Boolean	Specify whether the service credential is provisioned at the client out of band, or is obtained from the service to the client through a process of negotiation. Such a negotiation is a precursor to the usual message exchange. If the MessageClientCredentialType property equals None, Username, or Certificate, setting this property to False implies that the service certificate is available at the client out of band and that the client needs to specify the service certificate. This mode is interoperable with SOAP stacks that implement WS-Trust and WS-SecureConversation. If the MessageClientCredentialType property is set to Windows, setting this property to False specifies Kerberos-based authentication. This means that the client and service must be part of the same Kerberos domain. This mode is interoperable with SOAP stacks that implement the Kerberos token profile (as defined at OASIS WSS TC) as well as WS-Trust and WS-SecureConversation. When this property is True, it causes a .NET SOAP negotiation that tunnels SPNego exchange over SOAP messages. Default value: True
EstablishSecurityContext	Boolean	Specify whether the security channel establishes a secure session. A secure session establishes a Security Context Token (SCT) before exchanging the application messages. Default value: True
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-WSHttp Receive Adapter" in the WCF-WSHttp 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-WSHttp 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-WSHttp Receive Location with the BizTalk Administration Console

You can set WCF-WSHttp 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 procedures you must have already added a receive port. For more information, see How to Create a Receive Port.

Configure variables for a WCF-WSHttp receive location

In the BizTalk Administration console, expand BizTalk Server 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-WSHttp from the drop-down list, and then click Configure.
In the WCF-WSHttp Transport Properties dialog box, on the General tab, configure the endpoint address and the service identity for the WCF-WSHttp receive location. For more information about the General tab in the WCF-WSHttp Transport Properties dialog box, see the WCF-WSHttp Transport Properties Dialog Box, Receive, General tab in the UI guidance and developers API namespace reference.
In the WCF-WSHttp Transport Properties dialog box, on the Binding tab, configure the time-out, encoding, and transaction properties. For more information about the Binding tab in the WCF-WSHttp Transport Properties dialog box, see the WCF-WSHttp Transport Properties Dialog Box, Receive, Binding tab in the UI guidance and developers API namespace reference.
In the WCF-WSHttp Transport Properties dialog box, on the Security tab, define the security capabilities of the WCF-WSHttp receive location. For more information about the Security tab in the WCF-WSHttp Transport Properties dialog box, see the WCF-WSHttp Transport Properties Dialog Box, Receive, Security tab in the UI guidance and developers API namespace reference.
In the WCF-WSHttp 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-WSHttp Transport Properties dialog box, see the WCF-WSHttp Transport Properties Dialog Box, Receive, Messages tab in the UI guidance and developers API namespace reference.

Configure a WCF-WSHttp 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>  
  <NegotiateServiceCredential vt="11">-1</NegotiateServiceCredential>  
  <MaxReceivedMessageSize vt="3">2097152</MaxReceivedMessageSize>  
  <TextEncoding vt="8">utf-8</TextEncoding>  
  <CloseTimeout vt="8">00:01:00</CloseTimeout>  
  <SuspendMessageOnFailure vt="11">0</SuspendMessageOnFailure>  
  <EnableTransaction vt="11">0</EnableTransaction>  
  <InboundNodeEncoding vt="8">Xml</InboundNodeEncoding>  
  <EstablishSecurityContext vt="11">-1</EstablishSecurityContext>  
  <IncludeExceptionDetailInFaults vt="11">0</IncludeExceptionDetailInFaults>  
  <MaxConcurrentCalls vt="3">16</MaxConcurrentCalls>  
  <ServiceCertificate vt="8" />  
  <MessageEncoding vt="8">Text</MessageEncoding>  
  <OutboundBodyLocation vt="8">UseBodyElement</OutboundBodyLocation>  
</CustomProps>

The following code fragment illustrates creating a WCF-WSHttp 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-WSHttp 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 = "SampleBizTalkApplication1001";  
// 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-WSHttp   
int i = 0;  
for(i=0; i < explorer.ReceiveHandlers.Count; ++i)   
{  
    if("WCF-WSHttp" == explorer.ReceiveHandlers[i].TransportType.Name)  
        break;  
}  
receiveLocation.ReceiveHandler = explorer.ReceiveHandlers[i];  
receiveLocation.Address = "/samplepath/sampleservice.svc";  
receiveLocation.ReceivePipeline = explorer.Pipelines["Microsoft.BizTalk.DefaultPipelines.PassThruReceive"];  
receiveLocation.TransportType = explorer.ProtocolTypes["WCF-WSHttp"];  
receiveLocation.TransportTypeData = transportConfigData;  
// Save  
explorer.SaveChanges();

Share via

How to Configure a WCF-WSHttp Receive Location

Configuration properties

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

Configure variables for a WCF-WSHttp receive location

Configure a WCF-WSHttp Receive Location Programmatically

See Also

Feedback

Additional resources