Creazione di una trasformazione sincrona con il componente script

Articolo
05/23/2023

Si applica a:SQL Server Integration Runtime SSIS in Azure Data Factory

Usare un componente di trasformazione nel flusso di dati di un pacchetto di Integration Services per modificare e analizzare i dati quando vengono passati dall'origine alla destinazione. Una trasformazione con output sincroni elabora ogni riga di input non appena viene passata attraverso il componente. Una trasformazione con output asincroni attende di aver ricevuto tutte le righe di input per completare la relativa elaborazione. In questo argomento viene descritta una trasformazione sincrona. Per informazioni sulle trasformazioni asincrone, vedere Creazione di una trasformazione asincrona con il componente script. Per altre informazioni sulla differenza tra componenti sincroni e asincroni, vedere Informazioni sulle trasformazioni sincrone e asincrone.

Per una panoramica sulla programmazione del componente Script, vedere Estensione del flusso di dati con il componente script.

Il componente script e il codice dell'infrastruttura che genera semplificano in modo significativo il processo di sviluppo di un componente del flusso di dati personalizzato. Tuttavia, per comprendere il funzionamento del componente script, può risultare utile leggere informazioni sui passaggi necessari per lo sviluppo di un componente del flusso di dati personalizzato nella sezione Sviluppo di un componente del flusso di dati personalizzato e in particolare in Sviluppo di un componente di destinazione personalizzato con output sincroni.

Introduzione ai componenti di trasformazione sincroni

Quando si aggiunge un componente script nel riquadro Flusso di dati di Progettazione SSIS viene visualizzata la finestra di dialogo Seleziona tipo componente script che richiede di selezionare un tipo di componente Origine, Destinazione o Trasformazione. In questa finestra di dialogo selezionare Trasformazione.

Configurazione di un componente di trasformazione sincrono in modalità di progettazione metadati

Dopo aver selezionato l'opzione per creare un componente di trasformazione, configurare il componente mediante Editor trasformazione Script. Per altre informazioni, vedere Configurazione del componente script nell'editor corrispondente.

Per impostare il linguaggio di scripting del componente script, impostare la proprietà ScriptLanguage nella pagina Script di Editor trasformazione Script.

Nota

Per impostare il linguaggio di scripting predefinito per il componente script, usare l'opzione Linguaggio di scripting nella pagina Generale della finestra di dialogo Opzioni. Per altre informazioni, vedere Pagina Generale.

Un componente di trasformazione del flusso di dati include un input e supporta uno o più output. La configurazione dell'input e degli output per il componente è uno dei passaggi che è necessario completare in modalità di progettazione metadati tramite Editor trasformazione Script prima di creare lo script personalizzato.

Configurazione delle colonne di input

Un componente di trasformazione include un unico input.

Nella pagina Colonne di input di Editor trasformazione Script l'elenco di colonne contiene le colonne disponibili dell'output del componente a monte nel flusso di dati. Selezionare le colonne che si desidera trasformare o passare. Contrassegnare le colonne che si desidera trasformare sul posto come di lettura/scrittura.

Per altre informazioni sulla pagina Colonne di input di Editor trasformazione Script, vedere Editor trasformazione Script (pagina Colonne di input).

Configurazione di input, output e colonne di output

Un componente di trasformazione supporta uno o più output.

Nella pagina Input e output di Editor trasformazione Script è possibile verificare che è stato creato un singolo output, che tuttavia non include colonne. In questa pagina dell'editor può essere necessario o consigliabile configurare gli elementi seguenti.

Creare uno o più output aggiuntivi, ad esempio un output degli errori simulati per le righe che contengono valori imprevisti. Usare i pulsanti Aggiungi output e Rimuovi output per gestire gli output del componente di trasformazione sincrono. Tutte le righe di input vengono indirizzate a tutti gli output disponibili, a meno che non si indichi che si intende reindirizzare ogni riga a uno o all'altro output. Indicare che si intende reindirizzare le righe specificando un valore Integer diverso da zero per la proprietà ExclusionGroup degli output. Il valore Integer specifico immesso in ExclusionGroup per identificare gli output non è significativo, ma è necessario usare sempre lo stesso valore per il gruppo di output specificato.

Nota

