File Adapter (esempio di BizTalk Server)
L'esempio di adattatore file è scritto in Microsoft Visual C# .NET per lavorare con Microsoft BizTalk Server. Il codice fornito consente di compilare un adapter statico o dinamico. Nella procedura riportata di seguito, tuttavia, viene descritto solo l'adapter statico. Un adapter statico è costituito da un set di schemi statico e non include interfacce utente personalizzate. Un adapter dinamico include invece un'interfaccia utente personalizzata e un set di schemi potenzialmente dinamico. Sia gli adapter statici sia quelli dinamici utilizzano l'Aggiunta guidata adapter per aggiungere i relativi schemi a un progetto BizTalk.
Nota
L'esempio di adattatore file non corrisponde all'adattatore FILE nativo fornito con BizTalk Server. Quando si seleziona il tipo di trasporto durante l'utilizzo dell'esempio, è quindi necessario selezionare "static" anziché FILE.
L'adapter dinamico con un'interfaccia utente personalizzata e un set di schemi potenzialmente dinamico richiede codice aggiuntivo sul lato relativo alla gestione dell'adapter. Per comprendere meglio l'uso del set dinamico di schemi, vedere Configurazione dinamica dell'adattatore Design-Time.
Scopo dell'esempio
L'adattatore di esempio copia i file da una cartella di file, invia a BizTalk come messaggi o accetta messaggi da BizTalk Server e rilascia in una cartella di file. Il codice fornito consente di compilare un adapter statico o dinamico. Nella procedura riportata di seguito, tuttavia, viene descritto solo l'adapter statico. Un adapter statico è costituito da un set di schemi statico e non include interfacce utente personalizzate. Un adapter dinamico include invece un'interfaccia utente personalizzata e un set di schemi potenzialmente dinamico. Sia gli adapter statici sia quelli dinamici utilizzano l'Aggiunta guidata adapter per aggiungere i relativi schemi a un progetto BizTalk.
È possibile utilizzare l'adapter per file di esempio come modello per la creazione di altri adapter personalizzati.
Percorso dell'esempio
< Percorso esempi>\AdaptersDevelopment\File Adapter
Nota
Il percorso predefinito per <Il percorso> degli esempi è %ProgramFiles%\Microsoft BizTalk Server\SDK\Samples quando BizTalk Server è installato in un computer che esegue una versione a 32 bit di Windows. Il percorso predefinito per <Il percorso> esempi è %ProgramFiles(x86)%\Microsoft BizTalk Server\SDK\Samples quando BizTalk Server è installato in un computer che esegue una versione a 64 bit di Windows. Per determinare i valori associati a %ProgramFiles% o %ProgramFiles(x86)% delle variabili di ambiente digitare echo %ProgramFiles% o echo %ProgramFiles(x86)% al prompt dei comandi e premere INVIO. Se si esegue questo esempio in un sistema operativo a 64 bit, è necessario modificare tutti i riferimenti in uno dei file reg da %ProgramFiles% a %ProgramFiles(x86)% prima di eseguire i file reg.
Nella seguente tabella sono riportati i file inclusi nell'esempio e ne viene descritto lo scopo.
| File in \File Adapter | Descrizione |
|---|---|
| \BizTalk Project | Contiene il progetto Adapter Harness utilizzato per il test dell'adapter di esempio. |
| \Design Time | Contiene il progetto della fase di progettazione e gestione (AdapterManagement.csproj). |
| File in \Runtime | Contiene i progetti di trasmissione e ricezione per la copia dei file di runtime (DotNetFile.csproj). |
| DynamicAdapterManagement.reg | Registra l'adapter dinamico di esempio. |
| Instance.xml | File di esempio per il pass-through dell'adapter per file. |
| StaticAdapterManagement.reg | Registra l'adapter statico di esempio. |
| File in \BizTalk Project\Adapter Harness | Descrizione |
|---|---|
| AdapterHarness.odx, AdapterHarness.sln, AdapterHarnessProject.btproj | Forniscono progetto, soluzione e file correlati per il progetto BizTalk. |
| mySchema.xsd | Fornisce lo schema di Instance.xml che l'orchestrazione harness prevede di ricevere dal componente di ricezione dell'adapter, nonché lo schema di Instance.xml che l'orchestrazione consegna al componente di trasmissione dell'adapter. |
| File in \Design Time\Adapter Management | Descrizione |
|---|---|
| AdapterManagement.cs, AdapterManagement.csproj, AdapterManagement.sln | Includono progetto, soluzione e file correlati per la fase di progettazione dell'adapter. |
| AssemblyInfo.cs | Contiene informazioni sull'assembly per l'esempio. |
| CategorySchema2.xml | Non utilizzato dall'adapter di esempio. |
| CategorySchema.xml | Contiene l'albero dell'organizzazione di servizi per l'adapter statico. |
| DotNetFileResource.resx | Contiene risorse. |
| ReceiveHandler.xsd, ReceiveLocation.xsd | Contengono il gestore del lato ricezione e gli schemi delle proprietà personalizzate dell'endpoint. |
| service1.wsdl | Contiene definizioni di operazioni per l'adapter. |
| TransmitHandler.xsd, TransmitLocation.xsd | Contengono il gestore del lato trasmissione e gli schemi delle proprietà personalizzate dell'endpoint. |
| File in \Runtime | Descrizione |
|---|---|
| DotNetFile.csproj, DotNetFile.sln, AssemblyInfo.cs, DotNetFileExceptions.cs, DotNetFileProperties.cs, DotNetFileReceiver.cs, DotNetFileReceiverEndPoint.cs, DotNetFileTransmitter.cs, DotNetFileTransmitterEndpoint.cs, DotNetFileAsyncTransmitterBatch.cs, BatchMessage.cs |
File relativi agli adapter di trasmissione e ricezione per la copia di runtime. È possibile modificare e salvare questi file con un nuovo nome per i componenti personalizzati. DotNetFile.csproj e DotNetFile.sln sono i file di progetto e soluzione. AssemblyInfo.cs contiene informazioni sull'assembly per l'esempio. DotNetFileReceiver.cs legge i file dai percorsi di ricezione e li invia a BizTalk Server. DotNetFileExceptions.cs implementa codice per la gestione delle eccezioni durante l'elaborazione dei messaggi. DotNetFileProperties.cs contiene proprietà comuni per le operazioni di ricezione e trasmissione. BatchMessage.cs implementa l'invio di messaggi in batch. DotNetFileReceiverEndPoint.cs è una classe corrispondente a un indirizzo di ricezione/URI e gestisce il polling della cartella specificata per verificare se sono presenti nuovi messaggi. DotNetFileTransmitter.cs è una classe singleton per l'adapter di trasmissione DotNetFile, che consente il passaggio di tutti i messaggi inviati alle diverse porte di trasmissione di questo tipo di adapter. DotNetFileTransmitterEndpoint.cs gestisce la trasmissione di messaggi. |
| File in \SDK\Samples\AdaptersDevelopment\BaseAdapter\v1.0.2 | Descrizione |
|---|---|
| Adapter.cs, AdapterException.cs, AsyncTransmitter.cs, batch.cs, ConfigProperties.cs, ControlledTermination.cs, IManageEndpoints.cs, Receiver.cs, ReceiverEndpoint.cs | Forniscono classi che costituiscono l'adapter base e che consentono di creare adapter personalizzati. |
Modalità di utilizzo dell'esempio
Utilizzare l'adapter per file di esempio come modello per la creazione di altri adapter personalizzati.
Compilazione dell'esempio
Importante
Se l'installazione di BizTalk è a 64 bit o il percorso di installazione viene modificato, OutboundAssemblyPath, InboundAssemblyPath, AdapterMgmtAssemblyPath devono essere modificati di conseguenza.
Utilizzare le procedure riportate di seguito per compilare e inizializzare l'esempio di adapter per file.
Per creare una chiave con nome sicuro per i progetti DotNetFileAdapter e per il progetto dell'adapter base
Avviare il prompt dei comandi di Visual Studio.
Nota
Eseguire il prompt dei compandi come Amministratore.
Modificare la directory corrente nella < directory Path>\AdaptersDevelopment\BaseAdapter\v1.0.2.
Al prompt dei comandi digitare sn –k BaseAdapter.snk e quindi premere INVIO. È possibile che il file snk sia già stato installato durante l'esecuzione di altri esempi. In questo caso, è possibile ignorare questo passaggio e andare direttamente al passaggio 4.
Modificare la directory corrente nella < directory Path>\AdaptersDevelopment\File Adapter\Runtime.
Al prompt dei comandi digitare sn –k DotNetFileAdapter.snk e quindi premere INVIO.
Al prompt dei comandi digitare exit e quindi premere INVIO per chiudere la finestra del prompt dei comandi.
Per compilare il progetto in fase di esecuzione del ricevitore
Fare clic sul pulsante Start, scegliere Tutti i programmi, Accessori, quindi fare clic su Esplora risorse.
Passare alla < directory Samples Path>"\AdaptersDevelopment\File Adapter\Runtime" e quindi fare doppio clic su DotNetFile.sln.
Per ricompilare il progetto di runtime del ricevitore adapter, in Esplora soluzioni fare clic con il pulsante destro del mouse su DotNetFile e quindi scegliere Ricompilazione.
Dal menu File fare clic su Esci per chiudere Visual Studio.
Per compilare il progetto in fase di progettazione dell'adapter
In Esplora risorse passare alla < directory Samples Path>"\AdaptersDevelopment\File Adapter\Design Time\Adapter Management" e quindi fare doppio clic su AdapterManagement.sln.
In Esplora soluzioni fare clic con il pulsante destro del mouse su AdapterManagement e quindi scegliere Ricompilazione.
Dal menu File fare clic su Esci per chiudere Visual Studio.
Per registrare l'adapter statico di esempio
In Esplora risorse passare alla < directory Percorso> esempi"\AdaptersDevelopment\File Adapter".
Per aggiungere l'adattatore di esempio al Registro di sistema, fare doppio clic su StaticAdapterManagement.reg.
Nota
StaticAdapterManagement.reg include percorsi hard coded a C:\Programmi\Microsoft BizTalk Server\. Se non è stato installato BizTalk Server nella directory %ProgramFiles%\Microsoft BizTalk Server\ se è stata aggiornata l'installazione BizTalk Server da BizTalk Server 2009 o BizTalk Server 2006 R2 o se è stata installata BizTalk Server in un computer che esegue una versione a 64 bit di Windows, è necessario modificare il file StaticAdapterManagement.reg con i percorsi appropriati. Per impostazione predefinita, BizTalk Server viene installata nella directory %ProgramFiles(x86)%\Microsoft BizTalk Server\ nei computer che eseguono una versione a 64 bit di Windows. Aggiornare i percorsi associati ai valori "InboundAssemblyPath", "OutboundAssemblyPath" e "AdapterMgmtAssemblyPath" in base al percorso corretto dei file specificati.
Importante
Se si installa BizTalk in un computer a 64 bit, modificare tutte le istanze della voce del Registro di sistema di HKEY_CLASSES_ROOT\CLSID\ in HKEY_CLASSES_ROOT\Wow6432Node\CLSID\ nel file di registro StaticAdapterManagement.reg .
Nella finestra di dialogo Editor registro fare clic su Sì per aggiungere l'adattatore di esempio al Registro di sistema e quindi fare clic su OK.
Per chiudere Esplora risorse, scegliere Chiudi dal menu File.
Per installare l'adapter statico di esempio
Fare clic su Start, selezionare Tutti i programmi, selezionare Microsoft BizTalk Server 20xx e quindi selezionare BizTalk Server Amministrazione.
Nella console di amministrazione BizTalk Server fare clic per espandere BizTalk Server Amministrazione, fare clic per espandere Gruppo BizTalk e fare clic per espandere Impostazioni piattaforma.
Fare clic con il pulsante destro del mouse su Adattatori, scegliere Nuovo e quindi fare clic su Adattatore.
Nella finestra di dialogo Aggiungi adattatore eseguire le operazioni seguenti.
Usare Per Nome Tipo Statico. Adattatore Selezionare Static DotNetFile nell'elenco a discesa. Commento Adattatore di esempio di tipo. Fare clic su OK.
L'adapter statico verrà visualizzato nell'elenco degli adapter nella finestra di destra della Console di amministrazione BizTalk.
Per arrestare e riavviare l'istanza dell'host
Fare clic su Start, selezionare Tutti i programmi, selezionare Microsoft BizTalk Server 20xx e selezionare BizTalk Server Amministrazione.
Nella console di amministrazione BizTalk Server fare clic per espandere amministrazione BizTalk Server, fare clic per espandere Gruppo BizTalk, fare clic per espandere Impostazioni piattaforma e fare clic su Istanze host. Selezionare BizTalkServerApplication nel riquadro destro.
Nel riquadro dei risultati fare clic con il pulsante destro del mouse sull'istanza host (in genere, il nome del computer) e quindi fare clic su Riavvia.
Esecuzione dell'esempio
Per eseguire l'esempio di adapter per file
Fare clic sul pulsante Start, scegliere Tutti i programmi, Accessori, quindi fare clic su Esplora risorse.
Creare le cartelle seguenti nell'unità di installazione di BizTalk Server:
<drive>:\Temp
<drive>:\Temp\Send
<drive>:\Temp\Receive
Per chiudere Esplora risorse, scegliere Chiudi dal menu File.
Fare clic su Start, scegliere Tutti i programmi, scegliere Microsoft BizTalk Server 20xx e quindi fare clic su BizTalk Server Amministrazione.
Fare clic con il pulsante destro del mouse sul nodo BizTalk Server Amministrazione e scegliere Connetti al gruppo esistente.
Nella finestra di dialogo Connetti a Database di configurazione esistente BizTalk Server eseguire le operazioni seguenti.
Nota
Il database di gestione BizTalk viene anche chiamato database di configurazione BizTalk.
Usare Per SQL Server Digitare . (un punto). Database Selezionare il nome del database di gestione BizTalk creato tramite la Configurazione guidata. Il nome predefinito del database usato dalla Configurazione guidata è BizTalkMgmtDb. Fare clic su OK.
Espandere il nodo Gruppo BizTalk[nome server] nella console di amministrazione BizTalk Server espandere il nodo Applicazioni, espandere il nodo Applicazione BizTalk 1.
Fare clic con il pulsante destro del mouse sul nodo Invia porte e quindi scegliere Nuovo, selezionare Statico One-Way Porta di invio e quindi fare clic su OK.
Nella finestra di dialogo Proprietà porta di invio selezionare Generale ed eseguire le operazioni seguenti.
Usare Per Nome Digitare AdapterSend. Tipo di trasporto Selezionare Statico nell'elenco a discesa e fare clic su Configura.
- Nella casella Directory digitare <unità>:\Temp\Send.
- Nella casella Modalità file selezionare CreaNuovo.
- Nella casella Nome file digitare %MessageID%.xml.
- Fare clic su OK.
- Il campo URI deve visualizzare <l'unità>:\Temp\Send\%MessageID%.xml.Pipeline di invio Selezionare PassThruTransmit (Microsoft.BizTalk.DefaultPipelines.PassThruTransmit) e quindi fare clic su OK. Nel nodo Applicazione BizTalk 1 fare clic su Porte di ricezione e selezionare Nuovo/One-Way Porta di ricezione.
Nella finestra di dialogo Crea nuova porta di ricezione, nella casella Specificare il tipo di porta di ricezione selezionare Porta di ricezione unidirezionale dall'elenco a discesa e quindi fare clic su OK.
Nella finestra di dialogo Proprietà porta di ricezione digitare AdapterReceive nella casella Nome e quindi fare clic su OK.
Nel nodo Applicazione BizTalk 1 fare clic con il pulsante destro del mouse su Posizioni di ricezione e selezionare Nuovo/Percorso di ricezione unidirezionale.
Nella finestra di dialogo Seleziona porta di ricezione selezionareAdapterReceive e quindi fare clic su OK.
Nella finestra di dialogo Proprietà percorso di ricezione eseguire le operazioni seguenti.
Usare Per Nome Type AdapterReceiveLocation Tipo di trasporto Selezionare Statico nell'elenco a discesa e premere Configura per accedere a queste proprietà rimanenti. URI - Fare clic sul pulsante con i puntini di sospensione (...).
- Nella casella Numero di file in Batch digitare 20.
- Nella casella Directory digitare <unità>:\Temp\Receive.
- Assicurarsi che la proprietà File Mask sia impostata su *.xml.
- Nella casella Intervallo di polling digitare 5 e fare clic su OK.
- Verificare che l'etichetta URI contenga <l'unità>:\Temp\Receive\*.xml.Gestore di ricezione Selezionare BizTalkServerApplication nell'elenco a discesa. Pipeline di ricezione Selezionare XMLReceive nell'elenco a discesa. Fare clic su OK.
Passare alla compilazione, alla distribuzione e all'associazione dell'adapter di esempio.
Compilazione, distribuzione e binding dell'adapter di esempio
Prima dell'attivazione dell'adapter è necessario compilare il progetto, associare l'orchestrazione alle porte e integrare l'adapter.
Per creare una chiave con nome sicuro per l'adapter statico
Avviare il prompt dei comandi di Visual Studio.
Al prompt dei comandi modificare la directory corrente nella < directory Samples Path>\AdaptersDevelopment\File Adapter\BizTalk Project\Adapter Harness.
Al prompt dei comandi digitare sn –k AdapterHarness.snk e quindi premere INVIO.
Fare clic su OK.
Per compilare il progetto Adapter Harness
- In Esplora soluzioni fare clic con il pulsante destro del mouse su AdapterHarnessProject e quindi scegliere Ricompilazione.
Per distribuire il progetto Adapter Harness
In Esplora soluzioni, quando il progetto è stato ricompilato, fare clic con il pulsante destro del mouse su AdapterHarnessProject e quindi scegliere Distribuisci.
Nella console di amministrazione BizTalk Server selezionare il progetto distribuito e quindi fare clic su Aggiorna.
Per associare l'orchestrazione alle porte
Nella console di amministrazione di BizTalk Server, nell'applicazione di BizTalk Server appropriata espandere il nodo Orchestrazioni.
Fare clic con il pulsante destro del mouse su AdapterHarness.AdapterHarnessType e quindi scegliere Associa.
Nella finestra di dialogo Proprietà associazione porta - AdapterHarness.AdapterHarnessType- Configurazioni di associazione eseguire le operazioni seguenti.
Usare Per AdapterFileReceivePort Selezionare AdapterReceive nell'elenco a discesa. AdapterFileSendPort Selezionare AdapterSend nell'elenco a discesa. Nel riquadro sinistro fare clic su Host.
Nella casella Host selezionare BizTalkServerApplication nell'elenco a discesa e quindi fare clic su OK.
Procedere con l'amministrazione dell'adapter di esempio.
Amministrazione dell'adapter di esempio
Nella Console di amministrazione BizTalk è possibile completare le attività di amministrazione per l'adapter di esempio.
Per amministrare l'esempio di adapter per file
Fare clic su Start, scegliere Tutti i programmi, scegliere Microsoft BizTalk Server 20xx e quindi fare clic su BizTalk Server Amministrazione.
Nel riquadro sinistro fare clic per espandere Applicazioni, fare clic per espandere Applicazione BizTalk 1 e fare clic su Posizioni di ricezione.
Verificare che lo stato AdapterReceive sia abilitato.
Se lo stato non è abilitato, fare clic con il pulsante destro del mouse su AdapterReceive nel riquadro destro e quindi scegliere Abilita.
Nel riquadro sinistro fare clic su Orchestrazioni e assicurarsi che AdapterHarness.AdapterHarnessType sia in elenco. Fare clic con il pulsante destro del mouse su AdapterHarness.AdapterHarnessType e quindi scegliere Enlist (se AdapterHarness.AdapterHarnessType è già elencato, l'opzione di menu Enlist non è disponibile).
Fare clic con il pulsante destro del mouse su AdapterHarness.AdapterHarnessType e scegliere Avvia. Lo stato di questa orchestrazione deve essere modificato in Esecuzione.
Procedere al test dell'adattatore di esempio.
Test dell'adapter di esempio
Dopo aver distribuito l'adapter di esempio, è necessario arrestare e riavviare l'istanza host. È fondamentale testare l'adapter di esempio prima di inserirlo nell'ambiente di produzione.
Per arrestare e riavviare l'istanza dell'host
Nella console di amministrazione BizTalk Server fare clic per espandere BizTalk Server Amministrazione, fare clic per espandere Gruppo BizTalk, fare clic per espandere Impostazioni piattaforma e fare clic su Istanze host. Selezionare BizTalkServerApplication nel riquadro destro.
Fare clic con il pulsante destro del mouse sull'istanza host (in genere, il nome del computer) e quindi fare clic su Arresta.
Lo stato dell'istanza host viene modificato in Arresta.
Fare clic con il pulsante destro del mouse sull'istanza host e quindi scegliere Start.
Lo stato dell'istanza host viene modificato in Esecuzione.
Per testare il runtime dell'adapter statico di esempio
In Esplora risorse passare alla < directory Path\AdaptersDevelopment\File Adapters Samples e copiare il file InstanceXML.xml negli Appunti.>
Passare all'unità<>:\Temp\Receive e incollare il file Instance.xml nella cartella.
Se le schede di trasmissione e ricezione funzionano, il file deve passare dalla <cartella drive:\Temp\Receive alla cartella drive>>:\Temp\<Send.
Per testare il funzionamento dell'Aggiunta guidata adapter per l'adapter statico di esempio
In Visual Studio, in Esplora soluzioni fare clic con il pulsante destro del mouse su AdapterHarnessProject, scegliere Aggiungi e quindi fare clic su Aggiungi elementi generati.
Nella finestra di dialogo Aggiungi elementi generati - AdapterHarnessProject fare clic su Aggiungi metadati dell'adattatore e quindi fare clic su Apri.
Verrà visualizzato l'elenco degli adapter registrati.
Selezionare Static DotNetFile e quindi fare clic su Avanti.
Verrà visualizzata l'organizzazione di servizi esposta dall'adapter.
Espandere Organizzazione del servizio, Assistenza sanitaria e quindi fare clic su Amministrazione.
Si noti che l'idoneità viene visualizzata in modo diverso dagli altri nodi. L'idoneità è un nodo del servizio che è possibile selezionare. mentre gli altri sono nodi dell'organizzazione che non indicano alcun servizio specifico.
Selezionare il nodo Idoneità e quindi fare clic su Fine.
Nel progetto verranno importati un file odx e un file xsd.
A questo punto è possibile utilizzare gli schemi, i tipi di porta, le operazioni e i tipi di messaggio importati dall'adapter nella pianificazione per il progetto BizTalk.
Classi o metodi utilizzati nell'esempio
Interfacce: IBaseMessage, IPropertyBag, IBTTransportProxy
Classi (dall'adapter base): AsyncTransmitterEndpoint, AsyncTransmitter, BatchMessage, ControlledTermination, ReceiverEndpoint, DotNetFileCommonProperties, BatchOperationType
Commenti
Dopo aver completato l'adapter di esempio, è possibile modificare l'adattatore di esempio per creare una scheda statica o dinamica personalizzata Per altre informazioni, vedere Adapter Design-Time Configuration.