Usare progetti SQL in stile SDK con l'estensione progetti di database SQL (anteprima)

Questo articolo introduce 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.

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 inserire la cartella del progetto, il file .sqlproj e altri contenuti.

Per impostazione predefinita, viene spuntata la selezione Progetto in stile SDK (anteprima). Al termine del dialogo, il progetto vuoto viene aperto e mostrato nella vista Progetti di database per la modifica.

Da un database esistente

Nella vista Progetti selezionare il pulsante Crea progetto da database e connettersi a SQL Server. Dopo che la connessione è stata stabilita, 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 spuntata la selezione Progetto in stile SDK (anteprima). Al termine del dialogo verrà aperto il nuovo progetto, che conterrà gli script SQL per i contenuti 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 allo stesso modo del formato del progetto SQL precedente. Per altre informazioni su questo processo, vedere Compilare e pubblicare un progetto.

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

dotnet build

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

Capacità dei progetti

Nei progetti SQL sono disponibili diverse funzionalità che possono essere specificate nel file .sqlproj 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 tag DSP nel file .sqlproj sotto l'articolo <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 file .dacpac 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 una sostituzione di opzione di pubblicazione.

<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 database specificati nel file .sqlproj 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 d'uso: 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 d'uso: 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 d'uso: 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 file .dacpac.

  <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 file .dacpac 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 pacchetto Microsoft.SqlServer.Dacpacs per il database master.

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

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

  <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 file .sqlproj e vengono usate per sostituire i token negli oggetti e negli script SQL durante la distribuzione .dacpac. 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-distribuzione e post-distribuzione

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 pre-distribuzione viene eseguito prima dell'applicazione del modello di database e dopo l'applicazione del modello di database viene eseguito uno script 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>

Passaggi successivi

• Compilare e pubblicare un progetto con l'estensione progetti di database SQL
• Installare SqlPackage per la distribuzione dall'interfaccia della CLI
• Richiesta supporto per l'estensione progetti di database SQL
• Richiesta supporto per i progetti SQL e DacFx