スクリプトコンポーネントによる変換元の作成

[アーティクル]
05/23/2023

適用対象:SQL Server Azure Data Factory の SSIS Integration Runtime

Integration Services パッケージのデータフロー内で変換元コンポーネントを使用すると、データソースからデータを読み込み、下流にある変換や変換先に渡すことができます。通常、データソースへの接続には、既存の接続マネージャーを使用します。

スクリプトコンポーネントの概要については、「スクリプトコンポーネントによるデータフローの拡張」を参照してください。

スクリプトコンポーネントおよびそれによって生成されるインフラストラクチャコードを活用すれば、カスタムデータフローコンポーネントを開発するための手順を大幅に簡略化できます。スクリプトコンポーネントの動作のしくみを理解するため、カスタムデータフローコンポーネントの開発手順を理解しておくと役立つ場合があります。「カスタムデータフローコンポーネントの開発」セクション、特に「カスタム変換元コンポーネントの開発」トピックを参照してください。

変換元コンポーネントの概要

デザイナーの [データフロー] ペインにスクリプトコンポーネントを追加すると、[スクリプトコンポーネントの種類を選択] ダイアログボックスが開き、[変換元]、[変換先]、[変換] スクリプトのいずれかを選択するように求められます。このダイアログボックスで、 [変換元] を選択します。

メタデータデザインモードでの変換元コンポーネントの構成

変換元コンポーネントの作成を選択したら、 [スクリプト変換エディター] を使用して、コンポーネントを構成します。詳細については、「スクリプトコンポーネントエディターでのスクリプトコンポーネントの構成」を参照してください。

データフロー変換元コンポーネントに入力はありませんが、1 つ以上の出力を設定できます。コンポーネントの出力の設定は、メタデータデザインモードでカスタムスクリプトを記述する前に完了する必要のある手順の 1 つです。これを行うには、 [スクリプト変換エディター] を使用します。

[スクリプト変換エディター] の [スクリプト] ページにある [ScriptLanguage] プロパティを設定して、スクリプト言語を指定することもできます。

Note

スクリプトコンポーネントとスクリプトタスクの既定のスクリプト言語を設定するには、 [オプション] ダイアログボックスの [全般] ページにある [スクリプト言語] オプションを使用します。詳細については、「 General Page」を参照してください。

接続マネージャーの追加

通常、変換元コンポーネントは既存の接続マネージャーを使用してデータソースに接続し、データをデータフローに読み込みます。 [スクリプト変換エディター] の [接続マネージャー] ページで [追加] をクリックして、適切な接続マネージャーを追加します。

ただし、接続マネージャーは、便宜上、特定の種類のデータソースに接続するために必要な情報をカプセル化して格納するユニットにすぎません。データの読み込みや保存、場合によってはデータソースとの接続や切断を行うためには、独自のカスタムコードを記述する必要もあります。

スクリプトコンポーネントで接続マネージャーを使用する方法の一般情報については、「スクリプトコンポーネントでのデータソースへの接続」を参照してください。

[スクリプト変換エディター] の [接続マネージャー] ページの詳細については、「スクリプト変換エディター ([接続マネージャー] ページ)」を参照してください。

出力および出力列の設定

変換元コンポーネントに入力はありませんが、1 つ以上の出力を設定できます。 [スクリプト変換エディター] の [入力および出力] ページには、既定で 1 つの出力が作成されていますが、出力列は作成されていません。エディターのこのページで、必要に応じて以下の項目を設定します。

各出力に対する出力列は、手動で追加して設定する必要があります。各出力に対する [出力列] フォルダーを選択し、 [列の追加] および [列の削除] ボタンを使用して、変換元コンポーネントの各出力に対する出力列を管理します。後でスクリプト内で出力列を参照する際には、ここで割り当てた名前、および自動生成されたコードによって作成された、型指定されたアクセサープロパティを使用します。
予期しない値を含む行に対するシミュレートされたエラー出力など、1 つ以上の出力を追加して作成できます。 [出力の追加] および [出力の削除] ボタンを使用して、変換元コンポーネントの出力を管理します。すべての入力行は使用可能なすべての出力に送られます。ただし、出力の ExclusionGroup プロパティに 0 以外の同じ値を指定すると、各行を、同じ ExclusionGroup の値を共有する出力のうちいずれか 1 つにのみ送ることもできます。 ExclusionGroup を識別するために選択された整数値に、特別な意味はありません。

