Använda SQL-projekt i SDK-format med SQL Database Projects-tillägget (förhandsversion)

Den här artikeln introducerar SQL-projekt i Microsoft.Build.Sql för SDK-format i SQL Database Projects-tillägget i Azure Data Studio eller Visual Studio Code. SQL-projekt i SDK-stil är särskilt fördelaktiga för program som levereras via pipelines eller inbyggda plattformsoberoende miljöer. Det första meddelandet är tillgängligt i TechCommunity.

Skapa ett SDK-liknande databasprojekt

Du kan skapa ett SDK-liknande databasprojekt från ett tomt projekt eller från en befintlig databas.

Tomt projekt

I vyn Databasprojekt väljer du knappen Nytt projekt och anger ett projektnamn i textinmatningen som visas. I dialogrutan Välj en mapp som visas väljer du en katalog för projektets mapp, .sqlproj fil och annat innehåll som ska finnas i.

Som standard är markeringen för SDK-projekt (förhandsversion) markerad. När dialogrutan är klar öppnas det tomma projektet och visas i vyn Databasprojekt för redigering.

Från en befintlig databas

I projektvyn väljer du knappen Skapa projekt från databas och ansluter till en SQL Server. När anslutningen har upprättats väljer du en databas i listan över tillgängliga databaser och anger namnet på projektet. Välj en målstruktur för extraheringen.

Som standard är markeringen för SDK-projekt (förhandsversion) markerad. När dialogrutan är klar öppnas det nya projektet och innehåller SQL-skript för innehållet i den valda databasen.

Skapa och publicera

Från Azure Data Studio- och Visual Studio Code-gränssnitten slutförs skapandet och publiceringen av ett SQL-projekt i SDK-stil på samma sätt som det tidigare SQL-projektformatet. Mer information om den här processen finns i Skapa och publicera ett projekt.

Om du vill skapa ett SQL-projekt i SDK-format från kommandoraden i Windows, macOS eller Linux använder du följande kommando:

dotnet build

Filen .dacpac som är resultatet av att skapa ett SQL-projekt i SDK-format är kompatibel med verktyg som är associerade med datanivåprogramramverket (.dacpac, .bacpac), inklusive SqlPackage och GitHub sql-action.

Projektfunktioner

I SQL-projekt finns det flera funktioner som kan anges i .sqlproj filen som påverkar databasmodellen antingen vid projektversion eller distribution. I följande avsnitt beskrivs några av de här funktionerna som är tillgängliga för Microsoft.Build.Sql-projekt.

Målplattform

Målplattformsegenskapen finns i taggen DSP .sqlproj i filen under objektet <PropertyGroup> . Målplattformen används under projektversionen för att verifiera stöd för funktioner som ingår i projektet och läggs till i .dacpac filen som en egenskap. Under distributionen kontrolleras som standard målplattformen mot måldatabasen för att säkerställa kompatibilitet. Om målplattformen inte stöds av måldatabasen misslyckas distributionen om inte ett alternativ för åsidosättningspublicering har angetts.

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

Giltiga inställningar för målplattformen är:

• 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

Databasreferenser

Verifieringen av databasmodellen vid byggtiden kan utökas förbi innehållet i SQL-projektet via databasreferenser. Databasreferenser som anges i .sqlproj filen kan referera till ett annat SQL-projekt eller en .dacpac fil som representerar antingen en annan databas eller flera komponenter i samma databas.

Följande attribut är tillgängliga för databasreferenser som representerar en annan databas:

• DatabaseSqlCmdVariable: värdet är namnet på variabeln som används för att referera till databasen
  • Referensinställning: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
  • Användningsexempel: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
• ServerSqlCmdVariable: värdet är namnet på variabeln som används för att referera till servern där databasen finns. används med DatabaseSqlCmdVariable när databasen finns på en annan server.
  • Referensinställning: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
  • Användningsexempel: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
• DatabaseVariableLiteralValue: värdet är databasens literalnamn som används i SQL-projektet, ungefär som DatabaseSqlCmdVariable men referensen till en annan databas är ett literalvärde
  • Referensinställning: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
  • Användningsexempel: SELECT * FROM [SomeOtherDatabase].dbo.Table1

I en SQL-projektfil anges en databasreferens som ett ArtifactReference objekt med Include attributet inställt på sökvägen .dacpac till filen.

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

Paketreferenser

Paketreferenser används för att referera till NuGet-paket som innehåller en .dacpac fil och används för att utöka databasmodellen vid byggtiden på samma sätt som en databasreferens.

Följande exempel från en SQL-projektfil refererar till Microsoft.SqlServer.Dacpacs paketet för master databasen.

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

Förutom de attribut som är tillgängliga för databasreferenser kan följande DacpacName attribut anges för att välja ett .dacpac från ett paket som innehåller flera .dacpac filer.

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

SqlCmd-variabler

SqlCmd-variabler kan definieras i .sqlproj filen och används för att ersätta token i SQL-objekt och skript under .dacpac distributionen. I följande exempel från en SQL-projektfil definieras en variabel med namnet EnvironmentName som är tillgänglig för användning i projektets objekt och skript.

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

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

När ett kompilerat SQL-projekt (.dacpac) distribueras ersätts värdet för variabeln med det värde som anges i distributionskommandot. Följande kommando distribuerar AdventureWorks.dacpac till exempel och anger värdet för variabeln EnvironmentName till production.

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

Skript före/efter distribution

Skript före och efter distribution är SQL-skript som ingår i projektet som ska köras under distributionen. Skript före/efter distribution ingår i .dacpac men de kompileras inte till eller verifieras med databasobjektmodellen. Ett skript före distributionen körs innan databasmodellen tillämpas och ett skript efter distributionen körs när databasmodellen har tillämpats. I följande exempel från en SQL-projektfil läggs filen populate-app-settings.sql till som skript efter distributionen.

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

Nästa steg

• Skapa och publicera ett projekt med SQL Database Projects-tillägget
• Installera SqlPackage för distribution från CLI
• Få hjälp med SQL Database Projects-tillägget
• Få hjälp med SQL-projekt och DacFx