File 配接器 (BizTalk Server 範例)
檔案配接器範例是以 Microsoft Visual C# .NET 撰寫，以使用 Microsoft BizTalk Server。 此範例提供可建置動態或靜態配接器的程式碼。 不過，下列程序僅概述靜態配接器。 靜態配接器具有一組靜態結構描述，且沒有自訂使用者介面。 動態配接器具有自訂使用者介面，並且可能有一組動態結構描述。 靜態和動態配接器都使用「新增配接器精靈」將結構描述新增至 BizTalk 專案。
注意
檔案配接器範例與隨附于 BizTalk Server 的原生 FILE 配接器不同。 因此，使用此範例選取傳輸類型時，請選取「靜態」，不要選取 FILE。
具有自訂使用者介面並且可能有一組動態結構描述的動態配接器，在配接器管理方面將需要額外的程式碼。 若要進一步瞭解動態架構集的使用，請參閱 動態 Design-Time 配接器組態。
此範例的用途
範例配接器會從檔案資料夾複製檔案、提交至 BizTalk 做為訊息，或從BizTalk Server擷取訊息並卸載至檔案資料夾。 它提供可建置動態或靜態配接器的程式碼；不過，下列程序僅概述靜態配接器。 靜態配接器具有一組靜態結構描述，且沒有自訂使用者介面。 動態配接器具有自訂使用者介面，並且可能有一組動態結構描述。 靜態和動態配接器都使用「新增配接器精靈」將結構描述新增至 BizTalk 專案。
您可以將範例 FILE 配接器當做範本，建立其他自訂配接器。
可在何處找到此範例
<範例路徑>\AdaptersDevelopment\File Adapter
注意
當執行 32 位版本的 Windows 的電腦上安裝BizTalk Server時，範例路徑> 的預設位置 < 為%ProgramFiles%\Microsoft BizTalk Server\SDK\Samples。 當執行 64 位版本的 Windows 時，範例路徑> 的預設位置 < 是%ProgramFiles (x86) %\Microsoft BizTalk Server\SDK\BizTalk Server Samples。 若要判斷與 %ProgramFiles% 或 %ProgramFiles 相關聯的值， (x86) % 環境變數類型 會回應 %ProgramFiles% 或回應 %ProgramFiles (x86) % ，然後按 ENTER。 如果在 64 位作業系統上執行此範例，您必須在執行 .reg 檔案之前，將任何 .reg 檔案中的所有參考從%ProgramFiles%變更為%ProgramFiles (x86) %。
下表顯示此範例中的檔案，並說明其用途。
| \File Adapter 檔案 | Description |
|---|---|
| \BizTalk Project 檔案 | 包含配接器控管專案，可用來測試範例配接器。 |
| \Design Time 檔案 | 包含設計階段和管理專案 (AdapterManagement.csproj)。 |
| \Runtime 檔案 | 包含執行階段檔案複製接收和傳輸專案 (DotNetFile.csproj)。 |
| DynamicAdapterManagement.reg | 註冊範例動態配接器。 |
| Instance.xml | 透過 FILE 配接器傳遞的範例檔案。 |
| StaticAdapterManagement.reg | 註冊範例靜態配接器。 |
| \BizTalk Project\Adapter Harness 檔案 | Description |
|---|---|
| AdapterHarness.odx、AdapterHarness.sln、AdapterHarnessProject.btproj | 提供適用於 BizTalk 專案的專案、解決方案和相關檔案。 |
| mySchema.xsd | 提供控管協調流程所預期的 Instance.xml 結構描述 (來自配接器的接收部分)，以及由協調流程傳遞到配接器的傳送部分的 Instance.xml 結構描述。 |
| \Design Time\Adapter Management 檔案 | Description |
|---|---|
| AdapterManagement.cs、AdapterManagement.csproj、AdapterManagement.sln | 適用於配接器設計階段的專案、解決方案和相關檔案。 |
| AssemblyInfo.cs | 包含此範例的組件資訊。 |
| CategorySchema2.xml | 範例配接器不使用。 |
| CategorySchema.xml | 包含靜態配接器的服務組織樹狀結構。 |
| DotNetFileResource.resx | 包含資源。 |
| ReceiveHandler.xsd、ReceiveLocation.xsd | 包含接收端處理常式和結束點自訂屬性結構描述 |
| service1.wsdl | 包含配接器的作業定義。 |
| TransmitHandler.xsd、TransmitLocation.xsd | 包含傳輸端處理常式和結束點自訂屬性結構描述 |
| \Runtime 檔案 | Description |
|---|---|
| DotNetFile.csproj、DotNetFile.sln, AssemblyInfo.cs、 DotNetFileExceptions.cs、DotNetFileProperties.cs、DotNetFileReceiver.cs、DotNetFileReceiverEndPoint.cs、DotNetFileTransmitter.cs、 DotNetFileTransmitterEndpoint.cs、 DotNetFileAsyncTransmitterBatch.cs、 BatchMessage.cs |
適用於執行階段檔案複製傳送和接收配接器的檔案。 您可以修改並以新名稱儲存這些檔案，做為自訂元件。 DotNetFile.csproj 和 DotNetFile.sln 是專案與方案檔。 AssemblyInfo.cs 包含此範例的組件資訊。 DotNetFileReceiver.cs 會從接收位置讀取檔案，並將檔案提交至 BizTalk Server。 DotNetFileExceptions.cs 會在處理訊息期間實作程式碼以處理例外狀況 DotNetFileProperties.cs 包含接收和傳送作業的通用屬性 BatchMessage.cs 會實作批次訊息處理。 DotNetFileReceiverEndPoint.cs 是對應至接收位置/URI 的類別。 它會為新訊息輪詢指定資料夾 DotNetFileTransmitter.cs 是 DotNetFile 傳送配接器的單一類別。 傳遞到此配接器不同傳送埠的所有訊息都會經過這個類別 DotNetFileTransmitterEndpoint.cs 會處理傳輸訊息。 |
| \SDK\Samples\AdaptersDevelopment\BaseAdapter\v1.0.2 檔案 | Description |
|---|---|
| Adapter.cs、AdapterException.cs、AsyncTransmitter.cs、batch.cs、ConfigProperties.cs、ControlledTermination.cs、IManageEndpoints.cs、Receiver.cs、ReceiverEndpoint.cs | 提供組成 Base 配接器的類別。 您可以使用這些類別來建立自己的配接器。 |
如何使用此範例
將範例 FILE 配接器當做範本，建立其他自訂配接器。
建置此範例
重要
如果 BizTalk 安裝是 64 位元，或安裝位置已有修改，則需要隨之變更 OutboundAssemblyPath、InboundAssemblyPath、AdapterMgmtAssemblyPath。
使用下列程序建置和初始化 FILE 配接器範例。
為 DotNetFileAdapter 專案和 Base 配接器專案建立強式名稱金鑰
啟動 Visual Studio 命令提示字元。
注意
以系統管理員身分執行命令提示字元。
將目前目錄變更為 <Samples Path>\AdaptersDevelopment\BaseAdapter\v1.0.2目錄。
在命令提示字元中，輸入 sn –k BaseAdapter.snk ，然後按 ENTER 鍵。 這個 .snk 檔案可能因為先前已執行過其他範例而存在。 如果檔案已經存在，您可以直接執行步驟 4 並略過這個步驟。
將目前目錄變更為 <Samples Path> \AdaptersDevelopment\File Adapter\Runtime目錄。
在命令提示字元中，輸入 sn –k DotNetFileAdapter.snk ，然後按 ENTER 鍵。
在命令提示字元中，輸入 exit ，然後按 ENTER 以關閉命令提示字元視窗。
建置接收器執行階段專案
按一下 [開始]，指向 [所有程式]，指向 [配件]，然後按一下 [ Windows 檔案總管]。
流覽至 <範例路徑>「\AdaptersDevelopment\File Adapter\Runtime」目錄，然後按兩下DotNetFile.sln。
若要重建配接器接收器執行時間專案，請在 [方案總管] 中，以滑鼠右鍵按一下DotNetFile，然後按一下 [重建]。
從 [ 檔案] 功能表中，按一下 [ 結束 ] 以關閉 Visual Studio。
建置配接器執行階段專案
在 Windows 檔案總管中，流覽至 <範例路徑>「\AdaptersDevelopment\File Adapter\Design Time\Adapter Management」目錄，然後按兩下AdapterManagement.sln。
在 [方案總管] 中，以滑鼠右鍵按一下 [AdapterManagement]，然後按一下 [重建]。
從 [ 檔案] 功能表中，按一下 [ 結束 ] 以關閉 Visual Studio。
註冊範例靜態配接器
在 Windows 檔案總管中，流覽至 <範例路徑>「\AdaptersDevelopment\File Adapter」目錄。
若要將範例配接器新增至登錄，請按兩下 StaticAdapterManagement.reg。
注意
StaticAdapterManagement.reg 包含 C：\Program Files\Microsoft BizTalk Server\ 的硬式編碼路徑。 如果您未在 %ProgramFiles%\Microsoft BizTalk Server\ 目錄中安裝 BizTalk Server，如果您已從 BizTalk Server 2009 或 BizTalk Server 2006 R2 升級BizTalk Server安裝，或已安裝BizTalk Server在執行 64 位版本的 Windows 的電腦上，您必須使用適當的路徑修改 StaticAdapterManagement.reg 檔案。 根據預設，BizTalk Server安裝在執行 64 位版本 Windows 之電腦上的 %ProgramFiles (x86) %\Microsoft BizTalk Server\ 目錄中。 請將與 "InboundAssemblyPath"、"OutboundAssemblyPath" 和 "AdapterMgmtAssemblyPath" 值關聯的路徑更新為指向所指定檔案的正確位置。
重要
如果您在 64 位電腦上安裝 BizTalk，請將 HKEY_CLASSES_ROOT\CLSID\ 登錄專案的所有實例變更為 StaticAdapterManagement.reg 登錄檔中的 HKEY_CLASSES_ROOT\Wow6432Node\CLSID\。
在 [ 登錄編輯程式] 對話方塊中，按一下 [ 是 ] 將範例配接器新增至登錄，然後按一下 [ 確定]。
若要關閉 Windows 檔案總管，請在 [ 檔案 ] 功能表上，按一下 [ 關閉]。
安裝範例靜態配接器
依序按一下[開始]、[所有程式]、[Microsoft BizTalk Server 20xx]，然後選取[BizTalk Server系統管理]。
在 BizTalk Server 管理主控台中，按一下以展開[BizTalk Server系統管理]，按一下以展開[BizTalk 群組]，然後按一下以展開 [平臺設定]。
以滑鼠右鍵按一下 [配接器]，按一下 [ 新增]，然後按一下 [ 配接器]。
在 [ 新增配接器 ] 對話方塊中，執行下列動作。
使用 作法 名稱 輸入 Static。 配接器 從下拉式清單中選取 [靜態 DotNetFile ]。 註解 輸入 範例配接器。 按一下 [確定]。
靜態配接器現在會出現在 [BizTalk 管理主控台] 右邊視窗的配接器清單中。
停止並重新啟動主控件執行個體
按一下[開始]，選取[所有程式]，選取[Microsoft BizTalk Server 20xx]，然後選取[BizTalk Server系統管理]。
在BizTalk Server管理主控台中，按一下以展開[BizTalk Server系統管理]，按一下以展開[BizTalk 群組]，按一下以展開[平臺設定]，然後按一下 [主機實例]。 在右窗格中選取 BizTalkServerApplication。
在結果窗格中，以滑鼠右鍵按一下主機實例 (通常是電腦名稱稱) ，然後按一下 [ 重新開機]。
執行此範例
執行 FILE 配接器範例
按一下 [開始]，指向 [所有程式]，指向 [配件]，然後按一下 [ Windows 檔案總管]。
在BizTalk Server安裝磁片磁碟機上建立下列資料夾：
< drive >：\Temp
< drive >：\Temp\Send
< drive >：\Temp\Receive
若要關閉 Windows 檔案總管，請在 [ 檔案 ] 功能表上，按一下 [ 關閉]。
按一下[開始]，指向[所有程式]，指向[Microsoft BizTalk Server 20xx]，然後按一下[BizTalk Server管理]。
以滑鼠右鍵按一下[BizTalk Server管理] 節點，然後選取 [連線至現有群組]。
在 [連接到現有BizTalk Server組態資料庫] 對話方塊中，執行下列動作。
注意
「BizTalk 管理」資料庫也稱為「BizTalk 組態」資料庫。
使用 作法 SQL Server 輸入 。 (句號) 。 資料庫 選取由組態精靈建立的 BizTalk 管理資料庫名稱。 組態精靈所使用的預設資料庫名稱是 BizTalkMgmtDb。 按一下 [確定]。
在 BizTalk Server 管理主控台中展開BizTalk Group[server name]節點，展開 [應用程式] 節點，然後展開[BizTalk 應用程式 1] 節點。
以滑鼠右鍵按一下 [ 傳送埠] 節點，然後按一下 [ 新增]，選取 [ 靜態 One-Way 傳送埠]，然後按一下 [ 確定]。
在 [ 傳送埠屬性 ] 對話方塊中，選取 [ 一般]，然後執行下列動作。
使用 作法 名稱 輸入 AdapterSend。 傳輸類型 從下拉式清單中選取 [靜態 ]，然後按一下 [ 設定]。
- 在 [目錄]方塊中，輸入< drive >：\Temp\Send。
- 在 [ 檔案模式] 方塊中，選取 [ 建立][新增]。
- 在 [ 檔案名] 方塊中，輸入 %MessageID%.xml。
- 按一下 [ 確定]。
- URI欄位應該會顯示< 磁片磁碟機 >：\Temp\Send\%MessageID%.xml。傳送管線 選取 [PassThruTransmit (Microsoft.BizTalk.DefaultPipelines.PassThruTransmit) ]，然後按一下 [ 確定]。 在 [BizTalk 應用程式 1] 節點下，按一下 [ 接收埠]，然後選取 [ 新增/One-Way 接收埠]。
在 [ 建立新的接收埠 ] 對話方塊 的 [指定接收埠類型 ] 方塊中，從下拉式清單中選取 [單向接收埠 ]，然後按一下 [ 確定]。
在 [ 接收埠屬性 ] 對話方塊的 [ 名稱 ] 方塊中，輸入 AdapterReceive，然後按一下 [ 確定]。
在 [BizTalk 應用程式 1] 節點底下，以滑鼠右鍵按一下 [ 接收位置]，然後選取 [ 新增/ 單向接收位置]。
在 [ 選取接收埠] 對話方塊中，選取 [ 配接器][回復 ]，然後按一下 [ 確定]。
在 [ 接收位置屬性 ] 對話方塊中，執行下列動作。
使用 作法 名稱 類型 AdapterReceiveLocation 傳輸類型 從下拉式清單中選取 [靜態 ]，然後按一下 [ 設定 ] 以存取這些剩餘的屬性。 URI - 按一下省略號按鈕 (...) 。
- 在 [ 批次中的檔案數目] 方塊中，輸入 20。
- 在 [目錄]方塊中，輸入< drive >：\Temp\Receive。
- 確定 [檔案遮罩 ] 屬性已設定為 *.xml。
- 在 [ 輪詢間隔] 方塊中，輸入 5，然後按一下 [ 確定]。
- 確定URI標籤包含< 磁片磁碟機 >：\Temp\Receive\*.xml。接收處理常式 從下拉式清單中選取 [BizTalkServerApplication ]。 接收管線 從下拉式清單中選取 [XMLReceive ]。 按一下 [確定]。
繼續 建置、部署和系結範例配接器。
建置、部署和繫結範例配接器
在配接器可以使用之前，您必須先建置專案、將協調流程繫結至連接埠以及登錄配接器。
建立靜態配接器的強式名稱金鑰
啟動 Visual Studio 命令提示字元。
在命令提示字元中，將目前目錄變更為 <Samples Path>\AdaptersDevelopment\File Adapter\BizTalk Project\Adapter Harness目錄。
在命令提示字元中，輸入 sn –k AdapterHarness.snk，然後按ENTER。
按一下 [確定]。
建置配接器控管專案
- 在 [方案總管] 中，以滑鼠右鍵按一下[AdapterHarnessProject]，然後按一下 [重建]。
部署配接器控管專案
在 方案總管中，當專案重建時，以滑鼠右鍵按一下[AdapterHarnessProject]，然後按一下 [部署]。
在 BizTalk Server 管理主控台中，選取您已部署的專案，然後按一下 [重新整理]。
將協調流程繫結至連接埠
在 BizTalk Server 管理主控台中，于適當的BizTalk Server應用程式下，展開[協調流程]節點。
以滑鼠右鍵按一下 AdapterHarness.AdapterHarnessType，然後按一下 [ 系結]。
在 [ 埠系結屬性 - AdapterHarness.AdapterHarnessType- 系結組 態] 對話方塊中，執行下列動作。
使用 作法 AdapterFileReceivePort 從下拉式清單中選取 [配接器][回復 ]。 AdapterFileSendPort 從下拉式清單中選取 [配接器 ][傳送]。 在左窗格中，按一下 [ 主機]。
在 [ 主機] 方塊中，從下拉式清單中選取 [BizTalkServerApplication ]，然後按一下 [ 確定]。
繼續 管理範例配接器。
管理範例配接器
請在 [BizTalk 管理主控台] 中完成範例配接器的管理工作。
管理 FILE 配接器範例
按一下[開始]，指向[所有程式]，指向[Microsoft BizTalk Server 20xx]，然後按一下[BizTalk Server管理]。
在左窗格中，按一下以展開 [應用程式]，按一下以展開 [BizTalk 應用程式 1]，然後按一下 [ 接收位置]。
確定 AdapterReceive 狀態為 [已啟用]。
如果狀態不是 [已啟用]，請以滑鼠右鍵按一下右窗格中的 [ AdapterReceive ]，然後按一下 [ 啟用]。
在左窗格中，按一下 [ 協調流程 ]，並確定 AdapterHarness.AdapterHarnessType 已 登記。 在 [AdapterHarness.AdapterHarnessType] 上按一下滑鼠右鍵，然後按一下 [ 加入] (如果 AdapterHarness.AdapterHarnessType 已經登記，則 [ 加入清單 ] 功能表選項無法使用) 。
以滑鼠右鍵按一下 [AdapterHarness.AdapterHarnessType ]，然後選取 [ 啟動]。 此協調流程的狀態應該變更為 [執行中]。
繼續 測試範例配接器。
測試範例配接器
部署範例配接器之後，您必須停止並重新啟動主控件執行個體。 請務必先測試範例配接器，再運用到實際執行的環境中。
停止並重新啟動主控件執行個體
在BizTalk Server 管理主控台中，按一下以展開[BizTalk Server系統管理]，按一下以展開[BizTalk 群組]，按一下以展開[平臺設定]，然後按一下 [主機實例]。 在右窗格中選取 BizTalkServerApplication。
以滑鼠右鍵按一下主機實例 (通常是電腦名稱稱) ，然後按一下 [ 停止]。
主機實例的狀態會變更為 [已停止]。
以滑鼠右鍵按一下主機實例，然後按一下 [ 啟動]。
主機實例的狀態會變更為 [執行中]。
測試範例靜態配接器執行階段
在 Windows 檔案總管中 < ，流覽至Samples Path>\AdaptersDevelopment\File Adapter目錄，並將 InstanceXML.xml 檔案複製到剪貼簿。
流覽至< drive >：\Temp\Receive，並將 Instance.xml 檔案貼到資料夾中。
如果傳輸和接收配接器正常運作，檔案應該會從< 磁片磁碟機：\Temp\Receive 資料夾移至磁片磁碟機 >> ：\Temp\Send <資料夾。
測試範例靜態配接器的範例新增配接器精靈功能
在 Visual Studio 的 [方案總管] 中，以滑鼠右鍵按一下[AdapterHarnessProject]，指向 [新增]，然後按一下 [新增產生的專案]。
在 [ 新增產生的專案 - AdapterHarnessProject ] 對話方塊中，按一下 [ 新增配接器中繼資料]，然後按一下 [ 開啟]。
已註冊的配接器清單便會出現。
選取 [靜態 DotNetFile]，然後按 [ 下一步]。
配接器所公開的服務組織便會出現。
展開 [服務組織]、[ 醫療保健]，然後按一下 [ 系統管理]。
請注意， 資格 與其他節點的顯示方式不同。 資格 是您可以選取的服務節點。 其他節點是組織節點，沒有說明任何特定的服務。
選取 [ 資格] 節點，然後按一下 [ 完成]。
BizTalk 會將 .odx 檔案和 .xsd 檔案匯入專案。
現在，您可以在 BizTalk 專案中，使用排程中的配接器所匯入的結構描述、PortTypes、Operations 和 MessageTypes。
在此範例中使用的類別或方法
介面：IBaseMessage、IPropertyBag、IBTTransportProxy
基底配接器) (類別：AsyncTransmitterEndpoint、AsyncTransmitter、BatchMessage、ControlledTermination、ReceiverEndpoint、DotNetFileCommonProperties、BatchOperationType
註解
完成範例配接器之後，您可以修改範例配接器來建立自訂靜態或動態配接器。如需詳細資訊，請參閱 配接器 Design-Time 設定。