Note

すべての行を出力しない場合は、0 以外の ExclusionGroup プロパティ値を単一の出力で使用することもできます。ただし、この場合は、出力に送信する各行について、DirectRowTo<outputbuffer> メソッドを明示的に呼び出す必要があります。
出力にはわかりやすい名前を付けておくことができます。後で出力を参照する際には、スクリプト内での名前、および自動生成されたコードによって作成された、型指定されたアクセサープロパティを使用します。
通常、同じ ExclusionGroup 内の複数の出力には、同じ出力列が含まれます。ただし、シミュレートされたエラー出力を作成するには、エラー情報を格納するために列の追加が必要になる場合があります。データフローエンジンがエラー行を処理する方法については、「データフローコンポーネントでのエラー出力の使用」を参照してください。ただし、スクリプトコンポーネントでは、独自のコードを記述して、追加した列に該当するエラー情報を格納する必要があります。詳細については、「スクリプトコンポーネントに対するエラー出力のシミュレート」を参照してください。

[スクリプト変換エディター] の [入力および出力] ページの詳細については、「[スクリプト変換エディター] ([入力および出力] ページ)」を参照してください。

変数の追加

値をスクリプト内で使用する既存の変数がある場合は、 [スクリプト変換エディター] の [スクリプト] ページで、ReadOnlyVariables および ReadWriteVariables プロパティフィールドに追加できます。

プロパティフィールドに複数の変数を入力する場合は、変数名をコンマで区切ります。また、ReadOnlyVariables および ReadWriteVariables プロパティフィールドの横にある省略記号 ( [...] ) ボタンをクリックして [変数の選択] ダイアログボックスで変数を選択することで、複数の変数を入力することもできます。

スクリプトコンポーネントで変数を使用する方法に関する一般情報については、「スクリプトコンポーネントでの変数の使用」を参照してください。

[スクリプト変換エディター] の [スクリプト] ページの詳細については、「[スクリプト変換エディター] ([スクリプト] ページ)」を参照してください。

コードデザインモードでの変換元コンポーネントのスクリプト作成

コンポーネントのメタデータを構成したら、Microsoft Visual Studio Tools for Applications (VSTA) IDE を開き、カスタムスクリプトのコードを作成します。 VSTA を開くには、 [スクリプト変換エディター] の [スクリプト] ページで、 [スクリプトの編集] をクリックします。 [ScriptLanguage] プロパティで選択したスクリプト言語に応じて Microsoft Visual Basic と Microsoft Visual C# のいずれかを使用して、独自のスクリプトを記述できます。

スクリプトコンポーネントを使用して作成されたすべての種類のコンポーネントに適用される重要な情報については、「スクリプトコンポーネントのコーディングおよびデバッグ」を参照してください。

自動生成されたコードについて

変換元コンポーネントを作成して構成した後で VSTA IDE を開くと、コードエディターには編集可能な ScriptMain クラスが表示されます。この ScriptMain クラスにカスタムコードを記述します。

ScriptMain クラスには、CreateNewOutputRows メソッドのスタブが含まれています。 CreateNewOutputRows は、変換元コンポーネントの最重要メソッドです。

VSTA の [プロジェクトエクスプローラー] ウィンドウを開くと、スクリプトコンポーネントにより、BufferWrapper および ComponentWrapper というプロジェクトアイテムが、読み取り専用の状態で自動生成されていることもわかります。 ScriptMain クラスは、ComponentWrapper プロジェクトアイテム内の UserComponent クラスから継承されます。

実行時には、データフローエンジンが UserComponent クラスの PrimeOutput メソッドを呼び出します。これにより、ScriptComponent 親クラスの PrimeOutput メソッドがオーバーライドされます。次に、PrimeOutput メソッドは以下のメソッドを呼び出します。

