Panoramica dei riferimenti al database

Si applica a: SQL Server database SQL di Azure Istanza gestita di SQL di Azure database SQL in Microsoft Fabric

I riferimenti al database nei progetti SQL consentono di incorporare oggetti non inclusi in un progetto collegando un altro progetto, un file .dacpac o un pacchetto NuGet pubblicato. Gli oggetti di database aggiunti a un progetto possono far parte dello stesso database, di un database diverso nello stesso server o di un database diverso in un server diverso. Per lo sviluppo di SQL Server, è possibile usare i riferimenti al database per collegarsi a un altro database nello stesso server per la denominazione in tre parti o per collegarsi a un database diverso in un server diverso per le query tra database. Per i database con un numero elevato di oggetti in gruppi distinti, è possibile usare i riferimenti al database per suddividere un database in progetti più piccoli e gestibili. Le dimensioni del progetto più piccole consentono di migliorare le prestazioni e ridurre il tempo necessario per compilare un progetto durante lo sviluppo locale iterativo.

Nota

I riferimenti ai progetti e i riferimenti ai pacchetti NuGet sono i metodi consigliati per i riferimenti al database in un nuovo sviluppo. Il riferimento ai pacchetti NuGet non è supportato dai progetti SQL originali.

Esempio e sintassi del file di progetto SQL

I riferimenti al database sono inclusi in un progetto tramite voci nel file .sqlproj, simili ai progetti C#. Quando un riferimento al database si riferisce a un database diverso nello stesso server, un elemento <DatabaseSqlCmdVariable> viene incluso nel riferimento al progetto. Quando un riferimento al database si riferisce a un database diverso in un servr diverso, un elemento <ServerSqlCmdVariable> viene incluso anche nel riferimento al progetto. I riferimenti al database allo stesso database non includono gli elementi <ServerSqlCmdVariable> o <DatabaseSqlCmdVariable>.

L'inclusione di un riferimento specifico al riferimento al database negli script SQL usa le variabili SQLCMD denominate nel file di progetto per specificare il nome del database. Ad esempio, lo script SQL seguente fa riferimento a una tabella nel database Warehouse:

SELECT ProductId, StorageLocation, BinNumber
FROM [$(Warehouse)].[Production].[ProductInventory]

Un riferimento al database corrispondente alla variabile SQLCMD $(Warehouse) è incluso nel file di progetto e contiene <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>.

Riferimenti al progetto

In questo esempio viene aggiunto un riferimento al progetto a un progetto SQL AdventureWorksSalesLT.sqlproj che fa parte dello stesso database.

  <ItemGroup>
    <ProjectReference Include="..\AdventureWorks\AdventureWorksSalesLT.sqlproj">
      <Name>AdventureWorksSalesLT</Name>
      <Project>{d703fc7a-bc47-4aef-9dc5-cf01094ddb37}</Project>
      <Private>True</Private>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
    </ProjectReference>
  </ItemGroup>

Riferimenti al pacchetto Dacpac

Altre informazioni sui riferimenti ai pacchetti nei progetti SQL sono disponibili nell'articolo Riferimenti ai pacchetti di progetti SQL.

Un riferimento al pacchetto per il database di sistema master per SQL 2022 è illustrato nell'esempio seguente:

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs.Master" Version="160.2.1" />
  </ItemGroup>

Riferimenti all'artefatto Dacpac

I riferimenti diretti a un file di artefatto .dacpac non sono consigliati per i nuovi progetti in stile SDK. Usare invece riferimenti al pacchetto NuGet.

Nei progetti SQL originali, i riferimenti ai file .dacpac vengono specificati nel file .sqlproj con un elemento <ArtifactReference>. L'esempio seguente mostra un riferimento di artefatto .dacpac a un file .dacpac in un progetto diverso nello stesso server:

  <ItemGroup>
    <ArtifactReference Include="..\AdventureWorks\Warehouse\bin\Release\Warehouse.dacpac">
      <HintPath>..\AdventureWorks\Warehouse\bin\Release\Warehouse.dacpac</HintPath>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
      <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>
    </ArtifactReference>
  </ItemGroup>

Aggiungere e usare riferimenti al progetto

Aggiungere un riferimento al progetto

Per aggiungere un riferimento al progetto a un progetto SQL in Visual Studio, fare clic con il pulsante destro del mouse sul nodo Riferimenti nel progetto in Esplora soluzioni e selezionare Aggiungi riferimento al database.

La finestra di dialogo Aggiungi riferimento al database presenta le opzioni per l'aggiunta di un riferimento a:

• un progetto SQL dalla stessa soluzione
• un database di sistema (da file .dacpac inclusi automaticamente in Visual Studio)
• qualsiasi file dell'applicazione livello dati (.dacpac) nel file system locale

La finestra di dialogo fornisce anche un elenco a discesa da selezionare dai percorsi di riferimento seguenti:

• stesso database
• database diverso, stesso server
• database diverso, server diverso

