Стандартные блоки и модули PowerShell

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику Архитектору Инженеру

Play ITЗагрузка интерактивного демо…

Маршрут

Практическая автоматизация — модель и окупаемость — модель автоматизации → эта статья → Триггеры — расписание и наблюдатели — триггеры → Функции и продвинутые параметры — функции углублённо.

---

Зачем стандартные блоки

Стандартный блок — функция с ясным контрактом, которую можно вставить в разные скрипты без копипаста. Вместо одного монолита "на 400 строк" собирают цепочку: "найти старые файлы" → "сформировать имя архива" → "упаковать и удалить".

Поэтапный подход из Практическая автоматизация — модель и окупаемость — сначала рабочий скрипт для одной задачи, затем выделение повторяемых кусков в функции, затем модуль .psm1 для команды.

---

Анатомия блока-функции

Каждая функция для автоматизации получает три обязательных элемента:

Элемент	Зачем
[CmdletBinding()]	Общие параметры -Verbose, -ErrorAction, -WhatIf
[OutputType(...)]	Документирует тип результата для IDE и Get-Help
param() с типами и Mandatory	Ранний отказ при неверных аргументах

Пример — уникальное имя архива

Функция создаёт путь к новому .zip, проверяет папку и коллизию имён — типовой паттерн архивации логов:

Код ITЗагрузка примера кода…

Пример — файлы старше N дней

Параметр "возраст" задают положительным числом; внутри функции преобразуют в отрицательный для AddDays:

Код ITЗагрузка примера кода…

KISS

Пользователю проще передать "30 дней", чем "−30" в AddDays. Валидация ValidateRange(1, …) отсекает отрицательные значения до логики архивации.

---

Сборка скрипта из блоков

Скрипт верхнего уровня — оркестратор — параметры, вызов функций, журнал, код выхода.

Код ITЗагрузка примера кода…

Проблема "функции внутри .ps1": при dot-sourcing нескольких скриптов имена функций могут конфликтовать. Решение — вынести блоки в модуль.

---

Модуль .psm1

Модуль — каталог с файлом ИмяМодуля.psm1 (и опционально ИмяМодуля.psd1 — манифест).

Структура каталога:

ArchiveTools/
├── ArchiveTools.psd1    # манифест (версия, экспорт)
└── ArchiveTools.psm1    # функции

ArchiveTools.psm1:

function Set-ArchiveFilePath { ... }  # код из примера выше

function Get-FilesOlderThan { ... }

Export-ModuleMember -Function Set-ArchiveFilePath, Get-FilesOlderThan

Минимальный ArchiveTools.psd1:

@{
    ModuleVersion = '1.0.0'
    RootModule    = 'ArchiveTools.psm1'
    FunctionsToExport = @('Set-ArchiveFilePath', 'Get-FilesOlderThan')
    Description   = 'Блоки архивации логов для внутренних скриптов'
}

Установка для разработки (путь добавьте в $env:PSModulePath или скопируйте в Documents\PowerShell\Modules):

Import-Module .\ArchiveTools\ArchiveTools.psd1 -Force
Get-Command -Module ArchiveTools

Действие	Команда
Список экспортированных функций	Get-Command -Module ArchiveTools
Справка по функции модуля	Get-Help Set-ArchiveFilePath
Обновление после правки	Import-Module ... -Force

---

Советы по модулям для автоматизации

Правило	Пояснение
Один блок — одна задача	"Имя архива" и "список файлов" — разные функции
Comment-based help в каждой функции	Get-Help без чтения исходника — см. Рекомендации по написанию PowerShell-скриптов
Install-Module вне рабочего скрипта	Установку модулей делают при подготовке образа ПК или в CI
Версии модулей фиксируют	Два скрипта могут требовать разные версии одного модуля
Тестируйте блок отдельно	В консоли: Get-FilesOlderThan -Path C:\Logs -Days 7 -Verbose

---

Когда выносить в модуль

Ситуация	Решение
Функция нужна в одном .ps1	Оставить в том же файле или dot-source .\Blocks.ps1
Тот же блок в 2+ скриптах	Модуль или общий .ps1 с dot-sourcing
Блок отдают другой команде	Модуль + Git + 111 чек-лист
Нужна публикация в Gallery	Манифест .psd1, semver, Publish-Module

---

Чек-лист блока

#	Проверка
1	Есть [CmdletBinding()] и [OutputType]
2	Параметры типизированы; обязательные — Mandatory
3	Ошибки — throw или -ErrorAction Stop, а не тихий $null
4	Есть Write-Verbose для отладки в планировщике
5	Функция возвращает объект/значение, а не только пишет в консоль

---

Дальше

Тема	Материал
Запуск по расписанию и наблюдатели	Триггеры — расписание и наблюдатели
Планировщик Windows, пример .ps1	2.05/112
Параметры, SupportsShouldProcess	Функции и продвинутые параметры
Модули Gallery, Az, Graph	Популярные модули и примеры скриптов

---