Utilizzo delle variabili a livello di programmazioneWorking with Variables Programmatically

Le variabili consentono di impostare valori in modo dinamico e di controllare i processi in pacchetti, contenitori, attività e gestori eventi.Variables are a way to dynamically set values and control processes in packages, containers, tasks, and event handlers. Possono inoltre essere utilizzate dai vincoli di precedenza per controllare la direzione del flusso di dati verso attività diverse.Variables can also be used by precedence constraints to control the direction of the flow of data to different tasks. Le variabili possono essere utilizzate per effettuare le operazioni seguenti:Variables have a variety of uses:

AmbitoScope

Ogni contenitore dispone di una propria raccolta Variables.Each container has its own Variables collection. Ogni nuova variabile creata si trova nell'ambito del relativo contenitore padre.When a new variable is created, it is within the scope of its parent container. 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.Because the package container is at the top of the container hierarchy, variables with package scope function like global variables, and are visible to all containers within the package. 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.The collection of variables for the container can also be accessed by the children of the container through the Variables collection, by using either the variable name or the variable's index in the collection.

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.Because the visibility of a variable is scoped from the top down, variables declared at the package level are visible to all the containers in the package. Pertanto, la raccolta Variables in un contenitore include tutte le variabili che appartengono al relativo oggetto padre in aggiunta alle proprie variabili.Therefore, the Variables collection on a container includes all the variables that belong to its parent in addition to its own variables

Viceversa, le variabili contenute in un'attività sono limitate in termini di ambito e visibilità e sono visibili solo all'attività.Conversely, the variables that are contained in a task are limited in scope and visibility, and are only visible to the task.

Se un pacchetto esegue altri pacchetti, le variabili definite nell'ambito del pacchetto chiamante sono disponibili per il pacchetto chiamato.If a package runs other packages, the variables defined in the scope of the calling package are available to the called package. L'unica eccezione si verifica quando nel pacchetto chiamato esiste una variabile con lo stesso nome.The only exception occurs when a same-named variable exists in the called package. Quando si verifica questa collisione, il valore della variabile nel pacchetto chiamato sostituisce il valore del pacchetto chiamante.When this collision occurs, the variable value in the called package overrides the value from the calling package. Le variabili definite nell'ambito del pacchetto chiamato non sono mai nuovamente disponibili per il pacchetto chiamante.Variables defined in the scope of the called package are never available back to the calling package.

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.The following code example programmatically creates a variable, myCustomVar, at the package scope, and then iterates through all the variables visible to the package, printing their name, data type, and value.

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:Sample 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 con ambite nel sistema dello spazio dei nomi sono disponibili per il pacchetto.Notice that all the variables scoped in the System namespace are available to the package. Per altre informazioni, vedere Variabili di sistema.For more information, see System Variables.

Spazi dei nomiNamespaces

MicrosoftMicrosoft SQL ServerSQL Server Integration ServicesIntegration Services ( SSISSSIS) offre due spazi dei nomi predefinito in cui risiedono le variabili; Utente e sistema gli spazi dei nomi. SQL ServerSQL Server Integration ServicesIntegration Services ( SSISSSIS) provides two default namespaces where variables reside; User and System namespaces. Per impostazione predefinita, qualsiasi variabile personalizzata creata dallo sviluppatore viene aggiunta la utente dello spazio dei nomi.By default, any custom variable created by the developer is added to the User namespace. Le variabili di sistema si trovano nel sistema dello spazio dei nomi.System variables reside in the System namespace. È possibile creare ulteriori spazi dei nomi diverso dal utente dello spazio dei nomi per contenere le variabili personalizzate ed è possibile modificare il nome del utente dello spazio dei nomi, ma è possibile aggiungere o modificare le variabili nel sistema dello spazio dei nomi, o assegnare variabili di sistema a uno spazio dei nomi diversi.You can create additional namespaces other than the User namespace to hold custom variables, and you can change the name of the User namespace, but you cannot add or modify variables in the System namespace, or assign system variables to a different namespace.

Le variabili di sistema disponibili variano a seconda del tipo di contenitore.The system variables that are available differ depending on the container type. Per un elenco delle variabili di sistema disponibili per pacchetti, contenitori, attività e gestori eventi, vedere le variabili di sistema.For a list of the system variables available to packages, containers, tasks, and event handlers, see System Variables.

