Używanie projektów SQL w stylu zestawu SDK z rozszerzeniem Sql Database Projects (wersja zapoznawcza)

W tym artykule przedstawiono projekty SQL typu Microsoft.Build.Sql dla zestawów SDK w rozszerzeniu SQL Database Projects w narzędziu Azure Data Studio lub Visual Studio Code. Projekty SQL w stylu zestawu SDK są szczególnie korzystne dla aplikacji dostarczanych za pośrednictwem potoków lub wbudowanych środowisk międzyplatformowych. Wstępne ogłoszenie jest dostępne w TechCommunity.

Uwaga

Microsoft.Build.Sql jest obecnie w wersji zapoznawczej.

Tworzenie projektu bazy danych w stylu zestawu SDK

Projekt bazy danych w stylu zestawu SDK można utworzyć z pustego projektu lub z istniejącej bazy danych.

Pusty projekt

W widoku Projekty bazy danych wybierz przycisk Nowy projekt i wprowadź nazwę projektu w wyświetlonym tekście. W wyświetlonym oknie dialogowym Wybieranie folderu wybierz katalog folderu, .sqlproj pliku i innej zawartości projektu, w którym ma się znajdować.

Domyślnie zaznaczony jest wybór projektu w stylu zestawu SDK (wersja zapoznawcza). Po zakończeniu okna dialogowego pusty projekt zostanie otwarty i widoczny w widoku Projekty bazy danych do edycji.

Z istniejącej bazy danych

W widoku Projekt wybierz przycisk Utwórz projekt z bazy danych i połącz się z programem SQL Server. Po nawiązaniu połączenia wybierz bazę danych z listy dostępnych baz danych i ustaw nazwę projektu. Wybierz strukturę docelową wyodrębniania.

Domyślnie zaznaczony jest wybór projektu w stylu zestawu SDK (wersja zapoznawcza). Po zakończeniu okna dialogowego zostanie otwarty nowy projekt i zawiera skrypty SQL dla zawartości wybranej bazy danych.

Kompilowanie i publikowanie

Z poziomu interfejsów azure Data Studio i Visual Studio Code kompilowanie i publikowanie projektu SQL w stylu zestawu SDK jest wykonywane w taki sam sposób, jak w przypadku poprzedniego formatu projektu SQL. Aby uzyskać więcej informacji na temat tego procesu, zobacz Kompilowanie i publikowanie projektu.

Aby utworzyć projekt SQL w stylu zestawu SDK z poziomu wiersza polecenia w systemie Windows, macOS lub Linux, użyj następującego polecenia:

dotnet build

.dacpac Plik wynikający z utworzenia projektu SQL w stylu zestawu SDK jest zgodny z narzędziami skojarzonymi z strukturą aplikacji warstwy danych (.dacpac, .bacpac), w tym sqlPackage i GitHub sql-action.

Możliwości projektu

W projektach SQL istnieje kilka możliwości, które można określić w .sqlproj pliku, które wpływają na model bazy danych w kompilacji lub wdrożeniu projektu. W poniższych sekcjach opisano niektóre z tych możliwości, które są dostępne dla projektów Microsoft.Build.Sql.

Platforma docelowa

Właściwość platformy docelowej jest zawarta w tagu DSP .sqlproj w pliku w elemencie <PropertyGroup> . Platforma docelowa jest używana podczas kompilacji projektu, aby zweryfikować obsługę funkcji zawartych w projekcie i jest dodawana do .dacpac pliku jako właściwość. Domyślnie podczas wdrażania platforma docelowa jest sprawdzana względem docelowej bazy danych w celu zapewnienia zgodności. Jeśli platforma docelowa nie jest obsługiwana przez docelową bazę danych, wdrożenie zakończy się niepowodzeniem, chyba że zostanie określona opcja zastąpienia publikowania.

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

Prawidłowe ustawienia platformy docelowej to:

• 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

