Teilen über

Übersicht über Datenbankverweise

  • Artikel

Gilt für: SQL Server Azure SQL-Datenbank Azure SQL Managed Instance

Datenbankverweise in SQL-Projekten ermöglichen es Ihnen, Objekte zu integrieren, die nicht in einem Projekt enthalten sind, indem Sie eine Verknüpfung mit einem anderen Projekt, einer .dacpac-Datei oder einem veröffentlichten NuGet-Paket herstellen. Die einem Projekt hinzugefügten Datenbankobjekte können Teil derselben Datenbank, einer anderen Datenbank auf demselben Server oder einer anderen Datenbank auf einem anderen Server sein. Bei der SQL Server-Entwicklung können Datenbankverweise verwendet werden, um eine Verknüpfung mit einer anderen Datenbank auf demselben Server für dreiteilige Benennungen oder eine Verknüpfung mit einer anderen Datenbank auf einem anderen Server für datenbankübergreifende Abfragen zu erstellen. Bei Datenbanken mit einer großen Anzahl von Objekten in unterschiedlichen Gruppen können Datenbankverweise verwendet werden, um eine Datenbank in kleinere, verwaltbare Projekte aufzuteilen. Kleinere Projektgrößen können dazu beitragen, die Leistung zu verbessern und die Zeit zu verringern, die zum Erstellen eines Projekts während der iterativen lokalen Entwicklung erforderlich ist.

Screenshot eines SQL-Projekts, das auf einen dacpac-Datei, ein Nuget-Paket und ein Projekt für Datenbankverweise verweist.

Hinweis

Projektverweise und NuGet-Paketverweise sind die empfohlenen Methoden für Datenbankverweise in der neuen Entwicklung. Das Verweisen auf NuGet-Pakete wird von ursprünglichen SQL-Projekten nicht unterstützt.

SQL-Projektdateibeispiel und Syntax

Datenbankverweise werden in einem Projekt über Einträge in der .sqlproj-Datei eingeschlossen, ähnlich wie C#-Projekte. Wenn sich ein Datenbankverweis auf einer anderen Datenbank auf demselben Server bezieht, wird ein <DatabaseSqlCmdVariable>-Element in der Projektreferenz eingeschlossen. Wenn sich ein Datenbankverweis auf einer anderen Datenbank auf einen anderen Server bezieht, wird ein <ServerSqlCmdVariable>-Element auch in der Projektreferenz eingeschlossen. Datenbankverweise auf dieselbe Datenbank enthalten keine <ServerSqlCmdVariable>- oder <DatabaseSqlCmdVariable>-Elemente.

Wenn Sie einen bestimmten Verweis auf den Datenbankverweis in die SQL-Skripts einschließen, verwenden Sie SQLCMD-Variablen, die in der Projektdatei benannt sind, um den Datenbanknamen anzugeben. Das folgende SQL-Skript verweist beispielsweise auf eine Tabelle in der Warehouse-Datenbank:

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

Ein Datenbankverweis, der der $(Warehouse)-SQLCMD-Variablen entspricht, ist in der Projektdatei enthalten und enthält <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>.

Projektverweise

In diesem Beispiel wird einem SQL-Projekt AdventureWorksSalesLT.sqlproj, das Teil derselben Datenbank ist, ein Projektverweis hinzugefügt.

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

Dacpac-Paketverweise

Weitere Informationen zu Paketverweise in SQL-Projekten finden Sie im Artikel zu SQL-Projektpaketreferenzen.

Ein Paketverweis auf auf die master-Systemdatenbank für SQL 2022 wird im folgenden Beispiel gezeigt:

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

Dacpac-Artefaktverweise

Verweise auf eine .dacpac-Artefaktdatei werden für die neue Entwicklung in SDK-Formatprojekten nicht empfohlen. Verwenden Sie stattdessen NuGet-Paketverweise.

In ursprünglichen SQL-Projekten werden .dacpac-Dateiverweise in der .sqlproj-Datei mit einem <ArtifactReference>-Element angegeben. Das folgende Beispiel zeigt einen .dacpac-Artefaktverweis auf eine .dacpac-Datei in einem anderen Projekt auf demselben 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>

Hinzufügen und Verwenden von Projektverweisen

Hinzufügen eines Projektverweises

Wenn Sie einem SQL-Projekt in Visual Studio einen Projektverweis hinzufügen möchten, klicken Sie mit der rechten Maustaste auf den Knoten Verweise unter dem Projekt in Projektmappen-Explorer und wählen Sie Datenbankverweis hinzufügen aus.

Screenshot des Visual Studio-Dialogs für Datenbankverewise.

Im Datenbankreferenz hinzufügen werden Optionen zum Hinzufügen eines Verweises angezeigt:

  • ein SQL-Projekt aus derselben Lösung
  • eine Systemdatenbank (aus .dacpac-Dateien, die automatisch in Visual Studio enthalten sind)
  • beliebige Datenebenenanwendungsdatei (.dacpac) im lokalen Dateisystem