È anche possibile usare un valore diverso da zero per la proprietà ExclusionGroup con un singolo output se non si vuole restituire tutte le righe come output. In questo caso, tuttavia, è necessario chiamare in modo esplicito il metodo DirectRowTo<outputbuffer> per ogni riga che si vuole inviare all'output.
Assegnare un nome più descrittivo all'input e agli output. Il componente script utilizza questi nomi per generare le proprietà delle funzioni di accesso tipizzate che verranno utilizzate per fare riferimento all'input e agli output nello script.
Lasciare le colonne nello stato in cui si trovano per le trasformazioni sincrone. In genere una trasformazione sincrona non aggiunge colonne al flusso di dati. I dati vengono modificati sul posto nel buffer, che viene quindi passato al componente successivo nel flusso di dati. In questo caso, non è necessario aggiungere e configurare in modo esplicito colonne di output negli output della trasformazione. Gli output vengono visualizzati nell'editor senza colonne definite in modo esplicito.
Aggiungere le nuove colonne agli output degli errori simulati per gli errori a livello di riga. Normalmente, più output nello stesso oggetto ExclusionGroup dispongono dello stesso set di colonne di output. Tuttavia, se si crea un output degli errori simulati, è possibile aggiungere più colonne per contenere le informazioni sugli errori. Per informazioni su come il motore flusso di dati elabora le righe di errore, vedere Uso degli output degli errori in un componente del flusso di dati. Si noti che nel componente script è necessario scrivere codice personalizzato per inserire le informazioni appropriate sugli errori nelle colonne aggiuntive. Per altre informazioni, vedere Simulazione di un output degli errori per il componente script.

Per altre informazioni sulla pagina Input e output di Editor trasformazione Script, vedere Editor trasformazione Script (pagina Input e output).

Aggiunta di variabili

Se si vuole usare variabili esistenti nello script, è possibile aggiungerle nei campi delle proprietà ReadOnlyVariables e ReadWriteVariables della pagina Script di Editor trasformazione Script.

Quando si aggiungono più variabili nei campi delle proprietà, separare i relativi nomi con virgole. È anche possibile selezionare più variabili facendo clic sul pulsante con i puntini di sospensione ( ... ) accanto ai campi delle proprietà ReadOnlyVariables e ReadWriteVariables e selezionando le variabili nella finestra di dialogo Seleziona variabili.

Per informazioni generali sull'uso delle variabili con il componente script, vedere Uso di variabili nel componente script.

Per altre informazioni sulla pagina Script di Editor trasformazione Script, vedere Editor trasformazione Script (pagina Script).

Scripting di un componente di trasformazione sincrono in modalità di progettazione codice

Dopo aver configurato i metadati per il componente, è possibile scrivere lo script personalizzato. Nella pagina Script di Editor trasformazione Script fare clic su Modifica script per aprire l'IDE di Microsoft Visual Studio Tools for Applications (VSTA), in cui è possibile aggiungere lo script personalizzato. Il linguaggio di scripting che si usa varia a seconda che sia stato selezionato Microsoft Visual Basic o Microsoft Visual C# come linguaggio di scripting per la proprietà ScriptLanguage nella pagina Script.

Per importanti informazioni applicabili a tutti i tipi di componenti creati tramite il componente script, vedere Codifica e debug del componente script.

Informazioni sul codice generato automaticamente

Quando si apre l'IDE di VSTA dopo la creazione e la configurazione di un componente di trasformazione, la classe modificabile ScriptMain viene visualizzata nell'editor del codice con uno stub per il metodo ProcessInputRow. La classe ScriptMain è quella in cui si scriverà il codice personalizzato, mentre ProcessInputRow è il metodo più importante in un componente di trasformazione.

Se si apre la finestra Esplora progetti in VSTA, è possibile rilevare che il componente script ha generato anche gli elementi del progetto BufferWrapper e ComponentWrapper di sola lettura. La classe ScriptMain eredita dalla classe UserComponent nell'elemento di progetto ComponentWrapper.

In fase di esecuzione il motore flusso di dati chiama il metodo ProcessInput nella classe UserComponent, che esegue l'override del metodo ProcessInput della classe padre ScriptComponent. A sua volta il metodo ProcessInput esegue il ciclo delle righe nel buffer di input e chiama il metodo ProcessInputRow una volta per ogni riga.

Scrittura di codice personalizzato

Un componente di trasformazione con output sincroni è il più semplice da scrivere tra tutti i componenti del flusso di dati. L'esempio a singolo output illustrato più avanti in questo argomento è costituito, ad esempio, dal codice personalizzato seguente:

Row.City = UCase(Row.City)

Row.City = (Row.City).ToUpper();

