Freigeben über

Übersicht über SQLCMD-Variablen

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

SQLCMD-Variablen werden in SQL-Projekten verwendet, um dynamisch ersetzbare Token in SQL-Objekten und -Skripts zu erstellen. Die Werte dieser Variablen werden zur Bereitstellungszeit festgelegt und können verwendet werden, um Werte in einem SQL-Projekt dynamisch festzulegen. Werte für SQLCMD-Variablen können im Veröffentlichungsvorgang oder über ein Veröffentlichungsprofil festgelegt werden.

Screenshot der SQLCMD-Variablen EnvironmentName, die erst nach der Bereitstellung festgelegt ist.

SQL-Projektdateibeispiel und Syntax

SQLCMD-Variablen werden in der .sqlproj-Datei unter einem <ItemGroup>-Element definiert. In diesem Beispiel wird die Variable EnvironmentName mit einem Standardwert von testing definiert:

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

Das DefaultValue-Element ist optional. Wenn ein Standardwert bereitgestellt wird, wird er nur zum Laden im Dialogfeld „Veröffentlichen“ von grafischen Tools für SQL-Projekte verwendet. Der Standardwert wird nicht in die .dacpac-Datei kompiliert, und eine Befehlszeilenbereitstellung ohne die durch ein Veröffentlichungsprofil angegebenen Werte oder die /v-Option zum Angeben von Werten führt zu leeren Werten für die SQLCMD-Variablen.

Verwenden von SQLCMD-Variablen in SQL-Objekten

SQLCMD-Variablen können in SQL-Objekten und Skripts verwendet werden, indem sie den Variablennamen in die $(variableName)-Syntax umbrechen. Das folgende SQL-Skript verwendet beispielsweise die $(EnvironmentName)-Variable zum Steuern des Skriptverhaltens:

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

Verwenden von SQLCMD-Variablen in Veröffentlichungsvorgängen

SQLCMD-Variablen können zur Bereitstellungszeit mithilfe der /v-Option im SqlPackage-Befehlszeilentool festgelegt werden. Der folgende Befehl setzt die EnvironmentName-Variable beispielsweise auf production:

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

Hinzufügen und Verwenden von SQLCMD-Variablen

Wenn Sie einem SQLCMD-Projekt in Visual Studio eine SQLCMD-Variable hinzufügen möchten, klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Eigenschaften aus. Geben Sie auf der Registerkarte SQLCMD-Variablen des Eigenschaftenfensters den Variablennamen und optional einen Standardwert an.

Nachdem die Variable definiert wurde, kann sie in SQL-Skripts verwendet werden, indem sie den Variablennamen in die $(variableName)-Syntax umschließen.

Wenn Sie das Projekt aus Visual Studio veröffentlichen, werden SQLCMD-Variablen im Veröffentlichungsdialogfeld festgelegt. Verwenden Sie die Schaltfläche Werte laden, um die Standardwerte aus dem SQL-Projekt in den Dialog zu laden.

Wenn Sie einem SQLCMD-Projekt in Visual Studio eine SQLCMD-Variable hinzufügen möchten, klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Eigenschaften aus. Geben Sie im Abschnitt SQLCMD-Variablen des Eigenschaftenfensters den Variablennamen und optional einen Standardwert an.

Nachdem die Variable definiert wurde, kann sie in SQL-Skripts verwendet werden, indem sie den Variablennamen in die $(variableName)-Syntax umschließen.

Wenn Sie das Projekt aus Visual Studio veröffentlichen, werden SQLCMD-Variablen im Veröffentlichungsdialogfeld festgelegt. Verwenden Sie die Schaltfläche Werte laden, um die Standardwerte aus dem SQL-Projekt in den Dialog zu laden.

Wenn Sie einem SQLCMD-Projekt in der Erweiterung SQL Database Projects eine SQLCMD-Variable hinzufügen möchten, klicken Sie mit der rechten Maustaste auf den Knoten SQLCMD-Variablen" unter dem Projekt in der Anzeige Datenbankprojekte und wählen Sie SQLCMD-Variable hinzufügen aus. Geben Sie den Variablennamen und optional einen Standardwert an.

Nachdem die Variable definiert wurde, kann sie in SQL-Skripts verwendet werden, indem sie den Variablennamen in die $(variableName)-Syntax umschließen.

Wenn Sie das Projekt aus der Erweiterung SQL Database Projects veröffentlichen, werden SQLCMD-Variablenwerte automatisch aus den Standardwerten geladen. Sie können alternative Werte bereitstellen, wenn Sie aufgefordert werden, die Werte während des Veröffentlichungsprozesses zu ändern.

Wenn Sie einem SQL-Projekt eine SQLCMD-Variable hinzufügen möchten, fügen Sie der .sqlproj-Datei ein <ItemGroup>-Element mit einem <SqlCmdVariable>-Element für jede Variable hinzu. Das <SqlCmdVariable>-Element enthält den Variablennamen, einen Standardwert und einen Wert, der zur Bereitstellungszeit festgelegt werden kann.

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

Nachdem die Variable definiert wurde, kann sie in SQL-Skripts verwendet werden, indem sie den Variablennamen in die $(variableName)-Syntax umschließen.

Wenn Sie das Projekt über die Befehlszeile bereitstellen, können SQLCMD-Variablen mithilfe der /v-Option im Befehlszeilentool SqlPackage festgelegt werden.

Zum Beispiel:

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

Zugehöriger Inhalt