如何設定 WCF-WSHttp 接收位置

發行項
05/04/2023

您可以用程式設計方式或使用「BizTalk 管理」主控台來設定 WCF-WSHttp 接收位置。

設定屬性

「BizTalk 總管物件模型」可讓您以程式設計的方式建立和設定接收位置。 BizTalk Explorer 物件模型會公開具有TransportTypeData讀取/寫入屬性的IReceiveLocation接收位置組態介面。這個屬性會以 XML 字串之名稱-值配對的格式接受 WCF-WSHttp 接收位置組態屬性包。若要在 BizTalk Explorer 物件模型中設定此屬性，您必須設定IReceiveLocation介面的InboundTransportLocation屬性。

不需要設定 IReceiveLocation介面的TransportTypeData屬性。若沒有設定此屬性，WCF-WSHttp 配接器就會針對 WCF-WSHttp 接收位置組態使用預設值，如下表所示。

下表列出您可以在「BizTalk 總管物件模型」中針對 WCF-WSHttp 接收位置設定的組態屬性。

屬性名稱	類型	描述
身分識別	XML BLOB 範例： <身分識別> <userPrincipalName value=「 username@contoso.com 」 /> </身份>	指定此接收位置所提供服務的識別。可針對 Identity 屬性指定的值會根據安全性設定而有所不同。這些設定可讓用戶端驗證此接收位置。在用戶端與服務之間的交握程序中，Windows Communication Foundation (WCF) 基礎結構可確保預期之服務的識別能夠與這個項目的值相符。預設為空字串。
OpenTimeout	System.TimeSpan	指定時間值，表示可供完成通道開啟作業的時間間隔。預設值：00:01:00
SendTimeout	System.TimeSpan	指定時間值，表示可供完成傳送作業的時間間隔。如果您使用要求-回應接收埠，這個值會指定完成整個互動的時間長度，即使服務傳回很大的訊息也是如此。預設值：00:01:00
CloseTimeout	System.TimeSpan	指定時間值，表示可供完成通道關閉作業的時間間隔。預設值：00:01:00
MaxReceivedMessageSize	整數	指定訊息的大小上限，以位元組為單位， (包括可在網路接收的標頭) 。訊息的大小受限於配置給每個訊息的記憶體數量。您可以使用這個屬性來限制遭受拒絕服務 (DoS) 攻擊的風險程度。預設值：65536
MessageEncoding	列舉 - Text - 使用簡訊編碼器。 - Mtom - 使用訊息傳輸優化機制 1.0 (MTOM) 編碼器。	指定用來為 SOAP 訊息編碼的編碼器。預設值：文字
TextEncoding	列舉 - unicodeFFF - Unicode BigEndian 編碼。 - utf-16 - 16 位編碼。 - utf-8 - 8 位編碼	指定當 MessageEncoding 屬性設定為 Text時，要用於在系結上發出訊息的字元集編碼。預設值： utf-8
EnableTransaction	Boolean	指定是否使用來自用戶端的交易，將訊息提交至 MessageBox 資料庫。如果此屬性為 `True` ，用戶端必須使用 WS-AtomicTransaction 通訊協定來提交訊息。如果用戶端在交易式範圍以外提交訊息，這個接收位置會將例外狀況傳回至用戶端，而不會擱置任何訊息。此選項只適用於單向接收位置。如果用戶端在要求-回應接收位置的交易式內容中提交訊息，則會將例外狀況傳回至用戶端，而不會擱置任何訊息。預設值：`False`
MaxConcurrentCalls	整數	指定對單一服務執行個體的並行呼叫數目。超出上限的呼叫將排入佇列。此屬性的範圍介於 1 和 Int32.MaxValue 之間。預設值：200
SecurityMode	列舉 - 無 - 消息 - 運輸 - TransportWithMessageCredential 如需SecurityMode屬性成員名稱的詳細資訊，請參閱UI 指引和開發人員 API 命名空間參考中的WCF-WSHttp 傳輸屬性對話方塊、接收、安全性索引標籤中的安全性模式屬性。	指定使用的安全性類型。預設值：訊息
TransportClientCredentialType	列舉 - 無 - 基本 - Ntlm - Windows - 證書如需TransportClientCredentialType屬性成員名稱的詳細資訊，請參閱UI 指引和開發人員 API 命名空間參考中WCF-WSHttp 傳輸屬性對話方塊、接收、安全性索引標籤中的傳輸用戶端認證類型屬性。	指定在執行用戶端驗證時，所要使用的認證類型。預設值： Windows
MessageClientCredentialType	列舉 - 無 - Windows - 使用者 - 證書如需MessageClientCredentialType屬性成員名稱的詳細資訊，請參閱WCF-WSHttp 傳輸屬性對話方塊、接收、安全性索引標籤中的 [WCF-WSHttp 傳輸屬性] 對話方塊、[接收]、[安全性] 索引標籤和開發人員 API 命名空間參考。	指定當使用以訊息為基礎的安全性來執行用戶端驗證時，所要使用的認證類型。預設值： Windows
AlgorithmSuite	列舉如需AlgorithmSuite屬性成員名稱的詳細資訊，請參閱UI 指引和開發人員 API 命名空間參考中的WCF-WSHttp 傳輸屬性對話方塊、接收、安全性索引標籤中的Algorithm suite屬性。	指定訊息加密和 Key Wrap 演算法。這些演算法會對應到安全性原則語言 (WS-SecurityPolicy) 規格中所指定的演算法。預設值： Basic256
NegotiateServiceCredential	Boolean	指定是否會在超出範圍的用戶端提供此服務認證，或是透過交涉程序從此服務取得服務認證給用戶端。此類交涉是一般訊息交換的前兆。如果 MessageClientCredentialType 屬性等於 None、 Username或 Certificate，將此屬性設定為 False 表示服務憑證可在頻外用戶端使用，而且用戶端需要指定服務憑證。這個模式可與實作 WS-Trust 和 WS-SecureConversation 的 SOAP 堆疊互通。如果 MessageClientCredentialType 屬性設定為 Windows，請將此屬性設定為 False 會指定 Kerberos 型驗證。這表示用戶端和服務必須屬於同一個 Kerberos 網域。這個模式可與實作 Kerberos 語彙基元設定檔 (如在 OASIS WSS TC 所定義) 以及 WS-Trust 和 WS-SecureConversation 的 SOAP 堆疊互通。當此屬性為 True時，它會導致 .NET SOAP 交涉，以透過 SOAP 訊息進行 SPNego 交換。預設值： True
EstablishSecurityCoNtext	Boolean	指定此安全性通道是否會建立安全的工作階段。安全工作階段會先建立安全性內容權杖 (SCT)，再交換應用程式訊息。預設值： True
ServiceCertificate	字串	針對此接收位置指定用戶端用來驗證服務之 X.509 憑證的憑證指紋。要用於此屬性的憑證必須安裝在[目前使用者] 位置的[我的存放區] 中。注意：您必須針對裝載此接收位置的接收處理常式，將服務憑證安裝到使用者帳戶的目前使用者位置。預設為空字串。
UseSSO	Boolean	指定是否使用「企業單一登入」(SSO) 來擷取用戶端認證，以便發出 SSO 票證。 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	列舉 - UseBodyElement - 使用傳入訊息的 SOAP Body 元素內容來建立 BizTalk 訊息本文部分。如果 Body 元素有一個以上的子元素，則只有第一個元素會成為 BizTalk 訊息內文部分。 - UseEnvelope - 從傳入訊息的整個 SOAP 信封建立 BizTalk 訊息本文部分。 - UseBodyPath - 使用 InboundBodyPathExpression 屬性中的本文路徑運算式來建立 BizTalk 訊息本文部分。內文路徑運算式會依照內送訊息 SOAP Body 元素的直系子元素來進行評估。此屬性只對請求-回應連接埠有效。如需如何使用 InboundBodyLocation 屬性的詳細資訊，請參閱指定 WCF 配接器的訊息本文。	為傳入 WCF 訊息的 SOAP Body 元素指定資料選取範圍。預設值： UseBodyElement
InboundBodyPathExpression	字串如需如何使用 InboundBodyPathExpression 屬性的詳細資訊，請參閱 WCF 配接器屬性架構和屬性。	指定內文路徑運算式來識別用於建立 BizTalk 訊息內文部分之內送訊息的特定部分。此本文路徑運算式會根據傳入訊息之 SOAP Body 節點的立即子項目進行評估。如果此內文路徑運算式傳回一個以上的節點，則只會為 BizTalk 訊息內文部分選擇第一個節點。如果 InboundBodyLocation 屬性設定為 UseBodyPath，則需要這個屬性。預設為空字串。
InboundNodeEncoding	列舉 - Base64 - Base64 編碼。 - 十六進位 - 十六進位編碼。 - 字串 - 文字編碼 - UTF-8。 - XML - WCF 配接器會使用 InboundBodyPathExpression中主體路徑運算式所選取節點的外部 XML，建立 BizTalk 訊息本文。	指定 WCF-WSHttp 接收配接器用來解碼 InboundBodyPathExpression中所指定主體路徑運算式所識別的節點編碼類型。如果 InboundBodyLocation 屬性設定為 UseBodyPath，則需要這個屬性。預設值： XML
OutboundBodyLocation	列舉 - UseBodyElement - 使用 BizTalk 訊息本文部分，為傳出回應訊息建立 SOAP Body 元素的內容。 - UseTemplate - 使用 OutboundXMLTemplate 屬性中提供的範本，為傳出回應訊息建立 SOAP Body 元素的內容。如需如何使用 OutboundBodyLocation 屬性的詳細資訊，請參閱指定 WCF 配接器的訊息本文。	為傳出 WCF 訊息的 SOAP Body 元素指定資料選取範圍。此屬性只適用於要求-回應接收位置。預設值： UseBodyElement
OutboundXMLTemplate	字串如需如何使用 OutboundXMLTemplate 屬性的詳細資訊，請參閱指定 WCF 配接器的訊息本文。	指定 XML 格式的範本，以取得傳出回應訊息之 SOAP Body 元素的內容。如果 OutboundBodyLocation 屬性設定為 UseTemplate，則需要這個屬性。此屬性只適用於要求-回應接收位置。預設為空字串。
SuspendMessageOnFailure	Boolean	指定是否擱置因接收管線失敗或路由失敗而造成輸入處理失敗的要求訊息。預設值： True
IncludeExceptionDetailInFaults	Boolean	指定基於偵錯目的傳回用戶端的 SOAP 錯誤詳細資料中，是否包括 Managed 例外狀況資訊。預設值： False

