Usare progetti SQL di tipo SDK con l'estensione Progetti di database SQL (anteprima)

2025-06-19

Importante

Azure Data Studio verrà ritirato il 28 febbraio 2026. È consigliabile usare Visual Studio Code. Per altre informazioni sulla migrazione a Visual Studio Code, vedere Che cosa accade in Azure Data Studio?

Questo articolo presenta Microsoft.Build.Sql per progetti SQL in stile SDK nell'estensione Progetti di database SQL in Azure Data Studio o Visual Studio Code. I progetti SQL in stile SDK sono particolarmente vantaggiosi per le applicazioni fornite tramite pipeline o create in ambienti multipiattaforma predefiniti. L'annuncio iniziale è disponibile in TechCommunity.

Annotazioni

Microsoft.Build.Sql è attualmente in anteprima.

Creare un progetto di database in stile SDK

È possibile creare un progetto di database in stile SDK da un progetto vuoto o da un database esistente.

Progetto vuoto

Nella vista Progetti di database selezionare il pulsante Nuovo progetto e immettere il nome di un progetto nella casella di testo di input visualizzata. Nella finestra di dialogo Seleziona cartella visualizzata scegliere una directory in cui risiedere la cartella, .sqlproj il file e altri contenuti del progetto.

Per impostazione predefinita, viene selezionata la selezione per il progetto in stile SDK (anteprima). Al termine della finestra di dialogo, il progetto vuoto viene aperto e visibile nella visualizzazione Progetti di database per la modifica.

Da un database esistente

Nella visualizzazione Progetto selezionare il pulsante Crea progetto dal database e connettersi a SQL Server. Dopo aver stabilito la connessione, selezionare un database dall'elenco dei database disponibili e impostare il nome del progetto. Selezionare una struttura di destinazione dell'estrazione.

Per impostazione predefinita, viene selezionata la selezione per il progetto in stile SDK (anteprima). Al termine della finestra di dialogo, il nuovo progetto viene aperto e contiene script SQL per il contenuto del database selezionato.

Compilare e pubblicare

Dalle interfacce di Azure Data Studio e Visual Studio Code, la compilazione e la pubblicazione di un progetto SQL in stile SDK viene completata nello stesso modo del formato di progetto SQL precedente. Per altre informazioni su questo processo, vedere Compilare e pubblicare un progetto.

Per compilare un progetto SQL in stile SDK dalla riga di comando in Windows, macOS o Linux, usare il comando seguente:

dotnet build

Il .dacpac file risultante dalla compilazione di un progetto SQL in stile SDK è compatibile con gli strumenti associati al framework dell'applicazione livello dati (.dacpac, .bacpac), inclusi SqlPackage e GitHub sql-action.

Funzionalità del progetto

Nei progetti SQL sono disponibili diverse funzionalità che possono essere specificate nel .sqlproj file che influiscono sul modello di database in fase di compilazione o distribuzione del progetto. Le sezioni seguenti descrivono alcune di queste funzionalità disponibili per i progetti Microsoft.Build.Sql.

Piattaforma di destinazione

La proprietà della piattaforma di destinazione è contenuta nel DSP tag nel .sqlproj file sotto l'elemento <PropertyGroup> . La piattaforma di destinazione viene usata durante la compilazione del progetto per convalidare il supporto per le funzionalità incluse nel progetto e viene aggiunta al .dacpac file come proprietà. Per impostazione predefinita, durante la distribuzione, la piattaforma di destinazione viene verificata sul database di destinazione per garantire la compatibilità. Se la piattaforma di destinazione non è supportata dal database di destinazione, la distribuzione ha esito negativo a meno che non venga specificata un'opzione di pubblicazione di override.

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

Le impostazioni valide per la piattaforma di destinazione sono:

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

Riferimenti al database

La convalida del modello di database in fase di compilazione può essere estesa oltre il contenuto del progetto SQL tramite riferimenti al database. I riferimenti al .sqlproj database specificati nel file possono fare riferimento a un altro progetto SQL o a un .dacpac file, che rappresenta un altro database o più componenti dello stesso database.

Per i riferimenti al database che rappresentano un altro database sono disponibili gli attributi seguenti:

DatabaseSqlCmdVariable: il valore è il nome della variabile usata per fare riferimento al database
- Impostazione di riferimento: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
- Esempio di utilizzo: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
ServerSqlCmdVariable: il valore è il nome della variabile usata per fare riferimento al server in cui risiede il database. usato con DatabaseSqlCmdVariable, quando il database si trova in un altro server.
- Impostazione di riferimento: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
- Esempio di utilizzo: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
DatabaseVariableLiteralValue: il valore è il nome letterale del database usato nel progetto SQL, simile a DatabaseSqlCmdVariable ma il riferimento ad altro database è un valore letterale
- Impostazione di riferimento: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
- Esempio di utilizzo: SELECT * FROM [SomeOtherDatabase].dbo.Table1

In un file di progetto SQL, un riferimento al database viene specificato come ArtifactReference elemento con l'attributo Include impostato sul percorso del .dacpac file.

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

Riferimenti ai pacchetti

I riferimenti ai pacchetti vengono usati per fare riferimento a pacchetti NuGet che contengono un .dacpac file e vengono usati per estendere il modello di database in fase di compilazione in modo analogo a un riferimento al database.

L'esempio seguente da un file di progetto SQL fa riferimento al Microsoft.SqlServer.Dacpacspacchetto per il master database.

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

Oltre agli attributi disponibili per i riferimenti al database, è possibile specificare l'attributo seguente DacpacName per selezionare un .dacpac oggetto da un pacchetto che contiene più .dacpac file.

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

Variabili SqlCmd

Le variabili SqlCmd possono essere definite nel .sqlproj file e vengono usate per sostituire i token negli oggetti e negli script SQL durante .dacpacla distribuzione. L'esempio seguente di un file di progetto SQL definisce una variabile denominata EnvironmentName disponibile per l'uso negli oggetti e negli script del progetto.

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

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

Quando viene distribuito un progetto SQL compilato (.dacpac), il valore della variabile viene sostituito con il valore specificato nel comando di distribuzione. Ad esempio, il comando seguente distribuisce AdventureWorks.dacpac e imposta il valore della EnvironmentName variabile su production.

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

Script pre/post-implementazione

Gli script pre-distribuzione e post-distribuzione sono script SQL inclusi nel progetto da eseguire durante la distribuzione. Gli script di pre-distribuzione vengono inclusi in .dacpac ma non vengono compilati o convalidati con il modello a oggetti del database. Uno script di pre-distribuzione viene eseguito prima dell'applicazione del modello di database e dopo l'applicazione del modello di database viene eseguito uno script di post-distribuzione. L'esempio seguente da un file di progetto SQL aggiunge il file populate-app-settings.sql come script post-distribuzione.

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

Condividi tramite