Panoramica dei riferimenti al database

Si applica a:SQL Serverdatabase SQL di AzureAzure SQL Istanza gestitaDatabase 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 in SQL Server, usare i riferimenti al database per collegarsi a un altro database nello stesso server per i nomi in tre parti oppure a un database diverso su un server diverso per le query tra database. Per i database con un numero elevato di oggetti in gruppi distinti, 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.

Esempio e sintassi del file di progetto SQL

Includere riferimenti di database in un progetto tramite voci nel .sqlproj file, simili ai progetti C#. Usare la sintassi SQLCMD per fare riferimento al nome del database negli oggetti di progetto SQL. Quando un riferimento al database punta a un database diverso nello stesso server, includere un <DatabaseSqlCmdVariable> elemento nel riferimento al progetto. Quando un riferimento al database punta a un database diverso in un server diverso, includere anche un <ServerSqlCmdVariable> elemento nel riferimento al progetto. I riferimenti allo stesso database non includono gli elementi <ServerSqlCmdVariable> o <DatabaseSqlCmdVariable>.

Per includere un riferimento specifico al riferimento al database negli script SQL, usare 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];

Il file di progetto include un riferimento al database corrispondente alla $(Warehouse) variabile SQLCMD e contiene <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>.

Denominazione a tre parti nello stesso database

Quando un oggetto in un progetto SQL fa riferimento a un altro oggetto nello stesso database, la denominazione in tre parti non è necessaria anche se gli oggetti vengono inclusi tramite un riferimento al database. Tuttavia, i progetti SQL incorporano una variabile SQLCMD automatica per il nome del database, che è possibile usare negli script SQL per fare riferimento al database del progetto senza impostare come hardcoding il nome. Se è necessaria la denominazione in tre parti, usare $(DatabaseName) negli script SQL per fare riferimento al database. Ad esempio, lo script SQL seguente fa riferimento a una tabella nel database del progetto:

UPDATE [$(DatabaseName)].[SalesLT].[Customer]
SET [SalesPerson] = 'John Doe',
    [ModifiedDate] = GETDATE()
WHERE [CustomerId] = @CustomerId;

Valori letterali del database

In alcuni casi, potrebbe essere necessario usare un valore letterale (non variabile) per il nome del database da un riferimento al database negli oggetti SQL. È possibile configurare il .sqlproj file per specificare un valore letterale per un nome di database anziché usare una variabile SQLCMD. L'elemento utilizzato per specificare un valore letterale è <DatabaseLiteralValue>. Se si usa questo elemento, non usare l'elemento <DatabaseSqlCmdVariable> . All'interno dell'elemento <DatabaseLiteralValue> specificare il valore letterale per il nome del database. Ad esempio, un riferimento al database con <DatabaseVariableLiteralValue>WarehouseDB</DatabaseVariableLiteralValue> viene usato in uno script SQL come indicato di seguito:

SELECT ProductId,
       StorageLocation,
       BinNumber
FROM [WarehouseDB].[Production].[ProductInventory];

Riferimenti al progetto

In questo esempio si aggiunge un riferimento al progetto a un progetto SQL denominato 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

Per altre informazioni sui riferimenti ai pacchetti nei progetti SQL, vedere Riferimenti ai pacchetti SQL.

L'esempio seguente mostra un riferimento di pacchetto al master database di sistema di SQL Server 2022:

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

Riferimenti all'artefatto Dacpac

Non usare riferimenti diretti a un .dacpac file di artefatto per i nuovi progetti in stile SDK. Usare invece riferimenti al pacchetto NuGet.

Nei progetti SQL originali, è possibile specificare i riferimenti ai file .dacpac nel file .sqlproj usando 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

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

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

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

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

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

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

Compila 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 si compila un progetto in una pipeline di integrazione continua (CI), è necessario configurare l'ambiente dell'agente di compilazione 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 al progetto nel progetto SQL richiedono che il progetto a cui si fa riferimento sia presente nell'agente di compilazione con lo stesso percorso file relativo specificato nel file di progetto e che possa essere compilato correttamente nell'agente di compilazione.
• I riferimenti al database di sistema creati nei progetti SQL originali in Visual Studio richiedono l'installazione dell'agente di compilazione Visual Studio.
• 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 .dacpac file con riferimenti di database a un database diverso (nello stesso server o in un server diverso), impostare le variabili SQLCMD specificate nel file di progetto sui valori corretti per l'ambiente di destinazione. Impostare i valori delle variabili SQLCMD durante la distribuzione usando l'opzione /v nello strumento da 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

Contenuti correlati

• riferimenti ai pacchetti di progetti SQL
• Oggetti di sistema di progetti SQL
• Panoramica delle variabili SQLCMD