使用 BizTalk 管理主控台設定 WCF-WSHttp 接收位置

您可以在「BizTalk 管理」主控台中設定 WCF-WSHttp 接收位置配接器變數。若接收位置並未設定屬性，系統就會使用 [BizTalk 管理主控台] 中的預設接收處理常式值。

注意

完成下列程序之前，您必須已經新增接收埠。如需詳細資訊，請參閱如何建立接收埠。

設定 WCF-WSHttp 接收位置的變數

在 BizTalk 管理主控台中，依序展開 [BizTalk Server系統管理]、[BizTalk 群組]、[應用程式] 和 [應用程式] ，然後展開您要建立接收位置的應用程式。
在 [BizTalk 管理主控台] 的左窗格中，按一下 [接收埠] 節點。然後在右窗格中，使用滑鼠右鍵按一下與現有接收位置關聯的接收埠，或是您要與新接收位置關聯的接收埠，然後按一下 [屬性]。
在 [ 接收埠內容] 對話方塊的左窗格中，選取 [ 接收位置]，然後在右窗格中按兩下現有的接收位置，或按一下 [ 新增] 以建立新的接收位置。
在 [接收位置屬性] 對話方塊的[類型] 旁的 [傳輸] 區段中，從下拉式清單中選取[WCF-WSHttp]，然後按一下 [設定]。
在 [WCF-WSHttp 傳輸屬性 ] 對話方塊的 [ 一般 ] 索引標籤上，設定 WCF-WSHttp 接收位置的端點位址和服務識別。如需WCF-WSHttp 傳輸屬性對話方塊中 [一般] 索引標籤的詳細資訊，請參閱UI 指引和開發人員 API 命名空間參考中的WCF-WSHttp 傳輸屬性對話方塊、接收、一般索引標籤。
在 [WCF-WSHttp 傳輸屬性 ] 對話方塊的 [ 系結] 索引標籤上，設定逾時、編碼和交易屬性。如需WCF-WSHttp 傳輸屬性對話方塊中 [系結] 索引標籤的詳細資訊，請參閱UI 指引和開發人員 API 命名空間參考中的WCF-WSHttp 傳輸屬性對話方塊、接收、系結索引標籤。
在 [WCF-WSHttp 傳輸屬性 ] 對話方塊的 [ 安全性 ] 索引標籤上，定義 WCF-WSHttp 接收位置的安全性功能。如需WCF-WSHttp 傳輸屬性對話方塊中 [安全性] 索引標籤的詳細資訊，請參閱UI 指引和開發人員 API 命名空間參考中的WCF-WSHttp 傳輸屬性對話方塊、接收、安全性索引標籤。
在 [WCF-WSHttp 傳輸屬性 ] 對話方塊的 [ 訊息 ] 索引標籤上，指定 SOAP Body 元素的資料選取範圍。如需WCF-WSHttp 傳輸屬性對話方塊中 [訊息] 索引標籤的詳細資訊，請參閱UI 指引和開發人員 API 命名空間參考中的WCF-WSHttp 傳輸屬性對話方塊、接收、訊息索引標籤。

以程式設計方式設定 WCF-WSHttp 接收位置

您可以使用下列格式來設定屬性：

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

下列程式碼片段會說明如何建立 WCF-WSHttp 接收位置：

// 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();

另請參閱

利用外掛式 WCF 接收配接器發佈 WCF 服務
 針對外掛式 WCF 接收配接器設定 IIS
管理 BizTalk 主控件和主控件執行個體
 如何變更服務帳戶和密碼
 安裝 WCF 配接器的憑證
 指定 WCF 配接器的訊息內文
 設定 WCF-WSHttp 配接器

共用方式為