Das Dialogfeld enthält auch eine Dropdownliste, die aus den folgenden Referenzspeicherorten ausgewählt werden kann:

  • gleiche Datenbank
  • unterschiedliche Datenbank, derselbe Server
  • unterschiedliche Datenbank, unterschiedliche Server

Wenn Sie einem SQL-Projekt einen Projektverweis hinzufügen möchten, fügen Sie der .sqlproj-Datei ein <ItemGroup>-Element mit einem entsprechenden Referenzelement für jeden Datenbankverweis hinzu. Beispielsweise wird der folgende Projektverweis zu einem SQL-Projekt hinzugefügt, um auf das WorldWideImporters-Projekt in einer anderen Datenbank auf einem anderen Server zu verweisen:

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

Der Projektverweis wird in einer Beispielansichtsdefinition im SQL-Projekt verwendet:

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

Wenn Sie in der Erweiterung SQL Database Projects einen Datenbankverweis auf ein SQL-Projekt hinzufügen möchten, klicken Sie mit der rechten Maustaste auf den Knoten Datenbankverweise unter dem Projekt in der Ansicht Datenbankprojekte und wählen Sie Datenbankverweis hinzufügen aus.

Screenshot des Azure Data Studio-Dialogs zum Hinzufügen von Referenzen.

Die verfügbaren Referenztypen sind:

  • Systemdatenbank
  • Datenebenenanwendung (.dacpac)
  • Datenebenenanwendung veröffentlichen (.nupkg)
  • project

Die Erweiterung fordert außerdem auf, aus den folgenden Referenzspeicherorten auszuwählen:

  • gleiche Datenbank
  • unterschiedliche Datenbank, derselbe Server
  • unterschiedliche Datenbank, unterschiedliche Server

Wenn Sie einem SQL-Projekt einen Projektverweis hinzufügen möchten, fügen Sie der .sqlproj-Datei ein <ItemGroup>-Element mit einem entsprechenden Referenzelement für jeden Datenbankverweis hinzu. Beispielsweise wird der folgende Projektverweis zu einem SQL-Projekt hinzugefügt, um auf das WorldWideImporters-Projekt in einer anderen Datenbank auf einem anderen Server zu verweisen:

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

Der Projektverweis wird in einer Beispielansichtsdefinition im SQL-Projekt verwendet:

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

Erstellen mit Projektverweise

Das Erstellen eines SQL-Projekts mit Datenbankverweisen erfordert möglicherweise eine zusätzliche Konfiguration, um sicherzustellen, dass die referenzierten Objekte während des Build-Prozesses verfügbar sind. Wenn z. B. ein Projekt in einer CI-Pipeline (Continuous Integration) erstellt wird, muss die Build-Agent-Umgebung ähnlich wie die lokale Entwicklungsumgebung eingerichtet werden.

  • .dacpac-Verweise im SQL-Projekt erfordern, dass .dacpac im Build-Agent auf demselben relativen Dateipfad vorhanden ist, wie angegeben in der Projektdatei.
  • Projektverweise im SQL-Projekt erfordern, dass das referenzierte Projekt auf dem Build-Agent auf demselben relativen Dateipfad vorhanden sein muss, wie in der Projektdatei angegeben und erfolgreich auf dem Build-Agent erstellt werden können muss.
  • Systemdatenbankverweise, die in ursprünglichen SQL-Projekten in Visual Studio erstellt wurden, erfordern, dass der Build-Agent Visual Studio installiert hat.
  • NuGet-Paketverweise im SQL-Projekt erfordern, dass das Paket in einem NuGet-Feed veröffentlicht wird, der auch als Paketquelle für den Build-Agent festgelegt ist.

Veröffentlichen mit Projektverweisen

Für das Veröffentlichen eines .dacpac-Projekts mit Datenbankverweisen sind keine zusätzlichen Schritte erforderlich. Die .dacpac-Datei enthält die referenzierten Objekte und die in der Projektdatei angegebenen SQLCMD-Variablen.

Für Datenbankverweise auf Objekte in derselben Datenbank sind die Objekte aus dem referenzierten Projekt in der .dacpac-Datei enthalten, sind aber standardmäßig nicht in der Bereitstellung enthalten. Um die Objekte in die Bereitstellung einzuschließen, verwenden Sie die /p:IncludeCompositeObjects=true-Option im SqlPackage-Befehlszeilentool. Beispielsweise stellt der folgende Befehl das AdventureWorks-Projekt mit der /p:IncludeCompositeObjects=true-Option bereit, um Objekte aus Datenbankverweisen auf AdventureWorks einzuschließen:

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

Beim Bereitstellen einer .dacpac-Datei mit Datenbankverweisen auf unterschiedlichen Datenbanken (auf demselben oder einem anderen Server) müssen die in der Projektdatei angegebenen SQLCMD-Variablen auf die richtigen Werte für die Zielumgebung festgelegt werden. Das Festlegen der SQLCMD-Variablenwerte während der Bereitstellung erfolgt mit der /v-Option im SqlPackage-Befehlszeilentool. Zum Beispiel setzt der folgende Befehl die Variable WorldWideImporters auf WorldWideImporters und die Variable WWIServer auf localhost:

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

Zugehöriger Inhalt