Per aggiungere un riferimento al progetto a un progetto SQL, aggiungere un elemento <ItemGroup> al file .sqlproj con un elemento di riferimento appropriato per ogni riferimento al database. Ad esempio, il riferimento di progetto seguente viene aggiunto a un progetto SQL per fare riferimento al progetto WorldWideImporters in un database diverso in un server diverso:

  <ItemGroup>
    <ProjectReference Include="..\Contoso\WorldWideImporters.sqlproj">
      <Name>WorldWideImporters</Name>
      <Project>{d703fc7a-bc47-4aef-9dc5-cf01094ddb37}</Project>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
      <ServerSqlCmdVariable>WWIServer</ServerSqlCmdVariable>
      <DatabaseSqlCmdVariable>WorldWideImporters</DatabaseSqlCmdVariable>
    </ProjectReference>
  </ItemGroup>

Il riferimento al progetto viene usato in una definizione di vista di esempio nel progetto SQL:

CREATE VIEW dbo.WorldWide_Products
AS
SELECT ProductID, ProductName, SupplierID
FROM [$(WWIServer)].[$(WorldWideImporters)].[Purchasing].[Suppliers]

Per aggiungere un riferimento al database a un progetto SQL nell'estensione progetti database SQL, fare clic con il pulsante destro del mouse sul nodo Riferimenti database nel progetto nella vista Progetti di database e scegliere Aggiungi riferimento al database.

I tipi di riferimento disponibili sono:

• database di sistema
• applicazione livello dati (.dacpac)
• applicazione livello dati pubblicata (.nupkg)
• progetto

L'estensione richiede anche di selezionare tra i percorsi di riferimento seguenti:

• stesso database
• database diverso, stesso server
• database diverso, server diverso

Per aggiungere un riferimento al progetto a un progetto SQL, aggiungere un elemento <ItemGroup> al file .sqlproj con un elemento di riferimento appropriato per ogni riferimento al database. Ad esempio, il riferimento di progetto seguente viene aggiunto a un progetto SQL per fare riferimento al progetto WorldWideImporters in un database diverso in un server diverso:

  <ItemGroup>
    <ProjectReference Include="..\Contoso\WorldWideImporters.sqlproj">
      <Name>WorldWideImporters</Name>
      <Project>{d703fc7a-bc47-4aef-9dc5-cf01094ddb37}</Project>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
      <ServerSqlCmdVariable>WWIServer</ServerSqlCmdVariable>
      <DatabaseSqlCmdVariable>WorldWideImporters</DatabaseSqlCmdVariable>
    </ProjectReference>
  </ItemGroup>

Il riferimento al progetto viene usato in una definizione di vista di esempio nel progetto SQL:

CREATE VIEW dbo.WorldWide_Products
AS
SELECT ProductID, ProductName, SupplierID
FROM [$(WWIServer)].[$(WorldWideImporters)].[Purchasing].[Suppliers]

Compilazione con riferimenti al progetto

La compilazione di un progetto SQL con riferimenti al database potrebbe richiedere una configurazione aggiuntiva per assicurarsi che gli oggetti a cui si fa riferimento siano disponibili durante il processo di compilazione. Ad esempio, se un progetto viene compilato in una pipeline di integrazione continua (CI), l'ambiente dell'agente di compilazione deve essere configurato in modo analogo all'ambiente di sviluppo locale.

• I riferimenti .dacpac nel progetto SQL richiedono che l'oggetto .dacpac sia presente nell'agente di compilazione nello stesso percorso di file relativo specificato nel file di progetto.
• I riferimenti di progetto nel progetto SQL richiedono che il progetto a cui si fa riferimento sia presente nell'agente di compilazione nello stesso percorso di file relativo specificato nel file di progetto e che sia in grado di eseguire correttamente la compilazione nell'agente di compilazione.
• I riferimenti al database di sistema creati nei progetti SQL originali in Visual Studio richiedono l'installazione di Visual Studio per l'agente di compilazione.
• I riferimenti al pacchetto NuGet nel progetto SQL richiedono che il pacchetto venga pubblicato in un feed NuGet impostato anche come origine del pacchetto per l'agente di compilazione.

Pubblicare con riferimenti al progetto

La pubblicazione di un oggetto compilato .dacpac da un progetto con riferimenti al database non richiede passaggi aggiuntivi. Il file .dacpac contiene gli oggetti a cui si fa riferimento e le variabili SQLCMD specificate nel file di progetto.

Per i riferimenti di database agli oggetti nello stesso database, gli oggetti del progetto a cui si fa riferimento sono inclusi nel file .dacpac, ma non sono inclusi nella distribuzione per impostazione predefinita. Per includere gli oggetti nella distribuzione, usare l'opzione /p:IncludeCompositeObjects=true nello strumento riga di comando SqlPackage. Ad esempio, il comando seguente distribuisce il progetto AdventureWorks con l'opzione /p:IncludeCompositeObjects=true per includere gli oggetti dai riferimenti di database a AdventureWorks:

sqlpackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /p:IncludeCompositeObjects=true

Quando si distribuisce un file .dacpac con riferimenti di database a database diversi (nello stesso server o in un server diverso), le variabili SQLCMD specificate nel file di progetto devono essere impostate sui valori corretti per l'ambiente di destinazione. L'impostazione dei valori delle variabili SQLCMD durante la distribuzione viene eseguita con l'opzione /v nello strumento riga di comando SqlPackage. Ad esempio, il comando seguente imposta la variabile WorldWideImporters su WorldWideImporters e la variabile WWIServer su localhost:

sqlpackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /v:WorldWideImporters=WorldWideImporters /v:WWIServer=localhost

Contenuto correlato

• Panoramica dei riferimenti ai pacchetti di progetti SQL
• Panoramica delle variabili SQLCMD