Системные переменные SSIS
Системные переменные SSIS — это предопределённый набор переменных, доступных только для чтения в среде выполнения пакетов служб SQL Server Integration Services (SSIS). Они предоставляют информацию о контексте выполнения пакета, его задачах, контейнерах и обработчиках событий. Системные переменные автоматически создаются средой выполнения SSIS и не могут быть удалены, переименованы или изменены пользователем.
Назначение и область применения
Системные переменные предназначены для обеспечения доступа к метаданным и состоянию выполнения пакета. Они позволяют разработчикам и администраторам получать информацию о:
- Идентификации пакета: имя, уникальный идентификатор (GUID), версия.
- Конфигурации выполнения: режим запуска, имя компьютера, учётная запись пользователя.
- Состоянии выполнения: время начала, результат выполнения, идентификатор экземпляра выполнения.
- Иерархии объектов: имя и идентификатор родительского контейнера или задачи.
Эти переменные используются в выражениях, скриптах, задачах «Выполнение SQL», «Скрипт-задача» и «Скрипт-компонент», а также в конфигурациях пакета. Они незаменимы для ведения журнала, динамического построения путей к файлам, условного ветвления и отладки.
Классификация системных переменных
Системные переменные классифицируются по области действия (scope). Каждая переменная принадлежит определённому уровню иерархии пакета: сам пакет, контейнер (например, «Цикл по каждому элементу» или «Последовательность»), задача или обработчик событий.
Переменные уровня пакета
Эти переменные доступны во всех элементах пакета, если не переопределены на более низком уровне.
| Имя переменной | Тип данных | Описание |
|---|---|---|
System::PackageID | String | Уникальный идентификатор (GUID) пакета. |
System::PackageName | String | Имя файла пакета (без расширения .dtsx). |
System::StartTime | DateTime | Дата и время начала выполнения пакета. |
System::UserName | String | Учётная запись пользователя, запустившего пакет. |
System::MachineName | String | Имя компьютера, на котором выполняется пакет. |
System::CreationDate | DateTime | Дата и время создания пакета. |
System::CreatorComputerName | String | Имя компьютера, на котором был создан пакет. |
System::CreatorName | String | Имя пользователя, создавшего пакет. |
System::VersionBuild | Int32 | Номер сборки версии пакета. |
System::VersionMajor | Int32 | Основной номер версии пакета. |
System::VersionMinor | Int32 | Дополнительный номер версии пакета. |
System::VersionComments | String | Комментарии к версии пакета. |
System::VersionGUID | String | Уникальный идентификатор (GUID) версии пакета. |
Переменные уровня контейнера
Доступны внутри контейнера, в котором они определены, и во всех его дочерних элементах.
| Имя переменной | Тип данных | Описание |
|---|---|---|
System::ContainerName | String | Имя контейнера (например, «Последовательность», «Цикл по каждому элементу») или задачи. |
System::ContainerStartTime | DateTime | Дата и время начала выполнения контейнера. |
System::ExecutionInstanceGUID | String | Уникальный идентификатор (GUID) экземпляра выполнения контейнера. |
System::ParentContainerName | String | Имя родительского контейнера. |
System::SourceID | String | Уникальный идентификатор (GUID) задачи или контейнера, вызвавшего выполнение. |
System::TaskName | String | Имя задачи, которая в данный момент выполняется. |
Переменные уровня обработчика событий
Доступны только в контексте обработчика событий (например, OnError, OnPreExecute, OnPostExecute).
| Имя переменной | Тип данных | Описание |
|---|---|---|
System::ErrorCode | Int32 | Код ошибки, связанной с событием. |
System::ErrorDescription | String | Описание ошибки. |
System::ExecutionStatus | Int32 | Статус выполнения задачи или контейнера (0 — успех, 1 — сбой). |
System::EventType | Int32 | Тип события (например, OnError — 0, OnWarning — 1). |
System::SourceName | String | Имя объекта, вызвавшего событие. |
System::SubComponent | String | Имя подкомпонента, вызвавшего событие (если применимо). |
Переменные уровня цикла по каждому элементу (Foreach Loop)
Доступны только внутри контейнера «Цикл по каждому элементу».
| Имя переменной | Тип данных | Описание |
|---|---|---|
System::ForEachEnumeratorValue | Object | Текущее значение, возвращаемое перечислителем цикла. |
Особенности использования
- Только для чтения: системные переменные нельзя изменить напрямую. Попытка присвоить им значение в выражении или скрипте приведёт к ошибке выполнения.
- Тип данных: все системные переменные имеют строго определённый тип данных, как указано в таблицах выше. Это необходимо учитывать при использовании в выражениях и преобразованиях.
- Доступность: системные переменные доступны во всех областях пакета, но их значения могут различаться в зависимости от контекста. Например,
System::TaskNameв обработчике событий будет содержать имя задачи, вызвавшей событие, а в контейнере верхнего уровня — имя самого контейнера. - Отладка: системные переменные часто используются в задачах «Скрипт-задача» для вывода диагностической информации в окно вывода или журнал. Например, запись
System::PackageNameиSystem::StartTimeпозволяет отслеживать, какой пакет и когда был запущен. - Динамическое построение путей: переменная
System::PackageNameможет использоваться для создания уникальных имён файлов журналов или выходных данных, чтобы избежать конфликтов при параллельном выполнении пакетов.
Примеры применения
- Логирование ошибок: в обработчике событий
OnErrorможно записать в таблицу базы данных значенияSystem::ErrorDescription,System::SourceName,System::PackageNameиSystem::StartTimeдля последующего анализа сбоев.
- Условное выполнение: в выражении для свойства
Disableзадачи можно использовать условие:@[System::UserName] != "DOMAIN\ServiceAccount". Это позволит выполнять задачу только при запуске от имени определённой учётной записи.
- Генерация отчётов: в задаче «Выполнение SQL» можно использовать
System::PackageNameкак параметр для вставки в таблицу статистики:INSERT INTO dbo.PackageRunLog (PackageName, StartTime) VALUES (?, ?).
- Управление версиями: при развёртывании пакета можно проверять
System::VersionMajorиSystem::VersionMinorв скрипте, чтобы убедиться, что используется актуальная версия.
Отличие от пользовательских переменных
В отличие от системных, пользовательские переменные создаются разработчиком, могут быть изменены в процессе выполнения и имеют произвольные имена и типы данных. Системные переменные являются частью инфраструктуры SSIS и не подлежат модификации. Они предоставляют надёжный и стандартизированный способ получения информации о среде выполнения, в то время как пользовательские переменные служат для хранения данных, специфичных для конкретного пакета.
Источники
- Документация Microsoft SQL Server Integration Services (SSIS) — раздел «Системные переменные».
- Книга «SQL Server Integration Services Design Patterns» (Tim Mitchell, Matt Masson, Andy Leonard).
- Книга «Professional Microsoft SQL Server 2012 Integration Services» (Brian Knight, Erik Veerman, et al.).
BFOmetr — база данных и аналитика по компаниям России.
На главную BFOmetr →