Odwołania do bazy danych

Walidacja modelu bazy danych w czasie kompilacji może zostać rozszerzona o zawartość projektu SQL za pomocą odwołań do bazy danych. Odwołania do bazy danych określone w .sqlproj pliku mogą odwoływać się do innego projektu SQL lub .dacpac pliku reprezentującego inną bazę danych lub więcej składników tej samej bazy danych.

Następujące atrybuty są dostępne dla odwołań do bazy danych, które reprezentują inną bazę danych:

• DatabaseSqlCmdVariable: wartość jest nazwą zmiennej używanej do odwołowania się do bazy danych
  • Ustawienie odwołania: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
  • Przykład użycia: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
• ServerSqlCmdVariable: wartość jest nazwą zmiennej używanej do odwołowania się do serwera, na którym znajduje się baza danych. używany z databaseSqlCmdVariable, gdy baza danych znajduje się na innym serwerze.
  • Ustawienie odwołania: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
  • Przykład użycia: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
• DatabaseVariableLiteralValue: wartość jest nazwą literału bazy danych używaną w projekcie SQL, podobnie jak DatabaseSqlCmdVariable w przypadku, gdy odwołanie do innej bazy danych jest wartością literału
  • Ustawienie odwołania: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
  • Przykład użycia: SELECT * FROM [SomeOtherDatabase].dbo.Table1

W pliku projektu SQL odwołanie do bazy danych jest określane jako ArtifactReference element z atrybutem Include ustawionym na ścieżkę .dacpac pliku.

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

Odwołania do pakietu

Odwołania do pakietów służą do odwołowania się do pakietów NuGet zawierających .dacpac plik i są używane do rozszerzania modelu bazy danych w czasie kompilacji podobnie jak odwołanie do bazy danych.

Poniższy przykład z pliku projektu SQL odwołuje się do Microsoft.SqlServer.Dacpacs pakietu bazy master danych.

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

Oprócz atrybutów dostępnych dla odwołań do bazy danych można określić następujący DacpacName atrybut, aby wybrać z .dacpac pakietu zawierającego wiele .dacpacplików.

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

Zmienne SqlCmd

Zmienne SqlCmd można zdefiniować w .sqlproj pliku i są używane do zastępowania tokenów w obiektach SQL i skryptach podczas .dacpac wdrażania. Poniższy przykład z pliku projektu SQL definiuje zmienną o nazwie EnvironmentName , która jest dostępna do użycia w obiektach i skryptach projektu.

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

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

Po wdrożeniu skompilowanego projektu SQL (.dacpac) wartość zmiennej jest zastępowana wartością określoną w poleceniu wdrożenia. Na przykład następujące polecenie wdraża AdventureWorks.dacpac element i ustawia wartość zmiennej EnvironmentName na production.

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

Skrypty przed/po wdrożeniu

Skrypty przed wdrożeniem i po wdrożeniu to skrypty SQL zawarte w projekcie, które mają być wykonywane podczas wdrażania. Skrypty przed/po wdrożeniu są uwzględniane w elemecie .dacpac , ale nie są kompilowane ani weryfikowane za pomocą modelu obiektów bazy danych. Skrypt przed wdrożeniem jest wykonywany przed zastosowaniem modelu bazy danych, a skrypt po wdrożeniu jest wykonywany po zastosowaniu modelu bazy danych. Poniższy przykład z pliku projektu SQL dodaje plik populate-app-settings.sql jako skrypt po wdrożeniu.

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

Następne kroki

• Kompilowanie i publikowanie projektu za pomocą rozszerzenia SQL Database Projects
• Instalowanie pakietu SqlPackage na potrzeby wdrażania z poziomu interfejsu wiersza polecenia
• Uzyskiwanie pomocy dotyczącej rozszerzenia projektów usługi SQL Database
• Uzyskiwanie pomocy dotyczącej projektów SQL i narzędzia DacFx