CreateNewOutputRows メソッド。これを ScriptMain でオーバーライドして、最初は空である出力バッファーに、データソースの行を追加します。
FinishOutputs メソッド。既定では空です。このメソッドを ScriptMain でオーバーライドして、出力を完了するために必要な処理を実行します。
MarkOutputsAsFinished プライベートメソッド。これは、ScriptBuffer 親クラスの SetEndOfRowset メソッドを呼び出し、出力が完了したことをデータフローエンジンに示します。独自のコードで明示的に SetEndOfRowset を呼び出す必要はありません。

カスタムコードの記述

カスタム変換元コンポーネントの作成を終了するには、必要に応じて ScriptMain クラスで使用できる次のメソッドにスクリプトを記述する場合があります。

外部データソースに接続する場合は、AcquireConnections メソッドをオーバーライドします。接続マネージャーから、接続オブジェクトまたは必要な接続情報を抽出します。
変換元データをすべて同時に読み込める場合は、PreExecute メソッドをオーバーライドしてデータを読み込みます。たとえば、SQL Server データベースへの ADO.NET 接続に対して SqlCommand を実行し、すべての変換元データを同時に SqlDataReader に読み込むことができます。変換元データを 1 行ずつ読み込む必要がある場合 (たとえば、テキストファイルを読み取る場合)、は、CreateNewOutputRows で行をループする際にデータを読み込むことができます。
オーバーライドされた CreateNewOutputRows メソッドを使用して、空の出力バッファーに新しい行を追加し、新しい出力行に各列の値を入力します。各出力バッファーの AddRow メソッドを使用して空の新しい行を追加し、各列の値を設定します。通常は、外部ソースから読み込まれた列から値をコピーします。
PostExecute メソッドをオーバーライドして、データの処理を終了します。たとえば、データを読み込むために使用した SqlDataReader を閉じることができます。
ReleaseConnections メソッドを必要に応じてオーバーライドして、外部データソースとの接続を切断します。

例

次の例では、変換元コンポーネントを作成するために、ScriptMain クラスで必要なカスタムコードを示します。

Note

これらの例では、AdventureWorks サンプルデータベースの Person.Address テーブルを使用して、その第 1 列および第 4 列、つまり、intAddressID 列および nvarchar(30)City 列をデータフローにそのまま渡します。このセクションの変換元、変換、および変換先の例でも、同じデータが使用されます。他の前提条件および仮定条件については、それぞれの例で説明します。

ADO.NET ソースの例

この例では、既存の ADO.NET 接続マネージャーを使用して、SQL Server のテーブルからデータを読み込み、データフローに送る変換元コンポーネントを示します。

このサンプルコードを実行する場合は、パッケージやコンポーネントを次のように構成する必要があります。

SqlClient プロバイダーを使用する ADO.NET 接続マネージャーを作成して、AdventureWorks データベースに接続します。
新しいスクリプトコンポーネントを [データフロー] デザイナー画面に追加し、変換元として構成します。
[スクリプト変換エディター] を開きます。 [入力および出力] ページで、既定の出力を MyAddressOutput などのわかりやすい名前に変更し、AddressID と City という 2 つの出力列を追加して構成します。

Note

City 出力列のデータ型は必ず DT_WSTR に変更してください。
[接続マネージャー] ページで、ADO.NET 接続マネージャーを追加または作成し、MyADONETConnection などの名前を付けます。
[スクリプト] ページで、 [スクリプトの編集] をクリックし、続きのスクリプトを入力します。その後、スクリプト開発環境と [スクリプト変換エディター] を閉じます。
SQL Server の変換先、または「スクリプトコンポーネントによる変換先の作成」で説明されている変換先コンポーネントの例など、AddressID および City 列が予期される変換先コンポーネントを作成して構成します。変換元のコンポーネントを変換先に接続します (変換なしで直接変換元を変換先に接続することもできます)。AdventureWorks データベースで次の Transact-SQL コマンドを実行して、変換先テーブルを作成できます。
```
CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL,  
    [City] [nvarchar](30) NOT NULL)  
```

