How to Configure a WCF-Custom Receive Location
You can configure a WCF-Custom 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-Custom 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-Custom adapter uses the default values for the WCF-Custom 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-Custom 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. |
| BindingType | Enum - basicHttpBinding - customBinding - mexHttpBinding - mexHttpsBinding - mexNamedPipeBinding - mexTcpBinding - netMsmqBinding - netNamedPipeBinding - netPeerTcpBinding - netTcpBinding - wsDualHttpBinding - wsFederationHttpBinding - wsHttpBinding |
Specify the type of the binding to use for the endpoint that this receive location uses. Note: If you use a custom binding, the BindingType property can be configured with the custom bindings. For more information about how to use custom binding, see How to Enable the WCF Extensibility Points with the WCF Adapters. The default is an empty string. |
| BindingConfiguration | XML Blob Example: <binding name="netNamedPipeBinding"><security mode="None" /></binding> |
Specify an XML string with the <binding> element to configure different types of predefined bindings provided by Windows Communication Foundation (WCF). For more information about the system-provided binding and custom binding, see the appropriate topics in See Also. Note: BizTalk Server does not support all the types of the binding extension elements that you can configure with the BindingConfiguration property. The default is an empty string. |
| ServiceBehaviorConfiguration | XML Blob Example: <behavior name="SampleServiceBehavior"><serviceMetadata httpGetEnabled="true" httpGetUrl="http://mycomputer:9995/SampleMex" /><serviceCredentials /></behavior> |
Specify an XML string with the <behavior> element of the <serviceBehaviors> element to configure the behavior settings of a WCF service. For more information about the <serviceBehaviors> element, see the appropriate topic in See Also. The default is an empty string. |
| EndpointBehaviorConfiguration | XML Blob Example: <behavior name="sampleBehavior"><callbackTimeouts /></behavior> |
Specify an XML string with the <behavior> element of the <endpointBehaviors> element to configure the behavior settings of a WCF endpoint. For more information about the <endpointBehaviors> element, see the appropriate topic in See Also. Note: BizTalk Server does not support all the types of the behavior extension elements that you can configure with the EndpointBehaviorConfiguration property. The default is an empty string. |
| CredentialType | Enum - None: Do not use any credentials when this receive location sends solicit messages to poll an external service, or this receive location does not need to poll any external service. - IssueTicket: Use Enterprise Single Sign-On (SSO) to retrieve client credentials to issue an SSO ticket. This option requires using the security mode that allows this receive location to impersonate the user account to issue an SSO ticket. - UserAccount: Use the credentials specified in the Username and Password properties when this receive location sends solicit messages to poll an external service. - GetCredentials: Use the SSO affiliate application specified in the AffiliateApplicationName property when this receive location sends solicit messages to poll an external service. |
Specify the type of credentials for this receive location to use when polling an external service Default value: None |
| UserName | String | Specify the user name for this receive location to use when polling an external service to retrieve response messages. This property is required when the CredentialType property is set to UserAccount. The default is an empty string. |
| Password | String | Specify the password for this receive location to use when polling an external service to retrieve response messages. This property is required when the CredentialType property is set to UserAccount. The default is an empty string. |
| AffiliateApplicationName | String | Specify the SSO affiliate application to return external credentials to be used when this receive location sends solicit messages to poll an external service. The specified SSO affiliate application must have a mapping between the Windows account under which this receive location runs and the account for the external service. This property is required when the CredentialType property is set to GetCredentials. The default is an empty string. |
| OrderedProcessing | Boolean | Specify whether to preserve message order when processing messages (for use with the NetMsmq binding). 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-Custom 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. |
| DisableLocationOnFailure | Boolean | Specify whether to disable the receive location that fails inbound processing due to a receive pipeline failure or a routing failure. Default: False |
| 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 |
| ReferencedBindings | XML Blob Example: <BindingConfiguration vt="8"> <wsFederationHttpBinding> <binding name="sampleBinding"> <security mode="Message"> <message issuedKeyType="AsymmetricKey"> <issuer address="http://www.contoso.com/samplests" binding="wsFederationHttpBinding" bindingConfiguration="contosoSTSBinding"/> </message> </security> </binding> </wsFederationHttpBinding> </BindingConfiguration> <ReferencedBindings vt="8"> <bindings> <wsFederationHttpBinding> <binding name="contosoSTSBinding"> <security mode="Message"> <message negotiateServiceCredential="false"> <issuer address="http://northwind.com/samplests" bindingConfiguration="northwindBinding" binding="wsHttpBinding"> </issuer> </message> </security> </binding> </wsFederationHttpBinding> <wsHttpBinding> <binding name="northwindBinding"> <security mode="Message"> <message clientCredentialType="Certificate" /> </security> </binding> </wsHttpBinding> </bindings> </ReferencedBindings> Note: The ReferencedBinding property must not contain the binding configuration used in the BindingConfiguration property. |
Specify the binding configurations referenced by the bindingConfiguration attribute of the <issuer> element for the wsFederationHttpBinding and customBinding, which indicates the Security Token Service (STS) that issues security tokens. For more information about the <issuer> element, see the topic, "<issuer>" at https://go.microsoft.com/fwlink/?LinkId=83476. The binding information including the <issuer> element for the wsFederationHttpBinding and customBinding can be configured through the BindingConfiguration property of the WCF-Custom and the WCF-CustomIsolated adapters. All of the referenced binding configurations for this property must be placed in the form of the <bindings> element. Note: You cannot configure this property on the Binding tab in the transport properties dialog box. You can import and export this property through the Import/Export tab in the transport properties dialog box of the WCF-Custom and WCF-CustomIsolated adapters. Note: The bindingConfiguration attribute of the <issuer> element must refer a valid binding name in this property. Note: The <issuer> element in the referenced binding configurations can also refer to a different binding configuration in t his property if this reference chain does not make a circular dependency. The default is an empty string. |
Configure a WCF-Custom Receive Location with the BizTalk Administration Console
You can set WCF-Custom 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-Custom receive location
If you plan to use the WCF extensibility points such as the custom binding elements, custom behavior element, and custom channel components when configuring the WCF-Custom adapter, you must add the assemblies that implement the extensibility points and all of the dependent assemblies to the global assembly cache on both the BizTalk processing computer (runtime computer) and the administration computer. In addition, you must register the extension components to the machine.config file. For more information about how to use the WCF extensibility points with the WCF Custom adapter, see How to Enable the WCF Extensibility Points with the WCF Adapters.
In the BizTalk Administration console, expand BizTalk Server Administration, expand BizTalk Group, expand Applications, and then expand the application in which you want to create a receive location.
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-Custom from the drop-down list, and then click Configure.
In the WCF-Custom Transport Properties dialog box, on the General tab, configure the endpoint address and the service identity for the WCF-Custom receive location. For more information about the General tab in the WCF-Custom Transport Properties dialog box, see the WCF-Custom Transport Properties Dialog Box, Receive, General tab in the UI guidance and developers API namespace reference.
In the WCF-Custom Transport Properties dialog box, on the Binding tab, configure different types of predefined or custom bindings for WCF. For more information about the Binding tab in the WCF-Custom Transport Properties dialog box, see the WCF-Custom Transport Properties Dialog Box, Receive, Binding tab in the UI guidance and developers API namespace reference.
In the WCF-Custom Transport Properties dialog box, on the Behavior tab, configure the endpoint and service behaviors for this receive location. An endpoint behavior is a set of behavior extension elements that modify or extend service or client functionality. For more information about the Behavior tab in the WCF-Custom Transport Properties dialog box, see the WCF-Custom Transport Properties Dialog Box, Receive, Behavior tab in the UI guidance and developers API namespace reference.
In the WCF-Custom Transport Properties dialog box, on the Other tab, configure which credentials for this receive location to use when polling an external service, and whether this receive location preserves message order when processing messages. For more information about the Other tab in the WCF-Custom Transport Properties dialog box, see the WCF-Custom Transport Properties Dialog Box, Receive, Other tab in the UI guidance and developers API namespace reference.
In the WCF-Custom 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-Custom Transport Properties dialog box, see the WCF-Custom Transport Properties Dialog Box, Receive, Messages tab in the UI guidance and developers API namespace reference.
In the WCF-Custom Transport Properties dialog box, on the Import/Export tab, import and export the Address (URI) and Endpoint Identity properties on the General tab, binding information on the Binding tab, and endpoint behavior on the Behavior tab for this receive location. For more information about the Import/Export tab in the WCF-Custom Transport Properties dialog box, see the WCF-Custom Transport Properties Dialog Box, Receive, Import-Export tab in the UI guidance and developers API namespace reference.
Configure a WCF-Custom Receive Location programmatically
You can use the following format to set the properties:
<CustomProps>
<InboundBodyPathExpression vt="8" />
<InboundBodyLocation vt="8">UseBodyElement</InboundBodyLocation>
<BindingConfiguration vt="8"><binding name="netNamedPipeBinding"><security mode="None" /></binding></BindingConfiguration>
<OutboundXmlTemplate vt="8"><bts-msg-body xmlns="http://www.microsoft.com/schemas/bts2007" encoding="xml"/></OutboundXmlTemplate>
<CredentialType vt="8">GetCredentials</CredentialType>
<Identity vt="8" />
<ServiceBehaviorConfiguration vt="8"><behavior name="SampleServiceBehavior"><serviceMetadata httpGetEnabled="true" httpGetUrl="http://mycomputer:9995/SampleService/Mex" /><serviceCredentials /></behavior></ServiceBehaviorConfiguration>
<Password vt="1" />
<OrderedProcessing vt="11">-1</OrderedProcessing>
<IncludeExceptionDetailInFaults vt="11">0</IncludeExceptionDetailInFaults>
<AffiliateApplicationName vt="8">SampleAffiliateApplication</AffiliateApplicationName>
<DisableLocationOnFailure vt="11">0</DisableLocationOnFailure>
<SuspendMessageOnFailure vt="11">0</SuspendMessageOnFailure>
<BindingType vt="8">netNamedPipeBinding</BindingType>
<UserName vt="8">Hello</UserName>
<InboundNodeEncoding vt="8">Xml</InboundNodeEncoding>
<EndpointBehaviorConfiguration vt="8"><behavior name="EndpointBehavior" /></EndpointBehaviorConfiguration>
<OutboundBodyLocation vt="8">UseBodyElement</OutboundBodyLocation>
</CustomProps>
The following code fragment illustrates creating a WCF-Custom 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-Custom 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>
<BindingConfiguration vt=""8""><binding name=""netNamedPipeBinding""><security mode=""None"" /></binding></BindingConfiguration>
<BindingType vt=""8"">netNamedPipeBinding</BindingType>
</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-Custom
int i = 0;
for(i=0; i < explorer.ReceiveHandlers.Count; ++i)
{
if("WCF-Custom" == explorer.ReceiveHandlers[i].TransportType.Name)
break;
}
receiveLocation.ReceiveHandler = explorer.ReceiveHandlers[i];
receiveLocation.Address = "net.pipe://mycomputer/samplePipeName";
receiveLocation.ReceivePipeline = explorer.Pipelines["Microsoft.BizTalk.DefaultPipelines.PassThruReceive"];
receiveLocation.TransportType = explorer.ProtocolTypes["WCF-Custom"];
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 Configuring the WCF-Custom Adapter How to Create an Affiliate Application <behavior> of <endpointBehaviors> <bindings> <behavior> of <serviceBehaviors>