ValoreValue

Il valore di una variabile personalizzata può essere un valore letterale o un'espressione:The value of a custom variable can be a literal or an expression:

  • Se si desidera che la variabile contenga un valore letterale, impostare il valore della relativa proprietà Value.If you want the variable to contain a literal value, set the value of its Value property.

  • Se si desidera che la variabile contenga un'espressione, in modo che è possibile utilizzare i risultati dell'espressione come valore, impostare il EvaluateAsExpression proprietà della variabile da truee specificare un'espressione nella Expression proprietà.If you want the variable to contain an expression, so that you can use the results of the expression as its value, set the EvaluateAsExpression property of the variable to true, and provide an expression in the Expression property. In fase di esecuzione l'espressione verrà valutata e il relativo risultato verrà utilizzato come valore della variabile.At run time, the expression is evaluated, and the result of the expression is used as the value of the variable. Se ad esempio la proprietà Expression di una variabile è "100 * 2""100 * 2", la variabile restituirà il valore 200.For example, if the expression property of a variable is "100 * 2""100 * 2", the variable evaluates to a value of 200.

    Non è possibile impostare in modo esplicito il valore DataType di una variabile.For a variable, you cannot explicitly set the value of its DataType. Il valore DataType è derivato dal valore iniziale assegnato alla variabile e non può essere modificato in seguito.The DataType value is inferred from the initial value assigned to the variable, and cannot be changed afterward. Per ulteriori informazioni sui tipi di dati della variabile, vedere tipi di dati di Integration Services.For more information about variable data types, see Integration Services Data Types.

    Esempio di codice seguente crea un nuovo set di variabili, EvaluateAsExpression a true, assegna l'espressione "100 * 2" per la proprietà expression della variabile, quindi restituisce il valore della variabile.The following code example creates a new variable, sets EvaluateAsExpression to true, assigns the expression "100 * 2" to the expression property of the variable, and then outputs the value of the variable.

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:Sample Output:

Expression for myVar: 100 * 2

Value of myVar: 200

È necessario utilizzare un'espressione valida che utilizza la sintassi delle espressioni di SSISSSIS.The expression must be a valid expression that uses the SSISSSIS expression syntax. 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.Literals are permitted in variable expressions, in addition to the operators and functions that the expression syntax provides, but expressions cannot reference other variables or columns. Per altre informazioni, vedere Espressioni di Integration Services (SSIS).For more information, see Integration Services (SSIS) Expressions.

File di configurazioneConfiguration Files

Se un file di configurazione include una variabile personalizzata, la variabile può essere aggiornata in fase di esecuzione.If a configuration file includes a custom variable, the variable can be updated at run time. 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.What this means is that when the package runs, the value of the variable originally in the package is replaced with a new value from the configuration file. Questa tecnica di sostituzione risulta utile quando un pacchetto viene distribuito in più server che richiedono valori di variabili diversi.This replacement technique is useful when a package is deployed to multiple servers that require different variable values. Ad esempio, una variabile può specificare il numero di volte in cui un ciclo Foreach contenitore ripete il flusso di lavoro o elenco destinatari che un gestore eventi invia messaggi di posta elettronica quando viene generato un errore oppure modificare il numero di errori che possono verificarsi prima che il pacchetto ha esito negativo.For example, a variable can specify the number of times a Foreach Loop container repeats its workflow, or list the recipients that an event handler sends e-mail to when an error is raised, or change the number of errors that can occur before the package fails. Queste variabili vengono fornite dinamicamente nei file di configurazione per ogni ambiente.These variables are dynamically provided in configuration files for each environment. Pertanto, nei file di configurazione sono consentite solo variabili di lettura/scrittura.Therefore, only variables that are read/write are allowed in configuration files. Per altre informazioni, vedere Creazione di configurazioni dei pacchetti.For more information, see Create Package Configurations.

Vedere ancheSee Also

Integration Services ( SSIS ) Variabili Integration Services (SSIS) Variables
Utilizzare le variabili nei pacchettiUse Variables in Packages