Create the receive location and send port programmatically

Configure a WCF-BasicHttp receive location and send port programmatically. To use the BizTalk Administration console, see WCF-BasicHttp adapter.

Configure the receive location programmatically

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-BasicHttp 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-BasicHttp adapter uses the default values for the WCF-BasicHttp receive location configuration as indicated in the following table.

The following code fragment illustrates creating a WCF-BasicHttp receive location using the BizTalk Explorer Object Model:

// Use BizTalk Explorer object model to create new WCF-BasicHttp 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-BasicHttp
int i = 0;
for(i=0; i < explorer.ReceiveHandlers.Count; ++i)
{
    if("WCF-BasicHttp" == 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-BasicHttp"];
receiveLocation.TransportTypeData = transportConfigData;
// Save
explorer.SaveChanges();

You can use the following format to set the properties in <CustomProps>:

<CustomProps>
  <ServiceCertificate vt="8" />
  <InboundBodyLocation vt="8">UseBodyElement</InboundBodyLocation>
  <UseSSO vt="11">0</UseSSO>
  <MessageClientCredentialType vt="8">UserName</MessageClientCredentialType>
  <InboundBodyPathExpression vt="8" />
  <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>
  <Identity vt="8">
    <identity>
    <userPrincipalName value="username@contoso.com" />
    </identity>
  </Identity>
  <AlgorithmSuite vt="8">Basic256</AlgorithmSuite>
  <SecurityMode vt="8">None</SecurityMode>
  <TransportClientCredentialType vt="8">None</TransportClientCredentialType>
  <MaxReceivedMessageSize vt="3">2097152</MaxReceivedMessageSize>
  <TextEncoding vt="8">utf-8</TextEncoding>
  <CloseTimeout vt="8">00:01:00</CloseTimeout>
  <SuspendMessageOnFailure vt="11">0</SuspendMessageOnFailure>
  <InboundNodeEncoding vt="8">Xml</InboundNodeEncoding>
  <IncludeExceptionDetailInFaults vt="11">0</IncludeExceptionDetailInFaults>
  <MaxConcurrentCalls vt="3">16</MaxConcurrentCalls>
  <MessageEncoding vt="8">Text</MessageEncoding>
  <OutboundBodyLocation vt="8">UseBodyElement</OutboundBodyLocation>
</CustomProps>

The following table lists the configuration properties that you can set for the 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-BasicHttp adapter leverages the BasicHttpBinding class in the buffered transfer mode to communicate with an endpoint. For the buffered transport mode, the BasicHttpBinding.MaxBufferSize property is always equal to the value of this property.

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

For more information about the member names for the SecurityMode property, see the Security mode property in the WCF-BasicHttp 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: None
TransportClientCredentialType For more information about the member names for the TransportClientCredentialType property, see the Transport client credential type property in WCF-BasicHttp 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: None
MessageClientCredentialType Enum

- UserName
- Certificate

For more information about the member names for the MessageClientCredentialType property, see the Message client credential type property in WCF-BasicHttp 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: UserName
AlgorithmSuite Enum

For more information about the member names for the AlgorithmSuite property, see the Algorithm suite property in WCF-BasicHttp 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-BasicHttp Receive Adapter" in WCF-BasicHttp Transport Properties Dialog Box, Receive, Security tab in the UI guidance and developers API namespace reference.

Default value: False
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-BasicHttp 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: False
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 the send port programmatically

The following code fragment illustrates creating a WCF-BasicHttp send port using the BizTalk Explorer Object Model:

// Use BizTalk Explorer object model to create new WCF-BasicHttp send port.
string server = System.Environment.MachineName;
string database = "BizTalkMgmtDb";
string connectionString = string.Format("Server={0};Database={1};Integrated Security=true", server, database);
string transportConfigData = @"<CustomProps>
                                 <StaticAction vt=""8"">http://www.northwindtraders.com/Service/Operation</StaticAction>
                                 <MessageEncoding vt=""8"">Text</MessageEncoding>
                                 <TextEncoding vt=""8"">utf-8</TextEncoding>
                                 <OpenTimeout vt=""8"">00:01:00</OpenTimeout>
                               </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 static one-way send port
SendPort sendPort = application.AddNewSendPort(false, false);
sendPort.Name = "SampleSendPort";
sendPort.PrimaryTransport.TransportType = explorer.ProtocolTypes["WCF-BasicHttp"];
sendPort.PrimaryTransport.Address = "http://mycomputer/samplepath";
sendPort.PrimaryTransport.TransportTypeData = transportConfigData; // propertyData; // need to change
sendPort.SendPipeline = explorer.Pipelines["Microsoft.BizTalk.DefaultPipelines.PassThruTransmit"];
// Save
explorer.SaveChanges();

You can use the following format to set the properties in <CustomProps>:

<CustomProps>
  <ServiceCertificate vt="8" />
  <InboundBodyLocation vt="8">UseBodyElement</InboundBodyLocation>
  <UseSSO vt="11">0</UseSSO>
  <MessageClientCredentialType vt="8">UserName</MessageClientCredentialType>
  <InboundBodyPathExpression vt="8" />
  <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">None</SecurityMode>
  <TransportClientCredentialType vt="8">None</TransportClientCredentialType>
  <ClientCertificate vt="8" />
  <ProxyUserName vt="8" />
  <MaxReceivedMessageSize vt="3">2097152</MaxReceivedMessageSize>
  <TextEncoding vt="8">utf-8</TextEncoding>
  <StaticAction vt="8">http://www.northwindtraders.com/Service/Operation</StaticAction>
  <CloseTimeout vt="8">00:01:00</CloseTimeout>
  <ProxyToUse vt="8">Default</ProxyToUse>
  <InboundNodeEncoding vt="8">Xml</InboundNodeEncoding>
  <PropagateFaultMessage vt="11">-1</PropagateFaultMessage>
  <ProxyAddress vt="8" />
  <MessageEncoding vt="8">Text</MessageEncoding>
  <OutboundBodyLocation vt="8">UseBodyElement</OutboundBodyLocation>
</CustomProps>

The following table lists the configuration properties that you can set for the send port:

Property name Type Description
SecurityMode Enum

- None
- Message
- Transport
- TransportWithMessageCredential
- TransportCredentialOnly

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

Default value: None
MessageClientCredentialType Enum

- UserName
- Certificate

For more information about the member names for the MessageClientCredentialType property, see the Message client credential type property in WCF-BasicHttp Transport Properties Dialog Box, Send, 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: UserName
TransportClientCredentialType Enum

- None
- Basic
- Windows
- Certificate
- Digest
- Ntlm

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

Default value: None
UserName String Specify the user name to use for authentication with the destination server when the UseSSO property is set to False. You do not have to use the domain\user format for this property.

The default is an empty string.
Password String Specify the password to use for authentication with the destination server when the UseSSO property is set to False.

The default is an empty string.
AffiliateApplicationName String Specify the affiliate application to use for Enterprise Single Sign-On (SSO).

The default is an empty string.
UseSSO Boolean Specify whether to use Single Sign-On to retrieve client credentials for authentication with the destination server.

Default value: False
ClientCertificate String Specify the thumbprint of the X.509 certificate for authenticating this send port to services. This property is required if the ClientCredentialsType property is set to Certificate. The certificate to be used for this property must be installed into the My store in the Current User location.

The default is an empty string.
ServiceCertificate String Specify the thumbprint of the X.509 certificate for authenticating the service to which this send port sends messages. The certificate to be used for this property must be installed into the Other People store in the Local Machine location.

The default is an empty string.
ProxyToUse Enum

- None - Do not use a proxy server for this send port.
- Default - Use the proxy settings in the send handler hosting this send port.
- UserSpecified - Use the proxy server specified in the ProxyAddress property
Specify which proxy server to use for outgoing HTTP traffic.

Default value: None
ProxyAddress String Specify the address of the proxy server. Use the https or the http scheme depending on the security configuration. This address can be followed by a colon and the port number. For example, http://127.0.0.1:8080.

The default is an empty string.
ProxyUserName String Specify the user name to use for the proxy. The WCF-BasicHttp adapter leverages the BasicHttpBinding in the buffered transfer mode to communicate with an endpoint. Proxy credentials of BasicHttpBinding are applicable only when the security mode is Transport, None, or TransportCredentialOnly. If you set the SecurityMode property to Message or TransportWithMessageCredential, the WCF-BasicHttp adapter does not use the credential specified in the ProxyUserName and ProxyPassword properties for authentication against the proxy. Note: The WCF-BasicHttp send adapter uses Basic authentication for the proxy..

The default is an empty string.
ProxyPassword String Specify the password to use for the proxy.

The default is an empty string.
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. This property is valid only for solicit-response ports.
- 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
OutboundBodyLocation Enum

- UseBodyElement - Use the BizTalk message body part to create the content of the SOAP Body element for an outgoing message.
- UseTemplate - Use the template supplied in the OutboundXMLTemplate property to create the content of the SOAP Body element for an outgoing 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.

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. This property is valid only for solicit-response ports.

The default is an empty string.
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 message. This property is required if the OutboundBodyLocation property is set to UseTemplate.

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-BasicHttp send 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. This property is valid only for solicit-response ports.

Default value: XML
StaticAction String Specify the SOAPAction HTTP 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.

The default is an empty string.
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-BasicHttp adapter leverages the BasicHttpBinding class in the buffered transfer mode to communicate with an endpoint. For the buffered transport mode, the BasicHttpBinding.MaxBufferSize property is always equal to the value of this property.

Default value: 65,536
MessageEncoding Enum

- Text - Use a text message encoder.
- Mtom - Use a Message Transmission Organization 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
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 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
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
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
AlgorithmSuite Enum

For more information about the member names for the AlgorithmSuite property, see the Algorithm suite property in WCF-BasicHttp Transport Properties Dialog Box, Send, 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
Identity XML Blob

Example :

<identity>

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

</identity>
Specify the identity of the service that this send port expects. These settings enable this send port to authenticate the service. 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.
PropagateFaultMessage Boolean

- True - Route the message that fails outbound processing to a subscribing application (such as another receive port or orchestration schedule).
- False - Suspend failed messages and generate a negative acknowledgment (NACK).
Specify whether to route or suspend messages failed in outbound processing.

This property is valid only for solicit-response ports.

Default value : True

See Also

What Are the WCF Adapters? Publishing WCF Services with the Isolated WCF Receive Adapters Configuring IIS for the Isolated 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 WCF Adapters Property Schema and Properties Configuring Dynamic Send Ports Using WCF Adapters Context Properties