SQL-projecten in SDK-stijl gebruiken met de extensie SQL Database Projects (preview)

Artikel
02/06/2025

Belangrijk

Azure Data Studio wordt op 28 februari 2026buiten gebruik gesteld. U wordt aangeraden Visual Studio Codete gebruiken. Ga naar Wat gebeurt er met Azure Data Studio voor meer informatie over migreren naar Visual Studio Code?

In dit artikel maakt u kennis met MICROSOFT.Build.Sql voor SQL-projecten in de SQL Database Projects-extensie in Azure Data Studio of Visual Studio Code. SQL-projecten in SDK-stijl zijn met name voordelig voor toepassingen die worden verzonden via pijplijnen of ingebouwde platformoverschrijdende omgevingen. De eerste aankondiging is beschikbaar in TechCommunity.

Notitie

Microsoft.Build.Sql is momenteel beschikbaar als preview-versie.

Een SDK-databaseproject maken

U kunt een SDK-databaseproject maken op basis van een leeg project of van een bestaande database.

Leeg project

Selecteer in de weergave Databaseprojecten de knop Nieuw project en voer een projectnaam in de tekstinvoer in die wordt weergegeven. Kies in het dialoogvenster Een map selecteren dat wordt weergegeven een map voor de map, .sqlproj het bestand en andere inhoud van het project waarin u zich wilt bevinden.

Standaard is de selectie voor het project in SDK-stijl (preview) ingeschakeld. Wanneer het dialoogvenster is voltooid, wordt het lege project geopend en zichtbaar in de weergave Databaseprojecten voor bewerking.

Vanuit een bestaande database

Selecteer in de projectweergave de knop Project maken vanuit database en maak verbinding met een SQL Server. Zodra de verbinding tot stand is gebracht, selecteert u een database in de lijst met beschikbare databases en stelt u de naam van het project in. Selecteer een doelstructuur van de extractie.

Standaard is de selectie voor het project in SDK-stijl (preview) ingeschakeld. Wanneer het dialoogvenster is voltooid, wordt het nieuwe project geopend en bevat het SQL-scripts voor de inhoud van de geselecteerde database.

Bouwen en publiceren

Vanuit de Interfaces van Azure Data Studio en Visual Studio Code wordt het bouwen en publiceren van een SQL-project in SDK-stijl op dezelfde manier voltooid als de vorige SQL-projectindeling. Zie Een project bouwen en publiceren voor meer informatie over dit proces.

Gebruik de volgende opdracht om een SQL-project in SDK-stijl te bouwen vanaf de opdrachtregel in Windows, macOS of Linux:

dotnet build

Het .dacpac bestand dat het gevolg is van het bouwen van een SQL-project in SDK-stijl, is compatibel met hulpprogramma's die zijn gekoppeld aan het toepassingsframework voor de gegevenslaag (.dacpac, .bacpacinclusief SqlPackage en GitHub sql-action).

Projectmogelijkheden

In SQL-projecten zijn er verschillende mogelijkheden die kunnen worden opgegeven in het .sqlproj bestand dat van invloed is op het databasemodel in projectbuild of implementatie. In de volgende secties worden enkele van deze mogelijkheden beschreven die beschikbaar zijn voor Microsoft.Build.Sql-projecten.

Doelplatform

De doelplatformeigenschap bevindt zich in de DSP tag in het .sqlproj bestand onder het <PropertyGroup> item. Het doelplatform wordt gebruikt tijdens de projectbuild om ondersteuning te valideren voor functies die in het project zijn opgenomen en wordt als eigenschap aan het .dacpac bestand toegevoegd. Tijdens de implementatie wordt het doelplatform standaard gecontroleerd op basis van de doeldatabase om compatibiliteit te garanderen. Als het doelplatform niet wordt ondersteund door de doeldatabase, mislukt de implementatie, tenzij er een onderdrukkingsoptie voor publiceren is opgegeven.

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

Geldige instellingen voor het doelplatform zijn:

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

Databaseverwijzingen

De validatie van het databasemodel tijdens de build kan worden uitgebreid tot voorbij de inhoud van het SQL-project via databaseverwijzingen. Databaseverwijzingen die in het .sqlproj bestand zijn opgegeven, kunnen verwijzen naar een ander SQL-project of een .dacpac bestand, dat een andere database of meer onderdelen van dezelfde database vertegenwoordigt.

De volgende kenmerken zijn beschikbaar voor databaseverwijzingen die een andere database vertegenwoordigen:

DatabaseSqlCmdVariable: de waarde is de naam van de variabele die wordt gebruikt om te verwijzen naar de database
- Referentie-instelling: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
- Gebruiksvoorbeeld: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
ServerSqlCmdVariable: de waarde is de naam van de variabele die wordt gebruikt om te verwijzen naar de server waarin de database zich bevindt. wordt gebruikt met DatabaseSqlCmdVariable wanneer de database zich op een andere server bevindt.
- Referentie-instelling: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
- Gebruiksvoorbeeld: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
DatabaseVariableLiteralValue: de waarde is de letterlijke naam van de database die wordt gebruikt in het SQL-project, vergelijkbaar met DatabaseSqlCmdVariable maar de verwijzing naar een andere database is een letterlijke waarde
- Referentie-instelling: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
- Gebruiksvoorbeeld: SELECT * FROM [SomeOtherDatabase].dbo.Table1

In een SQL-projectbestand wordt een databasereferentie opgegeven als een ArtifactReference item met het Include kenmerk dat is ingesteld op het pad van het .dacpac bestand.

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

Pakketverwijzingen

Pakketverwijzingen worden gebruikt om te verwijzen naar NuGet-pakketten die een .dacpac bestand bevatten en worden gebruikt om het databasemodel tijdens de build op dezelfde manier uit te breiden als een databaseverwijzing.

Het volgende voorbeeld uit een SQL-projectbestand verwijst naar het Microsoft.SqlServer.Dacpacspakket voor de master database.

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

Naast de kenmerken die beschikbaar zijn voor databaseverwijzingen, kan het volgende DacpacName kenmerk worden opgegeven om een .dacpac te selecteren in een pakket dat meerdere .dacpac bestanden bevat.

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

SqlCmd-variabelen

SqlCmd-variabelen kunnen worden gedefinieerd in het .sqlproj bestand en worden gebruikt om tokens in SQL-objecten en -scripts te vervangen tijdens .dacpacde implementatie. In het volgende voorbeeld van een SQL-projectbestand wordt een variabele gedefinieerd met de naam EnvironmentName die beschikbaar is voor gebruik in de objecten en scripts van het project.

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

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

Wanneer een gecompileerd SQL-project (.dacpac) wordt geïmplementeerd, wordt de waarde van de variabele vervangen door de waarde die is opgegeven in de implementatieopdracht. Met de volgende opdracht wordt bijvoorbeeld de AdventureWorks.dacpac waarde van de EnvironmentName variabele geïmplementeerd en ingesteld op production.

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

Scripts vóór/na de implementatie

Scripts vóór en na de implementatie zijn SQL-scripts die zijn opgenomen in het project dat tijdens de implementatie moet worden uitgevoerd. Scripts vóór/na de implementatie zijn opgenomen in de .dacpac scripts, maar worden niet gecompileerd of gevalideerd met het databaseobjectmodel. Er wordt een script vóór de implementatie uitgevoerd voordat het databasemodel wordt toegepast en er wordt een script na de implementatie uitgevoerd nadat het databasemodel is toegepast. In het volgende voorbeeld uit een SQL-projectbestand wordt het bestand populate-app-settings.sql toegevoegd als script na de implementatie.

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

Delen via