Per completare la creazione di un componente di trasformazione sincrono, è possibile usare il metodo sottoposto a override ProcessInputRow per trasformare i dati in ogni riga del buffer di input. Il motore flusso di dati passa questo buffer, quando è pieno, al componente successivo nel flusso di dati.

A seconda dei requisiti, è anche possibile creare script nei metodi PreExecute e PostExecute, disponibili nella classe ScriptMain, per eseguire l'elaborazione preliminare o finale.

Utilizzo di più output

L'indirizzamento delle righe di input a uno dei due o più output possibili non richiede una quantità maggiore di codice personalizzato rispetto allo scenario a singolo output descritto in precedenza. L'esempio a due output illustrato più avanti in questo argomento è costituito, ad esempio, dal codice personalizzato seguente:

Row.City = UCase(Row.City)  
If Row.City = "REDMOND" Then  
    Row.DirectRowToMyRedmondAddresses()  
Else  
    Row.DirectRowToMyOtherAddresses()  
End If

Row.City = (Row.City).ToUpper();  
  
if (Row.City=="REDMOND")  
{  
    Row.DirectRowToMyRedmondAddresses();  
}  
else  
{  
    Row.DirectRowToMyOtherAddresses();  
}

In questo esempio il componente script genera automaticamente i metodi DirectRowTo<OutputBufferX>, in base ai nomi degli output configurati. È possibile utilizzare codice simile per indirizzare le righe di errore a un output degli errori simulati.

Esempi

Negli esempi seguenti è illustrato il codice personalizzato necessario nella classe ScriptMain per creare un componente di trasformazione sincrono.

Nota

Gli esempi usano la tabella Person.Address del database di esempio AdventureWorks e passano la prima e la quarta colonna, ovvero le colonne intAddressID e nvarchar(30)City, attraverso il flusso di dati. Gli stessi dati vengono utilizzati negli esempi relativi a origine, trasformazione e destinazione in questa sezione. Per ogni esempio, sono documentati ulteriori prerequisiti e presupposti.

Esempio di trasformazione sincrona a singolo output

In questo esempio viene illustrato un componente di trasformazione sincrono con un singolo output. La trasformazione passa la colonna AddressID e converte la colonna City in lettere maiuscole.

Se si desidera eseguire questo codice di esempio, è necessario configurare il pacchetto e il componente come segue:

Aggiungere un nuovo componente script all'area di progettazione del flusso di dati e configurarlo come trasformazione.
Connettere l'output di un'origine o di un'altra trasformazione al nuovo componente di trasformazione in Progettazione SSIS. Questo output deve specificare i dati della tabella Person.Address del database di esempio AdventureWorks che contiene le colonne AddressID e City.
Aprire l'Editor trasformazione Script. Nella pagina Colonne di input selezionare le colonne AddressID e City. Contrassegnare la colonna City come Lettura/Scrittura.
Nella pagina Input e output rinominare l'input e l'output con nomi più descrittivi, ad esempio MyAddressInput e MyAddressOutput. Si noti che l'elemento SynchronousInputID dell'output corrisponde all'elemento ID dell'input. Pertanto, non è necessario aggiungere e configurare colonne di output.
Nella pagina Script fare clic su Modifica script e immettere lo script seguente. Chiudere quindi l'ambiente di sviluppo dello script e Editor trasformazione Script.
Creare e configurare un componente di destinazione in cui sono previste le colonne AddressID e City, ad esempio una destinazione SQL Server, oppure il componente di destinazione di esempio illustrato in Creazione di una destinazione con il componente script. Connettere quindi l'output della trasformazione al componente di destinazione. È possibile creare una tabella di destinazione eseguendo il comando Transact-SQL seguente nel database AdventureWorks:
```
CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL,  
    [City] [nvarchar](30) NOT NULL)  
```
Eseguire l'esempio.

Public Class ScriptMain  
    Inherits UserComponent  
  
    Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer)  
  
        Row.City = UCase(Row.City)  
  
    End Sub  
  
End Class

public class ScriptMain:  
    UserComponent  
  
{  
    public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row)  
    {  
  
        Row.City = (Row.City).ToUpper();  
  
    }  
  
}

Esempio di trasformazione sincrona a due output

In questo esempio viene illustrato un componente di trasformazione sincrona con due output. La trasformazione passa la colonna AddressID e converte la colonna City in lettere maiuscole. Se il nome della città è Redmond, indirizza la riga a un unico output e tutte le altre righe a un altro output.