Utilizzo delle variabili a livello di programmazione

  • Articolo

Si applica a:SQL Server Integration Runtime SSIS in Azure Data Factory

Le variabili consentono di impostare valori in modo dinamico e di controllare i processi in pacchetti, contenitori, attività e gestori eventi. Possono inoltre essere utilizzate dai vincoli di precedenza per controllare la direzione del flusso di dati verso attività diverse. Le variabili possono essere utilizzate per effettuare le operazioni seguenti:

Scope

Ogni contenitore dispone di una propria raccolta Variables. Ogni nuova variabile creata si trova nell'ambito del relativo contenitore padre. Poiché il contenitore del pacchetto costituisce il livello principale della gerarchia dei contenitori, le variabili con ambito pacchetto sono variabili globali e sono visibili a tutti i contenitori del pacchetto. Alla raccolta di variabili per il contenitore possono accedere anche gli elementi figlio del contenitore tramite la raccolta Variables, utilizzando il nome della variabile o il relativo indice nella raccolta.

Poiché la visibilità di una variabile ha un ambito dall'alto in basso, le variabili dichiarate a livello di pacchetto sono visibili a tutti i contenitori nel pacchetto. Pertanto, la raccolta Variables in un contenitore include tutte le variabili che appartengono al relativo oggetto padre in aggiunta alle proprie variabili.

Viceversa, le variabili contenute in un'attività sono limitate in termini di ambito e visibilità e sono visibili solo all'attività.

Se un pacchetto esegue altri pacchetti, le variabili definite nell'ambito del pacchetto chiamante sono disponibili per il pacchetto chiamato. L'unica eccezione si verifica quando nel pacchetto chiamato esiste una variabile con lo stesso nome. Quando si verifica questa collisione, il valore della variabile nel pacchetto chiamato sostituisce il valore del pacchetto chiamante. Le variabili definite nell'ambito del pacchetto chiamato non sono mai nuovamente disponibili per il pacchetto chiamante.

Nell'esempio di codice seguente viene creata una variabile a livello di programmazione, myCustomVar, nell'ambito del pacchetto, quindi vengono scorse tutte le variabili visibili al pacchetto e ne vengono stampati il nome, il tipo di dati e il valore.

using System;  
using Microsoft.SqlServer.Dts.Runtime;  
  
namespace Microsoft.SqlServer.Dts.Samples  
{  
  class Program  
  {  
    static void Main(string[] args)  
    {  
      Application app = new Application();  
      // Load a sample package that contains a variable that sets the file name.  
      Package pkg = app.LoadPackage(  
        @"C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services" +  
        @"\Package Samples\CaptureDataLineage Sample\CaptureDataLineage\CaptureDataLineage.dtsx",  
        null);  
      Variables pkgVars = pkg.Variables;  
      Variable myVar = pkg.Variables.Add("myCustomVar", false, "User", "3");  
      foreach (Variable pkgVar in pkgVars)  
      {  
        Console.WriteLine("Variable: {0}, {1}, {2}", pkgVar.Name,  
          pkgVar.DataType, pkgVar.Value.ToString());  
      }  
      Console.Read();  
    }  
  }  
}  

Imports Microsoft.SqlServer.Dts.Runtime  
  
Module Module1  
  
  Sub Main()  
  
    Dim app As Application = New Application()  
    ' Load a sample package that contains a variable that sets the file name.  
    Dim pkg As Package = app.LoadPackage( _  
      "C:\Program Files\Microsoft SQL Server\100\Samples\Integration Services" & _  
      "\Package Samples\CaptureDataLineage Sample\CaptureDataLineage\CaptureDataLineage.dtsx", _  
      Nothing)  
    Dim pkgVars As Variables = pkg.Variables  
    Dim myVar As Variable = pkg.Variables.Add("myCustomVar", False, "User", "3")  
    Dim pkgVar As Variable  
    For Each pkgVar In pkgVars  
      Console.WriteLine("Variable: {0}, {1}, {2}", pkgVar.Name, _  
        pkgVar.DataType, pkgVar.Value.ToString())  
    Next  
    Console.Read()  
  
  End Sub  
  
End Module

Esempio di output

Variable: CancelEvent, Int32, 0

Variable: CreationDate, DateTime, 4/18/2003 11:57:00 AM

Variable: CreatorComputerName, String,

Variable: CreatorName, String,

Variable: ExecutionInstanceGUID, String, {237AB5A4-7E59-4FC9-8D61-E8F20363DF25}

Variable: FileName, String, Junk

Variable: InteractiveMode, Boolean, False

Variable: LocaleID, Int32, 1033

Variable: MachineName, String, MYCOMPUTERNAME

Variable: myCustomVar, String, 3

Variable: OfflineMode, Boolean, False

Variable: PackageID, String, {F0D2E396-A6A5-42AE-9467-04CE946A810C}

Variable: PackageName, String, DTSPackage1

Variable: StartTime, DateTime, 1/28/2005 7:55:39 AM

Variable: UserName, String, <domain>\<userid>

Variable: VersionBuild, Int32, 198

Variable: VersionComments, String,

Variable: VersionGUID, String, {90E105B4-B4AF-4263-9CBD-C2050C2D6148}

