SSISDB6：参数和环境变量

SSISDB 系列随笔汇总：

• SSISDB1：使用SSISDB管理Package
• SSISDB2：SSIS工程的操作实例
• SSISDB3：Package的执行实例
• SSISDB4：当前正在运行的Package及其Executable
• SSISDB5：使用TSQL脚本执行Package
• SSISDB6：参数和环境变量

参数（Parameter）是Package暴露给外界的接口，通过传递不同的参数值，能够控制 Package 的执行流程，执行不同的任务（Task）。参数分为Package级别的参数（Package Parameter）和工程级别的参数（Project Parameter），Package参数只能作用于当前的Package，而Project参数能够作用于当前Project中包含的所有Package。参数的值只能引用，不能修改。

参数除了直接赋值之外，还能通过环境变量来赋值。环境是变量的集合，参数引用不同环境中的变量，能够快速切换Package引用的参数值，例如，在测试环境和产品环境之间快速切换，这是参数化编程带来的便利。

一，参数的值

参数有三种类型的值：design_default_value，Default_Value 和 Execution_Value：

• design_default_value：在设计SSIS Project时，设置parameter的默认值。
• Default_Value：在project 部署到SSISDB后，如果不对Parameters value进行修改，那么 Default_Value 和 design_default_value 相同；也可以修改Parameter的default value。
• Execution_Value：Package 在执行时，parameters的值是Execution Value。默认情况下，Package在执行时，使用default value作为execution value；也可以在启动Execution时，设置Parameter的值，修改Execution Value不会修改Default value。

用户可以创建参数和环境之间的映射，Package在执行时，引用环境（Environment）中的变量（Variables）为参数赋值。

1，查看参数的设计值（design_default_value） 和默认值（Default_Value）

select f.name as folder_name,
    p.name as project_name,
    op.parameter_id,
    op.parameter_name,
    case op.object_type
        when 20 then 'Project'
        when 30 then 'Package'
        else ''
    end as  object_type,
    op.object_name,
    op.data_type,
    op.required,
    op.sensitive,
    op.design_default_value,
    op.default_value,
    case op.value_type
        when 'V' then 'parameter_value is a literal value'
        when 'R' then 'referencing an environment variable'
        else ''
    end as value_type,
    op.value_set,
    op.referenced_variable_name
from catalog.object_parameters op
inner join catalog.projects p
    on op.project_id=p.project_id
inner join catalog.folders f
    on p.folder_id=f.folder_id
where op.object_type in(20,30)

2，查看参数的执行值（Execution_Value）

select epv.execution_parameter_id,
    case epv.object_type
        when 20 then 'Project'
        when 30 then 'Package'
        when 50 then 'Special'
        else ''
    end as  object_type,
    epv.parameter_data_type,
    epv.parameter_name,
    epv.parameter_value,
    epv.sensitive,
    epv.required,
    epv.value_set,
    epv.runtime_override
from catalog.execution_parameter_values epv
where execution_id=104627

3，通过TSQL来设置参数的执行值（Execution value）

declare @Execution_ID bigint
exec catalog.create_execution @package_name=N'Test.dtsx',
    @Execution_ID=@Execution_ID output,
    @folder_name=N'MyProjectFloder',
    @project_name=N'MyProject',
    @use32bitruntime=FALSE,
    @reference_id=null
 
declare @var0 sql_variant=N'Package_Parameter_value';
exec catalog.set_execution_parameter_value
    @Execution_ID=@Execution_ID,
    @object_type=30,        --Package
    @parameter_name=N'Package_Parameter_Name',
    @parameter_value=@var0
 
exec catalog.start_execution @Execution_ID=@Execution_ID

二，参数的属性

参数有两种作用域：Project Scope 和 Package Scope。Project Scope用于Project中的所有package，而Package Scope只能用于当前Package，package只能引用 Parameter的值，不能修改。

Sensitive：敏感性，对于敏感参数，SSIS对值进行加密。

Required：必需性，对于必需参数，在执行时，必须设置值；在Create Agent时，必须显式为必需参数赋值。

三，特殊参数

SSISDB的特殊参数，用于控制Package执行时的特殊行为，这些参数的值，通过 catalog.set_execution_parameter_value 来设置，参数 @object_type必须为50.

• LOGGING_LEVEL
• CUSTOMIZED_LOGGING_LEVEL
• DUMP_ON_ERROR
• DUMP_ON_EVENT
• DUMP_EVENT_CODE
• CALLER_INFO
• SYNCHRONIZED

1，记录日志的级别

LOGGING_LEVEL：设置执行实例的日志级别，有效值是0、1、2、3，数值越大，日志记录的越详细，分别是：不记录（no Logging），基本（Basic），性能（Performance）和详细（verbose ）。

2，Package执行的同步性

