Verwenden von SDK-Stil SQL-Projekten mit der SQL-Datenbank-Projekterweiterung (Vorschau)

  • Artikel

Dieser Artikel stellt Microsoft.Build.Sql für SQL-Projekte im SDK-Stil in der SQL Database Projects-Erweiterung in Azure Data Studio oder Visual Studio Code vor. SDK-Stil SQL-Projekte sind besonders vorteilhaft für Anwendungen, die über Pipelines geliefert oder in plattformübergreifenden Umgebungen aufgebaut werden. Die erste Ankündigung ist in TechCommunity verfügbar.

Hinweis

Microsoft.Build.Sql befindet sich derzeit in der Vorschauphase.

Erstellen eines SDK-Stil Datenbankprojekts

Sie können ein SDK-Stil Datenbankprojekt aus einem leeren Projekt oder aus einer vorhandenen Datenbank erstellen.

Leeres Projekt

Wählen Sie in der Ansicht Datenbankprojekte die Schaltfläche Neues Projekt aus, und geben Sie in der angezeigten Texteingabe einen Projektnamen ein. Wählen Sie im angezeigten Dialogfeld Select a Folder (Ordner auswählen) ein Verzeichnis für den Ordner, die .sqlproj-Datei und andere Inhalte des Projekts aus.

Standardmäßig ist die Auswahl für das SDK-Stil Projekt (Vorschau) aktiviert. Wenn das Dialogfeld abgeschlossen ist, wird das leere Projekt geöffnet und zur Bearbeitung in der Ansicht Datenbankprojekte angezeigt.

Von einer bestehenden Datenbank

Klicken Sie in der Ansicht Projekte auf die Schaltfläche Create Project from Database (Projekt aus Datenbank erstellen), und stellen Sie eine Verbindung mit einer SQL Server-Instanz her. Wählen Sie, sobald die Verbindung hergestellt wurde, eine Datenbank aus der Liste der verfügbaren Datenbanken aus, und legen Sie den Namen des Projekts fest. Wählen Sie eine Zielstruktur für die Extraktion aus.

Standardmäßig ist die Auswahl für das SDK-Stil Projekt (Vorschau) aktiviert. Wenn das Dialogfeld abgeschlossen ist, wird das neue Projekt geöffnet und enthält SQL-Skripts für die Inhalte der ausgewählten Datenbank.

Erstellen und Veröffentlichen

Das Erstellen und Veröffentlichen eines SQL-Projekts im SDK-Stil wird aus den Schnittstellen von Azure Data Studio und von Visual Studio Code genauso wie das vorherige SQL-Projektformat abgeschlossen. Weitere Informationen zu diesem Prozess finden Sie unter Erstellen und Veröffentlichen eines Projekts.

Um ein SQL-Projekt im SDK-Stil über die Befehlszeile unter Windows, macOS oder Linux zu erstellen, verwenden Sie den folgenden Befehl:

dotnet build

Die .dacpac-Datei, die das Ergebnis der Erstellung eines SQL-Projekts im SDK-Stil ist, ist mit Tools kompatibel, die dem Datenebenen-Anwendunsframework (.dacpac, .bacpac), einschließlich SqlPackage und sql-action von GitHub zugeordnet sind.

Projektfunktionen

In SQL-Projekten gibt es mehrere Funktionen, die in der .sqlproj-Datei angegeben werden können, die sich entweder beim Erstellen des Projekts oder bei der Bereitstellung auf das Datenbankmodell auswirken. In den folgenden Abschnitten werden einige dieser Funktionen beschrieben, die für Microsoft.Build.Sql-Projekte verfügbar sind.

Zielplattform

Die Zielplattformeigenschaft ist im DSP-Tag in der .sqlproj-Datei unter dem <PropertyGroup>-Element enthalten. Die Zielplattform wird während der Projekterstellung verwendet, um die Unterstützung für im Projekt enthaltene Features zu überprüfen, und wird der .dacpac-Datei als Eigenschaft hinzugefügt. Standardmäßig wird die Zielplattform während der Bereitstellung anhand der Zieldatenbank überprüft, um Kompatibilität sicherzustellen. Wenn die Zielplattform von der Zieldatenbank nicht unterstützt wird, tritt bei der Bereitstellung ein Fehler auf, es sei denn, es wurde eine Überschreibungsoption für die Veröffentlichung angegeben.

