逐步解說：使用 XML 信封 (基本)

發行項
07/21/2023

此範例藉由實作虛構錯誤追蹤系統的一部分，示範基本的 XML 信封解譯。這個範例符合下列需求：

錯誤訊息記錄到公司內各個不同的實體網站，再傳送至一個集中位置處理後放入各個後端系統。
錯誤訊息會以 XML 格式寫入。
錯誤訊息可以單獨傳送，而不使用信封，也可以包含在信封中進行批次傳送。

必要條件

若要執行本範例，您必須已熟悉如何建立 BizTalk Server 專案、簽署組件，及使用 BizTalk Server 管理主控台檢視應用程式和連接埠。您也應該熟悉逐步解說：部署基本 BizTalk 應用程式中所述的想法。

本範例的工作項目

此範例定義信封結構描述並使用 XmlDisassembler 管線，以處理內含單一錯誤訊息或批次錯誤訊息的內送訊息。

範例

若要建立範例，請依照以下各節所列的步驟進行。

建立新的 BizTalk 專案

建置方案前，您必須建立 BizTalk 專案、確定其具備強式名稱，並為其指定應用程式名稱。指定應用程式名稱可避免 BizTalk Server 將方案部署至預設的 BizTalk 應用程式。

建立和設定新的 BizTalk 專案

使用 Visual Studio 建立新的 BizTalk 專案。呼叫專案 BasicXMLEnvelope。
產生金鑰檔並將其指派給專案。如需這項工作的詳細資訊，請參閱如何設定強式名稱元件金鑰檔案。
在專案的部署組態屬性中，將 [應用程式名稱 ] 指派給，並將 [重新開機主機實例 ] 設定為 True 。設定此旗標係指示主控件清除組件所有已快取的執行個體。

建立 Error 結構描述

在此步驟中，您要建立 Error 結構描述。它會定義系統的關鍵訊息。

若要建立 Error 結構描述

新增名稱為 "Error" 的結構描述至專案。
將架構的目標命名空間變更為 http://BasicXMLEnvelope 。
將 [進階] 類別下的 schema 屬性Element FormDefault變更為[限定]。這表示區域宣告項目必須由執行個體文件中的目標命名空間限定。
重新命名根節點為 "Error"，並建立下列五個子項目 (括號內顯示其個別的類型)：
- ID (xs:int)
- Type (xs:int)
- Priority (xs:string)
- Description (xs:string)
- ErrorDateTime (xs:string)
  
  您的結構描述應該如下所示：

建立此結構描述的範例訊息。這會用來確認是否正確處理了信封外部的單一訊息。下列是範例訊息：

<Error xmlns="http://BasicXMLEnvelope">  
  <ID>1</ID>  
  <Type>5</Type>  
  <Priority>Low</Priority>  
  <Description>Sprocket widget prints reports slowly.</Description>  
  <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
</Error>

將此訊息儲存到專案目錄中的檔案。

建立信封結構描述

信封包含一或多個錯誤訊息。在這個基本範例中，信封本身沒有屬性和項目。

若要建立信封結構描述

新增名稱為 "Envelope" 的結構描述至 BasicXMLEnvelope 專案。
將目標命名空間變更為 http://BasicXMLEnvelope 。
將根節點的名稱，由 "Root" 變更為 "Envelope"。
現在將結構描述標示為信封結構描述。按一下 [< 架構 >] 節點。在 [屬性] 窗格中，將架構參考屬性 Envelope 設定為 OK 。
設定 Body XPath 屬性。若要這樣做，請按一下 [信封 ] 節點。在屬性視窗中，按一下本文 XPath屬性中的省略號 (...) 按鈕，選取[信封]，然後按一下 [確定]。
新增 Any 項目子系至 [Envelope] 節點。錯誤訊息將會包含在此項目中。您的結構描述應該如下所示：

建立包含信封及一或多則範例訊息的範例訊息。範例訊息如下：

<Envelope xmlns="http://BasicXMLEnvelope">  
  <Error>  
    <ID>102</ID>  
    <Type>0</Type>  
    <Priority>High</Priority>  
    <Description>Sprocket query fails.</Description>  
    <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
  </Error>  
  <Error>  
    <ID>16502</ID>  
    <Type>2</Type>  
    <Priority>Low</Priority>  
    <Description>Time threshold exceeded.</Description>  
    <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
  </Error>  
</Envelope>

將此訊息儲存到專案目錄中的檔案。

部署並設定傳送埠和接收埠

建立結構描述後，您必須編譯並部署專案。一旦專案部署完成，即可使用「BizTalk Server 管理主控台」設定傳送埠和接收埠。

若要部署 BasicXMLEnvelope