Variable: VersionMajor, Int32, 1

Variable: VersionMinor, Int32, 0

Si noti che tutte le variabili che hanno come ambito lo spazio dei nomi System sono disponibili per il pacchetto. Per altre informazioni, vedere Variabili di sistema.

Spazi dei nomi

Microsoft SQL Server Integration Services (SSIS) fornisce due spazi dei nomi predefiniti in cui risiedono le variabili, ovvero gli spazi dei nomi User e System. Per impostazione predefinita, tutte le variabili personalizzate create dallo sviluppatore vengono aggiunte allo spazio dei nomi User. Le variabili di sistema risiedono nello spazio dei nomi System. È possibile creare altri spazi dei nomi diversi da User in cui includere variabili personalizzate, nonché modificare il nome dello spazio dei nomi User, ma non è possibile aggiungere o modificare variabili nello spazio dei nomi System, né assegnare variabili di sistema a uno spazio dei nomi diverso.

Le variabili di sistema disponibili variano a seconda del tipo di contenitore. Per un elenco delle variabili di sistema disponibili per pacchetti, contenitori, attività e gestori di eventi, vedere Variabili di sistema.

Valore

Il valore di una variabile personalizzata può essere un valore letterale o un'espressione:

  • Se si desidera che la variabile contenga un valore letterale, impostare il valore della relativa proprietà Value.

  • Se si vuole che la variabile contenga un'espressione, in modo che sia possibile usare i risultati dell'espressione come valore, impostare la proprietà EvaluateAsExpression della variabile su true e specificare un'espressione nella proprietà Expression. In fase di esecuzione l'espressione verrà valutata e il relativo risultato verrà utilizzato come valore della variabile. Se ad esempio la proprietà Expression di una variabile è "100 * 2""100 * 2", la variabile restituirà il valore 200.

Non è possibile impostare in modo esplicito il valore DataType di una variabile. Il valore DataType è derivato dal valore iniziale assegnato alla variabile e non può essere modificato in seguito. Per altre informazioni sui tipi di dati della variabile, vedere Tipi di dati di Integration Services.

Nell'esempio di codice seguente viene creata una nuova variabile, la proprietà EvaluateAsExpression viene impostata su true, viene assegnata l'espressione "100 * 2" alla proprietà Expression della variabile, quindi viene restituito il valore della variabile.

using System;  
using Microsoft.SqlServer.Dts.Runtime;  
  
namespace Microsoft.SqlServer.Dts.Samples  
{  
  class Program  
  {  
    static void Main(string[] args)  
    {  
      Package pkg = new Package();  
      Variable v100 = pkg.Variables.Add("myVar", false, "", 1);  
      v100.EvaluateAsExpression = true;  
      v100.Expression = "100 * 2";  
      Console.WriteLine("Expression for myVar: {0}",   
        v100.Properties["Expression"].GetValue(v100));  
      Console.WriteLine("Value of myVar: {0}", v100.Value.ToString());  
      Console.Read();  
    }  
  }  
}  

Imports Microsoft.SqlServer.Dts.Runtime  
  
Module Module1  
  
  Sub Main()  
  
    Dim pkg As Package = New Package  
    Dim v100 As Variable = pkg.Variables.Add("myVar", False, "", 1)  
    v100.EvaluateAsExpression = True  
    v100.Expression = "100 * 2"  
    Console.WriteLine("Expression for myVar: {0}", _  
      v100.Properties("Expression").GetValue(v100))  
    Console.WriteLine("Value of myVar: {0}", v100.Value.ToString)  
    Console.Read()  
  
  End Sub  
  
End Module

Esempio di output

Expression for myVar: 100 * 2

Value of myVar: 200

È necessario usare un'espressione valida che usa la sintassi delle espressioni di SSIS. I valori letterali sono consentiti nelle espressioni delle variabili, in aggiunta agli operatori e alle funzioni disponibili nella sintassi delle espressioni, ma le espressioni non possono fare riferimento ad altre variabili o colonne. Per altre informazioni, vedere Espressioni di Integration Services (SSIS).

File di configurazione

Se un file di configurazione include una variabile personalizzata, la variabile può essere aggiornata in fase di esecuzione. Questo significa che quando il pacchetto viene eseguito, il valore della variabile che si trovava originariamente nel pacchetto viene sostituito con un nuovo valore del file di configurazione. Questa tecnica di sostituzione risulta utile quando un pacchetto viene distribuito in più server che richiedono valori di variabili diversi. Ad esempio, una variabile può specificare il numero di volte in cui un contenitore Ciclo Foreach ripete il flusso di lavoro o elencare i destinatari a cui un gestore di eventi invia un messaggio di posta elettronica quando viene generato un errore oppure modificare il numero di errori che possono verificarsi prima che l'esecuzione del pacchetto abbia esito negativo. Queste variabili vengono fornite dinamicamente nei file di configurazione per ogni ambiente. Pertanto, nei file di configurazione sono consentite solo variabili di lettura/scrittura. Per altre informazioni, vedere Creazione di configurazioni dei pacchetti.

Vedere anche

Variabili di Integration Services (SSIS)
Uso di variabili nei pacchetti