Informazioni sul modello a oggetti del componente script

  • Articolo

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

Come illustrato in Codifica e debug del componente script, il progetto del componente script contiene tre elementi:

  1. L'elemento ScriptMain che contiene la classe ScriptMain in cui viene scritto il codice. La classe ScriptMain eredita dalla classe UserComponent.

  2. L'elemento ComponentWrapper, che contiene la classe UserComponent, un'istanza di ScriptComponent che contiene i metodi e le proprietà da usare per elaborare i dati e interagire con il pacchetto. L'elemento ComponentWrapper contiene anche le classi delle raccolte Connections e Variables.

  3. L'elemento BufferWrapper, che contiene le classi che ereditano da ScriptBuffer per ogni input e output, nonché le proprietà tipizzate per ogni colonna.

Quando si scrive il codice nell'elemento ScriptMain si useranno gli oggetti, i metodi e le proprietà illustrati in questo argomento. Ogni componente non utilizzerà tutti i metodi elencati, ma se li utilizza la sequenza sarà quella illustrata.

La classe di base ScriptComponent non contiene codice di implementazione per i metodi descritti in questo argomento. Pertanto, non è necessario aggiungere una chiamata all'implementazione della classe di base nell'implementazione del metodo, anche se questa operazione non genera errori.

Per informazioni su come usare i metodi e le proprietà di queste classi in un tipo di componente script specifico, vedere la sezione Ulteriori esempi di componente script. Negli argomenti di esempio vengono inoltre presentati esempi di codice completi.

Metodo AcquireConnections

Le origini e le destinazioni devono in genere connettersi a un'origine dati esterna. Eseguire l'override del metodo AcquireConnections della classe di base ScriptComponent per recuperare la connessione o le informazioni di connessione dalla gestione connessione appropriata.

Nell'esempio seguente viene restituito System.Data.SqlClient.SqlConnection da una gestione connessione ADO.NET.

Dim connMgr As IDTSConnectionManager100  
Dim sqlConn As SqlConnection  
  
Public Overrides Sub AcquireConnections(ByVal Transaction As Object)  
  
    connMgr = Me.Connections.MyADONETConnection  
    sqlConn = CType(connMgr.AcquireConnection(Nothing), SqlConnection)  
  
End Sub

Nell'esempio seguente vengono restituiti un percorso completo e un nome file da una gestione connessione file flat, quindi il file viene aperto usando System.IO.StreamReader.

Private textReader As StreamReader  
Public Overrides Sub AcquireConnections(ByVal Transaction As Object)  
  
    Dim connMgr As IDTSConnectionManager100 = _  
        Me.Connections.MyFlatFileSrcConnectionManager  
    Dim exportedAddressFile As String = _  
        CType(connMgr.AcquireConnection(Nothing), String)  
    textReader = New StreamReader(exportedAddressFile)  
  
End Sub

Metodo PreExecute

Eseguire l'override del metodo PreExecute della classe di base ScriptComponent quando è necessario eseguire un'elaborazione una volta solo prima di avviare l'elaborazione delle righe di dati. In una destinazione, ad esempio, è possibile configurare il comando con parametri che verrà utilizzato dalla destinazione stessa per inserire ogni riga di dati nell'origine dati.

    Dim sqlConn As SqlConnection  
    Dim sqlCmd As SqlCommand  
    Dim sqlParam As SqlParameter  
...  
    Public Overrides Sub PreExecute()  
  
        sqlCmd = New SqlCommand("INSERT INTO Person.Address2(AddressID, City) " & _  
            "VALUES(@addressid, @city)", sqlConn)  
        sqlParam = New SqlParameter("@addressid", SqlDbType.Int)  
        sqlCmd.Parameters.Add(sqlParam)  
        sqlParam = New SqlParameter("@city", SqlDbType.NVarChar, 30)  
        sqlCmd.Parameters.Add(sqlParam)  
  
    End Sub  

SqlConnection sqlConn;   
SqlCommand sqlCmd;   
SqlParameter sqlParam;   
  