默认情况下，当使用 catalog.start_execution 执行一个Package的执行实例（Execution Instance）时，该sp会立即返回结果值（0，表示调用Package成功），而不会等待Package执行完成，如果将参数 SYNCHRONIZED  设置为1，那么该SP不会立即返回，而是等到Package执行完成之后，才返回结果。

exec catalog.set_execution_parameter_value
　  @execution_id,
    @object_type= 50,
    @parameter_name = N'Synchronized',
    @parameter_value = 1;

3，创建用于调试的转存文件

• DUMP_ON_ERROR：在Package发生错误时创建转存文件
• DUMP_ON_EVENT：在触发事件时创建转存文件
• DUMP_EVENT_CODE：转存事件代码

4，查看特殊参数的执行值（Execution value）

select epv.execution_parameter_id,
    case epv.object_type
        when 20 then 'Project'
        when 30 then 'Package'
        when 50 then 'Special'
        else ''
    end as  object_type,
    epv.parameter_data_type,
    epv.parameter_name,
    epv.parameter_value,
    epv.sensitive,
    epv.required,
    epv.value_set,
    epv.runtime_override
from catalog.execution_parameter_values epv
where execution_id=104627
    and epv.object_type=50

四，环境和环境变量

环境（Environment）是变量的集合，创建环境的目的是为了向环境中添加变量。在开发Package时，为了保证开发包的质量，需要把产品环境和测试环境独立开来，包只有在测试环境中执行通过时，才能部署到产品环境中。这可以简单的通过修改链接管理器（Connection Manager）来实现。但是，当链接比较多时，或参数比较多时，在修改参数时，很容易出现错误。如果把Project和环境关联起来，把环境中的变量和参数关联起来。这样，只需要修改Project引用的环境，就可以很容易地切换Package运行的环境。

1，创建环境

通过向导来创建环境，右击“Environments”，点击“Create Environment”，打开创建环境的向导，输入环境名称，点击“OK”按钮，创建环境：

2，向环境中添加变量

右击新建的环境，点击“Properties”，选择“variables”页，输入变量的名称，选择变量的类型，输入变量值，勾选变量的敏感（Sensitive）属性：

3，设置Project引用环境

右击工程名称，点击“Configure”，在“Parameters” Tab中查看工程的参数。

选择“References” Tab，选择project 引用的环境：

回到“Parameters”Tab，点击value列后面的“...”，逐个设置工程参数应用的环境变量：

4，查看Project引用的环境

通过 catalog.environment_references 查看Project应用的环境，引用类型reference_type，当reference_type为A，表示使用绝对应用（absolute reference）；当reference_type为A，表示使用相对引用（relative reference）。相对引用表示环境和Project必须处于相同的Folder中；绝对引用表示环境和Project可以位于不同的Folder中，当然也可以位于相同的Folder中。

五，查看环境变量

1，参看参数 和环境变量的对应关系

--object_type : 20 (project parameter), 30 (package parameter)
--value_type: V (parameter_value is a literal value),R(referencing an environment variable)
--value_set:1(the parameter value has been assigned), 0 (the parameter value has not been assigned)
 
select op.project_id,
    p.name as ProjectName,
    op.object_type,
    op.object_name,
    op.parameter_name,
    op.data_type,
    op.required,
    op.sensitive,
    op.design_default_value,
    op.default_value,
    op.value_type,
    op.referenced_variable_name,
    op.value_set
from [catalog].[object_parameters] op with(NOLOCK)
inner join catalog.projects p with(nolock)
    on op.project_id=p.project_id
where object_type in(20,30)

2，查看SSISDB的环境变量

select f.name as Folder_Name,e.name as Environment_Name,
    ev.variable_id,ev.name as Environment_Variable_Name,
    ev.sensitive,ev.type,ev.value
from catalog.environments e
inner join catalog.environment_variables ev
    on e.environment_id=ev.environment_id
inner join catalog.folders f
    on e.folder_id=f.folder_id

3，查看Package 的参数和环境变量的映射关系

select er.environment_folder_name,er.environment_name,p.name as Project_Name,
    er.reference_type,
        ev.variable_id,ev.name as Environment_Variable_Name,
    ev.sensitive,ev.type,ev.value,
    op.parameter_id,op.object_type,op.object_name,op.parameter_name,
    op.data_type as Parameter_Data_Type,op.required,op.sensitive,
    op.default_value,op.design_default_value,op.value_set,op.value_type
from catalog.environment_references er
inner join catalog.projects p
    on er.project_id=p.project_id
inner join catalog.environments e
    on er.environment_name= er.environment_name
inner join catalog.environment_variables ev
    on e.environment_id=ev.environment_id
inner join catalog.object_parameters op
    on op.project_id=p.project_id and op.value_type=N'R' and op.referenced_variable_name=ev.name

参考文档：

catalog.object_parameters (SSISDB Database)

catalog.environment_references (SSISDB Database)

catalog.set_execution_parameter_value (SSISDB Database)

Quick Tip – Run SSIS 2012 packages synchronously and other execution parameters