<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>

Gültige Einstellungen für die Zielplattform sind:

  • 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

Datenbankverweise

Die Datenbankmodellvalidierung zur Buildzeit kann über den Inhalt des SQL-Projekts hinweg durch Datenbankverweise erweitert werden. Datenbankverweise, die in der .sqlproj-Datei angegeben werden, können auf ein anderes SQL-Projekt oder eine .dacpac-Datei verweisen, das bzw. die entweder eine andere Datenbank oder weitere Komponenten derselben Datenbank darstellt.

Die folgenden Attribute sind für Datenbankverweise verfügbar, die eine andere Datenbank darstellen:

  • DatabaseSqlCmdVariable: Der Wert ist der Name der Variablen, die verwendet wird, um auf die Datenbank zu verweisen.
    • Verweiseinstellung: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
    • Verwendungsbeispiel: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
  • ServerSqlCmdVariable: Der Wert ist der Name der Variablen, die verwendet wird, um auf den Server zu verweisen, auf dem sich die Datenbank befindet. Wird mit DatabaseSqlCmdVariable verwendet, wenn sich die Datenbank auf einem anderen Server befindet.
    • Verweiseinstellung: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
    • Verwendungsbeispiel: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
  • DatabaseVariableLiteralValue: Der Wert ist der literale Name der Datenbank, wie er im SQL-Projekt verwendet wird, ähnlich wie DatabaseSqlCmdVariable, aber der Verweis auf eine andere Datenbank ist ein literaler Wert.
    • Verweiseinstellung: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
    • Verwendungsbeispiel: SELECT * FROM [SomeOtherDatabase].dbo.Table1

In einer SQL-Projektdatei wird ein Datenbankverweis als ArtifactReference-Element angegeben, wobei das Include-Attribut auf den Pfad der .dacpac-Datei festgelegt ist.

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

Paketverweise

Paketverweise werden verwendet, um auf NuGet-Pakete zu verweisen, die eine .dacpac-Datei enthalten, und werden verwendet, um das Datenbankmodell zur Buildzeit ähnlich wie ein Datenbankverweis zu erweitern.

Das folgende Beispiel aus einer SQL-Projektdatei verweist auf das Microsoft.SqlServer.DacpacsPaket für die master-Datenbank.

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

Zusätzlich zu den für Datenbankverweise verfügbaren Attributen kann das folgende DacpacName-Attribut angegeben werden, um eine .dacpac-Datei aus einem Paket auszuwählen, das mehrere .dacpac-Dateien enthält.

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

SqlCmd-Variablen

SqlCmd-Variablen können in der .sqlproj-Datei definiert werden und werden verwendet, um Token in SQL-Objekten und -Skripts während der .dacpacBereitstellung zu ersetzen. Im folgenden Beispiel aus einer SQL-Projektdatei wird eine Variable namens EnvironmentName definiert, die für die Verwendung in den Objekten und Skripts des Projekts verfügbar ist.

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

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

Wenn ein kompiliertes SQL-Projekt (.dacpac) bereitgestellt wird, wird der Wert der Variablen durch den im Bereitstellungsbefehl angegebenen Wert ersetzt. Der folgende Befehl stellt z. B. AdventureWorks.dacpac bereit und legt den Wert der EnvironmentName-Variablen auf production fest.

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

Skripts vor oder nach der Bereitstellung

Skripts vor oder nach der Bereitstellung sind SQL-Skripts, die im Projekt enthalten sind und während der Bereitstellung ausgeführt werden sollen. Skripts vor oder nach der Bereitstellung sind in der .dacpac-Datei enthalten, aber sie werden nicht in das Datenbankobjektmodell kompiliert oder mit diesem überprüft. Ein Skript vor der Bereitstellung wird ausgeführt, bevor das Datenbankmodell angewendet wird, ein Skript nach der Bereitstellung, nachdem das Datenbankmodell angewendet wurde. Im folgenden Beispiel aus einer SQL-Projektdatei wird die populate-app-settings.sql-Datei als Skript nach der Bereitstellung hinzugefügt.

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

Nächste Schritte