Trabalhando com variáveis programaticamente

Escopo

Cada contêiner tem sua própria coleção Variables. Quando uma nova variável é criada, ela fica dentro do escopo de seu contêiner pai. Como o contêiner de pacote está no topo da hierarquia de contêineres, as variáveis com escopo de pacote funcionam como variáveis globais e ficam visíveis para todos os contêineres de pacote. A coleção de variáveis para o contêiner também pode ser acessada pelos filhos do contêiner através da coleção Variables, usando o nome da variável ou o índice da variável na coleção.

Como a visibilidade de uma variável tem um escopo de cima para baixo, as variáveis declaradas no nível do pacote são visíveis para todos os contêineres do pacote. Portanto, a coleção Variables em um contêiner inclui todas as variáveis que pertencem a seu pai além de suas próprias variáveis.

Por outro lado, as variáveis contidas em uma tarefa têm escopo e visibilidade limitados e são visíveis somente para a tarefa.

Se um pacote executar outros pacotes, as variáveis definidas no escopo do pacote de chamada estarão disponíveis ao pacote chamado. A única exceção ocorre quando há uma variável do mesmo nome no pacote chamado. Quando essa colisão ocorre, o valor variável no pacote chamado anula o valor do pacote de chamada. As variáveis definidas no escopo do pacote chamado não podem ficar disponíveis para o pacote de chamada de novo.

O exemplo de código seguinte cria programaticamente uma variável, myCustomVar, no escopo do pacote, e itera todas as variáveis visíveis do pacote, imprimindo seu nome, tipo de dados e valor.

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

Exemplo de saída:

Variável: CancelEvent, Int32, 0

Variável: CreationDate, DateTime, 4/18/2003 11:57:00 AM

Variável: CreatorComputerName, String,

Variável: CreatorName, String,

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

Variável: FileName, String, Junk

Variável: InteractiveMode, Boolean, False

Variável: LocaleID, Int32, 1033

Variável: MachineName, String, MYCOMPUTERNAME

Variável: myCustomVar, String, 3

Variável: OfflineMode, Boolean, False

Variável: PackageID, String, {F0D2E396-A6A5-42AE-9467-04CE946A810C}

Variável: PackageName, String, DTSPackage1

Variável: StartTime, DateTime, 1/28/2005 7:55:39 AM

Variável: UserName, String, <domain>\<userid>

Variável: VersionBuild, Int32, 198

Variável: VersionComments, String,

Variável: VersionGUID, String, {90E105B4-B4AF-4263-9CBD-C2050C2D6148}

Variável: VersionMajor, Int32, 1

Variável: VersionMinor, Int32, 0

Note que todas as variáveis com escopo no namespace do Sistema estão disponíveis para o pacote. Para obter mais informações, consulte Variáveis do sistema.

Namespaces

O Microsoft SQL Server Integration Services (SSIS) fornece dois namespaces padrão onde residem as variáveis; namespaces Usuário e Sistema. Por padrão, qualquer variável personalizada criada pelo desenvolvedor é acrescentada ao namespace Usuário. As variáveis de sistema residem no namespace Sistema. Você pode criar namespaces adicionais, além do namespace Usuário, para manter variáveis personalizadas, e você pode alterar o nome do namespace Usuário, mas não pode adicionar ou modificar variáveis no namespace Sistema ou atribuir variáveis de sistema a um namespace diferente.

As variáveis de sistema que estão disponíveis diferem dependendo do tipo de contêiner. Para uma lista das variáveis de sistema disponíveis para pacotes, contêineres, tarefas e manipuladores de eventos, consulte Variáveis do sistema.

Valor

O valor de uma variável personalizada pode ser literal ou uma expressão:

• Se você quiser a variável para conter um valor literal, defina o valor de sua propriedade Value.

• Se você deseja que a variável contenha uma expressão para que você possa usar os resultados da expressão como seu valor, defina a propriedade EvaluateAsExpression da variável como true e forneça uma expressão na propriedade Expression. Em tempo de execução, a expressão é avaliada e o resultado da expressão é usado como valor da variável. Por exemplo, se a propriedade da expressão de uma variável for "100 * 2""100 * 2", a variável avaliará a um valor de 200.

Para uma variável, você não pode definir o valor de seu DataType explicitamente. O valor DataType é inferido do valor inicial atribuído à variável e não pode ser alterado posteriormente. Para obter mais informações sobre tipos de dados variáveis, consulte Tipos de dados do Integration Services.

O exemplo de código a seguir cria uma nova variável, define EvaluateAsExpression como true, atribui a expressão "100 * 2" à propriedade da expressão da variável e produz o valor da variável.

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

Exemplo de saída:

Expressão para myVar: 100 * 2

Valor de myVar: 200

A expressão deve ser uma expressão válida que usa a sintaxe da expressão SSIS. Literais são permitidos em expressões variáveis, além dos operadores e funções que a sintaxe da expressão fornece, mas as expressões não podem fazer referência a outras variáveis ou colunas. Para obter mais informações, consulte Referência de Expressão do Integration Services.

Arquivos de configuração

Se um arquivo de configuração incluir uma variável personalizada, a variável poderá ser atualizada em tempo de execução. Isso significa que quando o pacote é executado, o valor da variável originalmente no pacote é substituído por um novo valor do arquivo de configuração. Essa técnica de substituição é útil quando um pacote é implantado em vários servidores que requerem valores de variável diferentes. Por exemplo, uma variável pode especificar o número de vezes que um contêiner Loop Foreach repete seu fluxo de trabalho ou listar os recipientes para os quais um manipulador de eventos envia email quando um erro é gerado ou alterar o número de erros que podem ocorrer antes de o pacote falhar. Essas variáveis são fornecidas dinamicamente em arquivos de configuração para cada ambiente. Portanto, somente as variáveis de leitura/gravação são permitidas em arquivos de configuração. Para obter mais informações, consulte Criando configurações do pacote.

Consulte também

Tarefas

Conceitos