サンプルを実行します。

Imports System.Data.SqlClient  
...  
Public Class ScriptMain  
    Inherits UserComponent  

    Dim connMgr As IDTSConnectionManager100  
    Dim sqlConn As SqlConnection  
    Dim sqlReader As SqlDataReader  

    Public Overrides Sub AcquireConnections(ByVal Transaction As Object)  

        connMgr = Me.Connections.MyADONETConnection  
        sqlConn = CType(connMgr.AcquireConnection(Nothing), SqlConnection)  

    End Sub  

    Public Overrides Sub PreExecute()  

        Dim cmd As New SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", sqlConn)  
        sqlReader = cmd.ExecuteReader  

    End Sub  

    Public Overrides Sub CreateNewOutputRows()  

        Do While sqlReader.Read  
            With MyAddressOutputBuffer  
                .AddRow()  
                .AddressID = sqlReader.GetInt32(0)  
                .City = sqlReader.GetString(1)  
            End With  
        Loop  

    End Sub  

    Public Overrides Sub PostExecute()  

        sqlReader.Close()  

    End Sub  

    Public Overrides Sub ReleaseConnections()  

        connMgr.ReleaseConnection(sqlConn)  

    End Sub  

End Class

using System.Data.SqlClient;  
public class ScriptMain:  
    UserComponent  

{  
    IDTSConnectionManager100 connMgr;  
    SqlConnection sqlConn;  
    SqlDataReader sqlReader;  

    public override void AcquireConnections(object Transaction)  
    {  
        connMgr = this.Connections.MyADONETConnection;  
        sqlConn = (SqlConnection)connMgr.AcquireConnection(null);  

    }  

    public override void PreExecute()  
    {  

        SqlCommand cmd = new SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", sqlConn);  
        sqlReader = cmd.ExecuteReader();  

    }  

    public override void CreateNewOutputRows()  
    {  

        while (sqlReader.Read())  
        {  
            {  
                MyAddressOutputBuffer.AddRow();  
                MyAddressOutputBuffer.AddressID = sqlReader.GetInt32(0);  
                MyAddressOutputBuffer.City = sqlReader.GetString(1);  
            }  
        }  

    }  

    public override void PostExecute()  
    {  

        sqlReader.Close();  

    }  

    public override void ReleaseConnections()  
    {  

        connMgr.ReleaseConnection(sqlConn);  

    }  

}

フラットファイルソースの例

この例では、既存のフラットファイル接続マネージャーを使用して、フラットファイルからデータを読み込み、データフローに送る変換元コンポーネントを示します。フラットファイルソースのデータは、SQL Server からエクスポートすることにより作成されます。

このサンプルコードを実行する場合は、パッケージやコンポーネントを次のように構成する必要があります。

SQL Server インポートおよびエクスポートウィザードを使用して、AdventureWorks サンプルデータベースから、Person.Address テーブルをコンマ区切りフラットファイルにエクスポートします。この例では、ファイル名を ExportedAddresses.txt とします。
エクスポートされたデータファイルに接続するフラットファイル接続マネージャーを作成します。
新しいスクリプトコンポーネントを [データフロー] デザイナー画面に追加し、変換元として構成します。
[スクリプト変換エディター] を開きます。 [入力および出力] ページで、既定の出力を MyAddressOutput などのわかりやすい名前に変更します。 AddressID と City という 2 つの出力列を追加して構成します。
[接続マネージャー] ページで、MyFlatFileSrcConnectionManager などのわかりやすい名前を使用して、フラットファイル接続マネージャーを追加または作成します。
[スクリプト] ページで、 [スクリプトの編集] をクリックし、続きのスクリプトを入力します。その後、スクリプト開発環境と [スクリプト変換エディター] を閉じます。
SQL Server の変換先、または「スクリプトコンポーネントによる変換先の作成」で説明されている変換先コンポーネントの例など、変換先コンポーネントを作成して構成します。変換元のコンポーネントを変換先に接続します (変換なしで直接変換元を変換先に接続することもできます)。AdventureWorks データベースで次の Transact-SQL コマンドを実行して、変換先テーブルを作成できます。
```
CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL,  
    [City] [nvarchar](30) NOT NULL)  
```

