Utilisation de variables par programme

Portée

Chaque conteneur possède sa propre collection Variables. Lorsqu'une nouvelle variable est créée, elle se trouve dans la portée de son conteneur parent. Le conteneur de packages se trouvant au sommet de la hiérarchie de conteneurs, les variables avec une portée de package fonctionnent comme les variables globales et sont visibles pour tous les conteneurs contenus dans le package. La collection de variables du conteneur est également accessible par les enfants du conteneur via la collection Variables, en utilisant le nom de variable ou l'index de la variable dans la collection.

Parce que la visibilité d'une variable s'étend du haut vers le bas, les variables déclarées au niveau du package sont visibles pour tous les conteneurs situés dans le package. Par conséquent, la collection Variables sur un conteneur inclut toutes les variables qui appartiennent à son parent en plus de ses propres variables.

Inversement, les variables contenues dans une tâche sont limitées en termes de portée et de visibilité et sont uniquement visibles pour la tâche.

Si un package exécute d'autres packages, les variables définies dans la portée du package appelant sont disponibles pour le package appelé. La seule exception se produit lorsqu'une variable de même nom existe dans le package appelé. Lorsque cette collision se produit, la valeur de la variable dans le package appelé remplace celle du package appelant. Les variables définies dans la portée du package appelé ne sont jamais de nouveau disponibles pour le package appelant.

L'exemple de code suivant crée une variable, myCustomVar, par programme, à la portée du package, puis parcourt toutes les variables visibles pour le package, en imprimant leur nom, leur type de données et leur valeur.

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

Exemple de sortie :

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, <domaine>\<userid>

Variable : VersionBuild, Int32, 198

Variable : VersionComments, String,

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

Variable : VersionMajor, Int32, 1

Variable : VersionMinor, Int32, 0

Notez que toutes les variables étendues dans l'espace de noms System sont disponibles pour le package. Pour plus d'informations, consultez Variables système.

Espaces de noms

MicrosoftSQL ServerIntegration Services (SSIS) fournit deux espaces de noms par défaut dans lesquels les variables résident : User et System. Par défaut, toute variable personnalisée créée par le développeur est ajoutée à l'espace de noms User. Les variables système résident dans l'espace de noms System. Vous pouvez créer des espaces de noms supplémentaires autres que l'espace de noms User afin d'y placer des variables personnalisées et vous pouvez modifier le nom de l'espace de noms User. En revanche, vous ne pouvez pas ajouter ou modifier des variables dans l'espace de noms System, ni assigner des variables système à un autre espace de noms.

Les variables système qui sont disponibles diffèrent selon le type de conteneur. Pour obtenir la liste des variables système disponibles pour les packages, conteneurs, tâches et gestionnaires d'événements, consultez Variables système.

Valeur

La valeur d'une variable personnalisée peut être un littéral ou une expression :

• Si vous souhaitez que la variable contienne une valeur littérale, définissez la valeur de sa propriété Value.

• Si vous souhaitez que la variable contienne une expression, afin de pouvoir utiliser les résultats de l'expression en tant que valeur, définissez la propriété EvaluateAsExpression de la variable sur trueet fournissez une expression dans la propriété Expression. Au moment de l'exécution, l'expression est évaluée et son résultat est utilisé en tant que valeur de la variable. Par exemple, si la propriété de l'expression d'une variable est "100 * 2""100 * 2" , la variable est évaluée à une valeur de 200.

Pour une variable, vous ne pouvez pas définir explicitement la valeur de sa propriété DataType. La valeur DataType est déduite de la valeur initiale assignée à la variable et ne peut pas être changée par la suite. Pour plus d'informations sur les types de données des variables, consultez Types de données d'Integration Services.

L'exemple de code suivant crée une variable, définit la propriété EvaluateAsExpression sur true, assigne l'expression "100 * 2" à la propriété de l'expression de la variable, puis calcule la valeur de la 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

Exemple de sortie :

Expression pour myVar : 100 * 2

Valeur de myVar : 200

L'expression doit être une expression valide qui utilise la syntaxe d'expression SSIS. Les littéraux sont autorisés dans les expressions variables, en plus des opérateurs et fonctions que la syntaxe d'expression fournit, mais les expressions ne peuvent pas référencer d'autres variables ou colonnes. Pour plus d'informations, consultez Informations de référence des expressions Integration Services.

Fichiers de configuration

Si un fichier de configuration inclut une variable personnalisée, la variable peut être mise à jour au moment de l'exécution. Cela signifie que lorsque le package s'exécute, la valeur de la variable qui se trouvait à l'origine dans le package est remplacée par une nouvelle valeur provenant du fichier de configuration. Cette technique de remplacement s'avère utile lorsqu'un package est déployé sur plusieurs serveurs qui requièrent des valeurs de variables différentes. Par exemple, une variable peut spécifier le nombre de fois qu'un conteneur Boucle Foreach répète son flux de travail ou répertorier les destinataires auxquels un gestionnaire d'événements envoie des messages électroniques lorsqu'une erreur est déclenchée ou changer le nombre d'erreurs pouvant se produire avant l'échec du package. Ces variables sont fournies de manière dynamique dans des fichiers de configuration pour chaque environnement. Par conséquent, seules les variables accessibles en lecture/écriture sont autorisées dans les fichiers de configuration. Pour plus d'informations, consultez Création de configurations de package.

Voir aussi

Tâches

Concepts