public override void PreExecute()   
{   
  
    sqlCmd = new SqlCommand("INSERT INTO Person.Address2(AddressID, City) " + "VALUES(@addressid, @city)", sqlConn);   
    sqlParam = new SqlParameter("@addressid", SqlDbType.Int);   
    sqlCmd.Parameters.Add(sqlParam);   
    sqlParam = new SqlParameter("@city", SqlDbType.NVarChar, 30);   
    sqlCmd.Parameters.Add(sqlParam);   
  
}

Elaborazione di input e output

Elaborazione di input

I componenti script configurati come trasformazioni o destinazioni prevedono un unico input.

Contenuto dell'elemento di progetto BufferWrapper

Per ogni input configurato, l'elemento di progetto BufferWrapper contiene una classe che deriva da ScriptBuffer e ha lo stesso nome dell'input. Ogni classe del buffer di input contiene le proprietà, le funzioni e i metodi seguenti:

  • Proprietà delle funzioni di accesso denominate e tipizzate per ogni colonna di input selezionata. Queste proprietà sono di sola lettura o di lettura/scrittura a seconda del Tipo di utilizzo specificato per la colonna nella pagina Colonne di input di Editor trasformazione Script.

  • Una proprietà <column>_IsNull per ogni colonna di input selezionata. Anche questa proprietà è di sola lettura o di lettura/scrittura a seconda del Tipo di utilizzo specificato per la colonna.

  • Un metodo DirectRowTo<outputbuffer> per ogni output configurato. Questi metodi verranno usati per filtrare le righe in uno dei diversi output dello stesso elemento ExclusionGroup.

  • Una funzione NextRow per ottenere la riga di input successiva e una funzione EndOfRowset per determinare se è stato elaborato l'ultimo buffer di dati. Queste funzioni non sono in genere necessarie quando si usano i metodi di elaborazione dell'input implementati nella classe di base UserComponent. La sezione seguente contiene altre informazioni sulla classe di base UserComponent.

Contenuto dell'elemento di progetto ComponentWrapper

L'elemento di progetto ComponentWrapper contiene una classe denominata UserComponent che deriva da ScriptComponent. La classe ScriptMain in cui si scrive il codice personalizzato deriva a sua volta da UserComponent. La classe UserComponent contiene i metodi seguenti:

  • Un'implementazione sottoposta a override del metodo ProcessInput. Si tratta del metodo chiamato in fase di esecuzione dal motore flusso di dati dopo il metodo PreExecute e può essere chiamato più volte. ProcessInput passa l'elaborazione al metodo <inputbuffer>_ProcessInput. Il metodo ProcessInput verifica quindi se è stata raggiunta la fine del buffer di input e, in caso affermativo, chiama il metodo FinishOutputs sottoponibile a override e il metodo MarkOutputsAsFinished privato. Il metodo MarkOutputsAsFinished chiama quindi SetEndOfRowset sull'ultimo buffer di output.

  • Un'implementazione sottoponibile a override del metodo <inputbuffer>_ProcessInput. Questa implementazione predefinita esegue il ciclo di ogni riga di input e chiama <inputbuffer>_ProcessInputRow.

  • Un'implementazione sottoponibile a override del metodo <inputbuffer>_ProcessInputRow. L'implementazione predefinita è vuota. Si tratta del metodo di cui in genere si esegue l'override per scrivere il codice personalizzato di elaborazione dati.

Funzione del codice personalizzato

Per elaborare l'input nella classe ScriptMain è possibile usare i metodi seguenti:

  • Eseguire l'override di <inputbuffer>_ProcessInputRow per elaborare i dati in ogni riga di input non appena vengono passati.

  • Eseguire l'override di <inputbuffer>_ProcessInput solo se è necessario eseguire operazioni aggiuntive mentre si esegue il ciclo delle righe di input, ad esempio se è necessario verificare la presenza di EndOfRowset per eseguire un'altra azione dopo l'elaborazione di tutte le righe. Chiamare <inputbuffer>_ProcessInputRow per eseguire l'elaborazione delle righe.

  • Eseguire l'override di FinishOutputs se è necessario eseguire operazioni sugli output prima che vengano chiusi.

Il metodo ProcessInput assicura che questi metodi vengano chiamati nel momento appropriato.

Elaborazione degli output

I componenti script configurati come origini o trasformazioni includono uno o più output.

Contenuto dell'elemento di progetto BufferWrapper

