SQL Database プロジェクトの拡張機能と SDK スタイルの SQL プロジェクトを併用する (プレビュー)

この記事では、Azure Data Studio または Visual Studio Code の SQL Database プロジェクトの拡張機能における SDK スタイルの SQL プロジェクト用 Microsoft.Build.Sql を紹介します。 SDK スタイルの SQL プロジェクトは、パイプラインまたは組み込みのクロスプラットフォーム環境で出荷されるアプリケーションにとって特に便利です。 初期のお知らせは、TechCommunity で参照できます。

注意

Microsoft.Build.Sql は、現在プレビュー段階です。

SDK スタイルのデータベース プロジェクトを作成する

SDK スタイルのデータベース プロジェクトは、空白プロジェクトまたは既存のデータベースから作成できます。

空白プロジェクト

[データベース プロジェクト] ビューで [新しいプロジェクト] ボタンを選び、表示されたテキスト入力にプロジェクト名を入力します。 表示される [フォルダーの選択] ダイアログ ボックスで、プロジェクトのフォルダー、.sqlproj ファイル、そこに含まれるその他のコンテンツを選択します。

既定では、[SDK-style project (Preview)](SDK スタイルのプロジェクト (プレビュー)) の選択項目がオンになっています。 ダイアログでの指定が済むと、空白のプロジェクトが開き、編集のために [データベース プロジェクト] ビューに表示されます。

既存のデータベースから

[プロジェクト] ビューで、[データベースからプロジェクトを作成] ボタンを選択して SQL Server に接続します。 接続が確立されたら、使用可能なデータベースのリストからデータベースを選択し、プロジェクトの名前を設定します。 抽出のターゲット構造体を選択します。

既定では、[SDK-style project (Preview)](SDK スタイルのプロジェクト (プレビュー)) の選択項目がオンになっています。 ダイアログを完成させると、新しいプロジェクトが開き、選択したデータベースのコンテンツに対応する SQL スクリプトが含まれます。

ビルドして発行する

Azure Data Studio および Visual Studio Code インターフェイスからの、SDK スタイルの SQL プロジェクトのビルドと発行は、前の SQL プロジェクトの形式と同じ方法で完了します。 このプロセスの詳細については、「プロジェクトをビルドして公開する」を参照してください。

Windows、macOS、または Linux のコマンド ラインから SDK スタイルの SQL プロジェクトをビルドするには、次のコマンドを使用します。

dotnet build

SDK スタイルの SQL プロジェクトのビルド結果である .dacpac ファイルは、データ層アプリケーション フレームワーク (.dacpac、.bacpac) に関連付けられているツール (SqlPackage と GitHub sql-action を含む) と互換性があります。

プロジェクトの機能

SQL プロジェクトでは、プロジェクトのビルドまたは配置時にデータベース モデルに影響を与えるいくつかの機能を .sqlproj ファイルに指定できます。 次のセクションでは、Microsoft.Build.Sql プロジェクトで使用できるこれらの機能の一部について説明します。

ターゲット プラットフォーム

ターゲット プラットフォーム プロパティは、<PropertyGroup> 項目の下の .sqlproj ファイルの DSP タグに含まれています。 ターゲット プラットフォームは、プロジェクトのビルド中に、プロジェクトに含まれる機能のサポートを検証するために使用され、プロパティとして .dacpac ファイルに追加されます。 既定では、配置中にターゲット プラットフォームがターゲット データベースに対してチェックされ、互換性が確保されます。 ターゲット プラットフォームがターゲット データベースでサポートされていない場合、オーバーライド発行オプション が指定されていない限り、配置は失敗します。

<Project DefaultTargets="Build">
  <Sdk Name="Microsoft.Build.Sql" Version="0.1.12-preview" />
  <PropertyGroup>
    <Name>AdventureWorks</Name>
    <DSP>Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider</DSP>
  </PropertyGroup>

ターゲット プラットフォームの有効な設定は次のとおりです。

• Microsoft.Data.Tools.Schema.Sql.Sql120DatabaseSchemaProvider
• Microsoft.Data.Tools.Schema.Sql.Sql130DatabaseSchemaProvider
• Microsoft.Data.Tools.Schema.Sql.Sql140DatabaseSchemaProvider
• Microsoft.Data.Tools.Schema.Sql.Sql150DatabaseSchemaProvider
• Microsoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProvider
• Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider
• Microsoft.Data.Tools.Schema.Sql.SqlDwDatabaseSchemaProvider
• Microsoft.Data.Tools.Schema.Sql.SqlServerlessDatabaseSchemaProvider
• Microsoft.Data.Tools.Schema.Sql.SqlDwUnifiedDatabaseSchemaProvider