サンプルを実行します。

Imports System.IO  
...  
Public Class ScriptMain  
    Inherits UserComponent  

    Private textReader As StreamReader  
    Private exportedAddressFile As String  

    Public Overrides Sub AcquireConnections(ByVal Transaction As Object)  

        Dim connMgr As IDTSConnectionManager100 = _  
            Me.Connections.MyFlatFileSrcConnectionManager  
        exportedAddressFile = _  
            CType(connMgr.AcquireConnection(Nothing), String)  

    End Sub  

    Public Overrides Sub PreExecute()  
        MyBase.PreExecute()  
        textReader = New StreamReader(exportedAddressFile)  
    End Sub  

    Public Overrides Sub CreateNewOutputRows()  

        Dim nextLine As String  
        Dim columns As String()  

        Dim delimiters As Char()  
        delimiters = ",".ToCharArray  

        nextLine = textReader.ReadLine  
        Do While nextLine IsNot Nothing  
            columns = nextLine.Split(delimiters)  
            With MyAddressOutputBuffer  
                .AddRow()  
                .AddressID = columns(0)  
                .City = columns(3)  
            End With  
            nextLine = textReader.ReadLine  
        Loop  

    End Sub  

    Public Overrides Sub PostExecute()  
        MyBase.PostExecute()  
        textReader.Close()  

    End Sub  

End Class

using System.IO;  
public class ScriptMain:  
    UserComponent  

{  
    private StreamReader textReader;  
    private string exportedAddressFile;  

    public override void AcquireConnections(object Transaction)  
    {  

        IDTSConnectionManager100 connMgr = this.Connections.MyFlatFileSrcConnectionManager;  
        exportedAddressFile = (string)connMgr.AcquireConnection(null);  

    }  

    public override void PreExecute()  
    {  
        base.PreExecute();  
        textReader = new StreamReader(exportedAddressFile);  
    }  

    public override void CreateNewOutputRows()  
    {  

        string nextLine;  
        string[] columns;  

        char[] delimiters;  
        delimiters = ",".ToCharArray();  

        nextLine = textReader.ReadLine();  
        while (nextLine != null)  
        {  
            columns = nextLine.Split(delimiters);  
            {  
                MyAddressOutputBuffer.AddRow();  
                MyAddressOutputBuffer.AddressID = columns[0];  
                MyAddressOutputBuffer.City = columns[3];  
            }  
            nextLine = textReader.ReadLine();  
        }  

    }  

    public override void PostExecute()  
    {  

        base.PostExecute();  
        textReader.Close();  

    }  

}

参照

スクリプトコンポーネントによる変換先の作成
 カスタム変換元コンポーネントの開発

次の方法で共有

スクリプトコンポーネントによる変換元の作成

変換元コンポーネントの概要

メタデータデザインモードでの変換元コンポーネントの構成

接続マネージャーの追加

出力および出力列の設定

変数の追加

コードデザインモードでの変換元コンポーネントのスクリプト作成

自動生成されたコードについて

カスタムコードの記述

例

ADO.NET ソースの例

フラットファイルソースの例

参照

フィードバック

フィードバック

その他のリソース

次の方法で共有

スクリプト コンポーネントによる変換元の作成

変換元コンポーネントの概要

メタデータ デザイン モードでの変換元コンポーネントの構成

接続マネージャーの追加

出力および出力列の設定

変数の追加

コード デザイン モードでの変換元コンポーネントのスクリプト作成

自動生成されたコードについて

カスタム コードの記述

例

ADO.NET ソースの例

フラット ファイル ソースの例

参照

フィードバック

フィードバック

その他のリソース

スクリプトコンポーネントによる変換元の作成

メタデータデザインモードでの変換元コンポーネントの構成

コードデザインモードでの変換元コンポーネントのスクリプト作成

カスタムコードの記述

フラットファイルソースの例