從 Visual Studio，從 [建置] 功能表選擇 [部署 BasicXMLEnvelope ]。這會在 BizTalk Server 中建置並部署為應用程式 "BasicXMLEnvelope"。
在 BizTalk Server 管理主控台中，展開[應用程式] 群組，確認BasicXMLEnvelope是否以自訂應用程式的形式出現。

設定接收埠

使用 Windows 檔案總管，在 BasicXMLEnvelope 專案目錄下建立名為「Receive」的目錄。
在 BizTalk Server 管理主控台中，展開BasicXMLEnvelope應用程式，以滑鼠右鍵按一下[接收埠]，指向 [新增]，然後按一下[單向接收埠]。
在 [ 接收埠屬性 ] 對話方塊中，將埠的名稱設定為「Receive」。
以滑鼠右鍵按一下 [接收位置]，然後按一下 [ 新增 ] 以新增接收埠。將新連接埠命名為 "ReceiveError"。將 接收管線 設定為 XMLReceive。針對 [傳輸類型]，選取 [檔案]，然後按一下 [ 設定]。
選取上面建立的接收目錄，然後按一下 [ 確定]。接收埠即設定完成。按一下 [確定 ] 以關閉。

設定傳送埠

使用 Windows 檔案總管在 BasicXMLEnvelope 專案目錄下建立名為「Send」的目錄。
在 [BizTalk Server管理主控台] 中，展開[BasicXMLEnvelope] 應用程式，以滑鼠右鍵按一下 [傳送埠]，指向 [新增]，然後按一下 [靜態單向]。
在 [ 傳送埠屬性 ] 對話方塊中，將埠的名稱設定為 [傳送]。
針對 [傳輸類型]，選取 [檔案]，然後按一下 [ 設定]。將目的地資料夾設定為您稍早建立的傳送目錄，然後按一下 [ 確定]。
按一下 [ 篩選 ] 並新增單一篩選：
- Bts。MessageType == http://BasicXMLEnvelope#Error
按一下 [確定 ] 以完成傳送埠設定。傳送埠即設定完成。

執行範例

現在即可開始執行範例。在使用 BizTalk Server 管理主控台啟動 BasicXMLEnvelope 應用程式後，您應將測試檔案複製到接收位置，然後檢查傳送位置所產生的結果。

若要執行 BasicXMLEnvelope 範例

在 BizTalk Server 管理主控台中，以滑鼠右鍵按一下BasicXMLEnvelope應用程式，然後按一下 [啟動]。這樣就會登錄並啟動傳送埠和接收埠。
將每一個範例檔案拖曳到接收目錄中。如果使用先前提供的範例，您應該會在處理完成時發現傳送位置中有三則個別的錯誤訊息。

延伸範例

您可以擴充這個範例以配合其他需求。本節說明兩種常見的案例：

如果是將錯誤批次放在信封中提交，則解譯中的個別訊息失敗應該不會阻止進一步處理其他未失敗的訊息。
這些錯誤應該會按照優先順序，傳送到不同的位置。高優先順序的訊息會被加速處理，而其他優先順序則透過一般通道處理。

下列各節會擴充範例以處理這些需求。

可復原交換處理

BizTalk Server支援可復原的交換處理。藉由使用這項功能，您可以確保訊息批次在解譯中發生失敗時，不會整個批次都失敗，而只限於個別的訊息。

若要設定可復原交換處理的範例。

在 BizTalk Server 管理主控台中，展開[BasicXMLEnvelope] 應用程式，按一下 [接收埠]，然後按兩下 [接收埠]。這是您先前建立的連接埠。
在 [ 接收埠屬性 ] 對話方塊中，按一下 [ 接收位置]。按一下 [屬性 ] 以顯示 [ReceiveError 接收位置屬性 ] 對話方塊。按一下 [接收管線] 的省略號 (...) 按鈕。
在 [ 設定管線 - XMLReceive ] 對話方塊中，將 [ 可復原交換處理 ] 屬性設定為 True ，然後按一下 [ 確定]。
按一下 [確定 ] 關閉 [ 接收位置屬性 ] 對話方塊，然後按一下 [ 確定 ] 以關閉 [ 接收埠屬性 ] 對話方塊。

若要建立範例檔案，然後執行範例

若要建立範例檔案，請產生範例中所建立之信封範例檔案的複本、將不存在的命名空間加入至其中一個 Error 執行個體，然後儲存檔案：

<Envelope xmlns="http://BasicXMLEnvelope">  
  <Error>  
    <ID>102</ID>  
    <Type>0</Type>  
    <Priority>High</Priority>  
    <Description>Sprocket query fails to return any sprockets even though some exist</Description>  
    <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
  </Error>  
  <Error xmlns="http://ThisIsAnError">  
    <ID>16502</ID>  
    <Type>2</Type>  
    <Priority>Low</Priority>  
    <Description>Time threshold exceeded.</Description>  
    <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
  </Error>  
</Envelope>