データベース参照

配置時のデータベース モデルの検証は、データベース参照を介して SQL プロジェクトの内容を超えて拡張できます。 .sqlproj ファイルで指定されたデータベース参照は、同じデータベースの別のデータベースまたは複数のコンポーネントを表す別の SQL プロジェクト、または .dacpac ファイルを参照できます。

別のデータベースを表すデータベース参照には、次の属性を使用できます。

• DatabaseSqlCmdVariable: 値は、データベースを参照するために使用される変数の名前です
  • 参照設定: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
  • 使用例: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
• ServerSqlCmdVariable: 値は、データベースが存在するサーバーを参照するために使用される変数の名前です。 データベースが別のサーバーにある場合は、DatabaseSqlCmdVariable と共に使用されます。
  • 参照設定: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
  • 使用例: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
• DatabaseVariableLiteralValue:DatabaseSqlCmdVariable と同様に、値は SQL プロジェクトで使用されるデータベースのリテラル名ですが、他のデータベースへの参照はリテラル値です
  • 参照設定: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
  • 使用例: SELECT * FROM [SomeOtherDatabase].dbo.Table1

SQL プロジェクト ファイルでは、Include 属性が .dacpac ファイルのパスに設定された ArtifactReference 項目としてデータベース参照が指定されます。

  <ItemGroup>
    <ArtifactReference Include="SampleA.dacpac">
      <DatabaseSqlCmdVariable>DatabaseA</DatabaseSqlCmdVariable>
    </ArtifactReference>
  </ItemGroup>
</Project>

パッケージ参照

パッケージ参照は、.dacpac ファイルを含む NuGet パッケージを参照するために使用され、データベース参照と同様にビルド時にデータベース モデルを拡張するために使用されます。

SQL プロジェクト ファイルの次の例では、master データベースの Microsoft.SqlServer.Dacpacs パッケージを参照しています。

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0" />
  </ItemGroup>
</Project>

データベース参照に使用できる属性に加えて、次の DacpacName 属性を指定して、複数の .dacpac ファイルを含むパッケージから .dacpac を選択できます。

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0">
      <DacpacName>msdb</DacpacName>
    </PackageReference>
  </ItemGroup>
</Project>

SqlCmd 変数

SqlCmd 変数は .sqlproj ファイルで定義でき、.dacpac 配置時に SQL オブジェクトとスクリプトのトークンを置き換えるために使用されます。 SQL プロジェクト ファイルの次の例では、プロジェクトのオブジェクトとスクリプトで使用できる EnvironmentName という名前の変数を定義しています。

  <ItemGroup>
    <SqlCmdVariable Include="EnvironmentName">
      <DefaultValue>testing</DefaultValue>
      <Value>$(SqlCmdVar__1)</Value>
    </SqlCmdVariable>
  </ItemGroup>
</Project>

IF '$(EnvironmentName)' = 'testing'
BEGIN
    -- do something
END

コンパイル済み SQL プロジェクト (.dacpac) が配置されると、変数の値が配置コマンドで指定された値に置き換えられます。 たとえば、次のコマンドは AdventureWorks.dacpac を配置し、EnvironmentName 変数の値を production に設定します。

SqlPackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /v:EnvironmentName=production

配置前および配置後スクリプト

配置前および配置後スクリプトは、配置中に実行されるプロジェクトに含まれる SQL スクリプトです。 配置前および配置後スクリプトは .dacpac に含まれていますが、データベース オブジェクト モデルにコンパイルまたは検証されません。 配置前スクリプトは、データベース モデルが適用される前に実行され、配置後スクリプトは、データベース モデルが適用された後に実行されます。 SQL プロジェクト ファイルの次の例では、配置後スクリプトとして populate-app-settings.sql ファイルを追加します。

  <ItemGroup>
    <PostDeploy Include="populate-app-settings.sql" />
  </ItemGroup>
</Project>

次のステップ

• SQL Database プロジェクトの拡張機能を使用してプロジェクトをビルドして公開する
• CLI からの配置用に SqlPackage をインストールする
• SQL データベース プロジェクトの拡張機能でヘルプを得る
• SQL プロジェクトと DacFx に関するヘルプを得る