Per ogni output configurato, l'elemento di progetto BufferWrapper contiene una classe che deriva da ScriptBuffer e ha lo stesso nome dell'output. Ogni classe del buffer di input contiene le proprietà e i metodi seguenti:

  • Proprietà delle funzioni di accesso di sola scrittura, denominate e tipizzate per ogni colonna di output.

  • Una proprietà <column>_IsNull di sola scrittura per ogni colonna di output selezionata che è possibile usare per impostare il valore della colonna su Null.

  • Un metodo AddRow per aggiungere una nuova riga vuota nel buffer di output.

  • Un metodo SetEndOfRowset per indicare al motore flusso di dati che non sono previsti altri buffer di dati. È inoltre disponibile una funzione EndOfRowset per determinare se il buffer corrente è l'ultimo buffer di dati. Queste funzioni non sono in genere necessarie quando si usano i metodi di elaborazione dell'input implementati nella classe di base UserComponent.

Contenuto dell'elemento di progetto ComponentWrapper

L'elemento di progetto ComponentWrapper contiene una classe denominata UserComponent che deriva da ScriptComponent. La classe ScriptMain in cui si scrive il codice personalizzato deriva a sua volta da UserComponent. La classe UserComponent contiene i metodi seguenti:

  • Un'implementazione sottoposta a override del metodo PrimeOutput. Il motore flusso di dati chiama questo metodo prima di ProcessInput in fase di esecuzione e viene chiamato solo una volta. PrimeOutput passa l'elaborazione al metodo CreateNewOutputRows. Quindi, se il componente è un'origine, ovvero non include input, PrimeOutput chiama il metodo FinishOutputs sottoponibile a override e il metodo MarkOutputsAsFinished privato. Il metodo MarkOutputsAsFinished chiama SetEndOfRowset sull'ultimo buffer di output.

  • Un'implementazione sottoponibile a override del metodo CreateNewOutputRows. L'implementazione predefinita è vuota. Si tratta del metodo di cui in genere si esegue l'override per scrivere il codice personalizzato di elaborazione dati.

Funzione del codice personalizzato

Per elaborare gli output nella classe ScriptMain è possibile usare i metodi seguenti:

  • Eseguire l'override di CreateNewOutputRows solo quando è possibile aggiungere e popolare le righe di output prima dell'elaborazione delle righe di input. Ad esempio, è possibile usare CreateNewOutputRows in un'origine, ma in una trasformazione con output asincroni è necessario chiamare AddRow durante o dopo l'elaborazione dei dati di input.

  • Eseguire l'override di FinishOutputs se è necessario eseguire operazioni sugli output prima che vengano chiusi.

Il metodo PrimeOutput assicura che questi metodi vengano chiamati nel momento appropriato.

Metodo PostExecute

Eseguire l'override del metodo PostExecute della classe di base ScriptComponent quando è necessario eseguire un'elaborazione un'unica volta solo dopo aver elaborato le righe di dati. In un'origine, ad esempio, può essere opportuno chiudere l'oggetto System.Data.SqlClient.SqlDataReader usato per caricare i dati nel flusso di dati.

Importante

La raccolta di ReadWriteVariables è disponibile solo nel metodo PostExecute. Pertanto, non è possibile incrementare direttamente il valore di una variabile del pacchetto durante l'elaborazione di ogni riga di dati. Incrementare invece il valore di una variabile locale e impostare il valore della variabile del pacchetto sul valore della variabile locale nel metodo PostExecute dopo che tutti i dati sono stati elaborati.

Metodo ReleaseConnections

Le origini e le destinazioni devono in genere connettersi a un'origine dati esterna. Eseguire l'override del metodo ReleaseConnections della classe di base ScriptComponent per chiudere e rilasciare la connessione aperta in precedenza nel metodo AcquireConnections.

    Dim connMgr As IDTSConnectionManager100  
...  
    Public Overrides Sub ReleaseConnections()  
  
        connMgr.ReleaseConnection(sqlConn)  
  
    End Sub  

IDTSConnectionManager100 connMgr;  
  
public override void ReleaseConnections()  
{  
  
    connMgr.ReleaseConnection(sqlConn);  
  
}

Vedere anche

Configurazione del componente script nell'editor corrispondente
Codifica e debug del componente script