在 BizTalk Server 管理主控台中，按一下 [應用程式]，並確認BasicXMLEnvelope應用程式正在執行。
將訊息拖曳到接收位置中。處理之後，您應該會發現傳送位置中有第一個訊息，而第二個 (低優先順序) 訊息則是在擱置佇列中。

以內容為基礎的路由 (CBR)

您可以使用以內容為基礎的路由，根據訊息的內容來傳送路由訊息。在此案例中，路由會根據優先順序進行，「高」優先順序訊息會進入一個傳送位置，而「低」和「中」優先順序訊息則進入不同的傳送位置。

若要擴充範例，您必須完成下列工作：

在 BasicXMLEnvelope 專案中，升級 [錯誤架構] 中的 [ 優先順序] 欄位。以內容為基礎的路由需要升級的屬性才能路由傳送訊息。如需詳細資訊，請參閱升級屬性。
建立和設定兩個額外的傳送埠。這些連接埠會使用篩選條件來確保收到適當的訊息。

升級 Error 結構描述中的 Priority 欄位

在 Visual Studio 中開啟 BasicXMLEnvelope 專案時，開啟 [錯誤 ] 架構並展開 [ 錯誤 ] 節點。
以滑鼠右鍵按一下 Priority 元素，指向 [ 升階]，然後按一下 [ 快速升級]。
按一下 [確定 ] 以確認已升級屬性新增屬性架構。
在 Visual Studio 的方案總管中，開啟新的屬性架構 PropertySchema.xsd。從架構中移除「Field1」。
現在，重新編譯並重新部署方案。在 [建置] 功能表中，選擇 [部署 BasicXMLEnvelope]。
此專案已設定為要在重新部署方案時重設主控件執行個體。如果您變更了這個設定，就必須先停止再啟動主控件。

設定低和中等優先順序的傳送埠

使用 Windows 檔案總管在 BasicXMLEnvelope 專案目錄下建立名為「SendLowMediumPriority」的目錄。
在 BizTalk Server 管理主控台中，展開[BasicXMLEnvelope] 應用程式，以滑鼠右鍵按一下 [傳送埠]，指向 [新增]，然後按一下 [靜態單向]。
在 [ 傳送埠屬性 ] 對話方塊中，將埠的名稱設定為「SendLowMediumPriority」。
針對 [傳輸類型]，選取 [ FILE]，然後按一下 [ 設定]。將目的資料夾設定為剛才建立的目錄。按一下 [確定 ] 以關閉。
按一下 [篩選] ，然後新增三個篩選運算式：
- Bts。MessageType == http://BasicXMLEnvelope#Error And
- BasicXMLEnvelope.PropertySchema.Priority == Low Or
- BasicXMLEnvelope.PropertySchema.Priority == Medium
按一下 [確定 ] 以完成低優先順序和中優先順序的傳送埠設定。

設定高優先順序的傳送埠

使用 Windows 檔案總管在 BasicXMLEnvelope 專案目錄下建立名為「SendHighPriority」的目錄。
在 BizTalk Server 管理主控台中，展開[BasicXMLEnvelope] 應用程式，以滑鼠右鍵按一下 [傳送埠]，指向 [新增]，然後按一下 [靜態單向]。
在 [ 傳送埠屬性 ] 對話方塊中，將埠的名稱設定為「SendHighPriority」。
針對 [傳輸類型]，選取 [ FILE]，然後按一下 [ 設定]。將目的資料夾設定為剛才建立的目錄。按一下 [確定 ] 以關閉。
按一下 [篩選] ，然後新增兩個篩選運算式：
- Bts。MessageType == http://BasicXMLEnvelope#Error And
- BasicXMLEnvelope.PropertySchema.Priority == High
按一下 [確定 ] 以完成高優先順序的傳送埠設定。

測試路由方案

在 BizTalk Server 管理主控台中，展開 [應用程式] 群組，以滑鼠右鍵按一下[BasicXMLEnvelope] 應用程式，然後按一下 [啟動]。 當系統提示您確認時，按一下 [ 開始]。這樣就會登錄新的傳送埠。
將測試訊息拖曳到接收位置中。請注意錯誤訊息是如何路由傳送至不同的傳送位置：
- 具有「低」、「中」或「高」優先順序，且順利通過訊息處理的錯誤訊息，會路由傳送至原始傳送位置 (基本範例中所設定的) 及依優先順序區分的傳送位置。如果是具有「低」或「中」優先順序的訊息，原始傳送位置及「低/中」傳送位置內都會出現其複本。
- 如果已啟用可復原的交換處理，則不會路由傳送失敗的錯誤訊息，且未處理的訊息會如預期般正確路由傳送。之所以不會傳送失敗訊息，是因為其訊息類型與篩選條件中使用的類型不相符。

另請參閱

可復原交換處理
 升級屬性
 CBRSample (BizTalk Server 範例)

共用方式為