پاورشل برای برنامه‌نویسان

درسنامه: Best Practices برای ساخت اسکریپت در PowerShell

این درسنامه به معرفی اصول و روش‌های حرفه‌ای برای نوشتن اسکریپت‌های PowerShell می‌پردازد. رعایت این نکات باعث می‌شود کدهای تو تمیزتر، قابل‌خواندن‌تر، قابل‌نگهداری‌تر و امن‌تر باشند. این اصول در پروژه‌های واقعی و مخصوصاً در محیط‌های سازمانی بسیار مهم‌اند.

۱. از ساختار و قالب استاندارد استفاده کن

هر اسکریپت باید از چند بخش تشکیل شود:

1. توضیحات اولیه (Header)
2. پارامترها
3. بدنه اصلی کد
4. خروجی و پایان

مثلاً:

<#
.SYNOPSIS
    This script backs up a directory to a ZIP file.
.DESCRIPTION
    It compresses files and saves them with a timestamp.
#>

param(
    [string]$SourcePath,
    [string]$DestinationPath
)

# --- Main Logic ---
$time = Get-Date -Format "yyyyMMdd_HHmm"
$zipName = "Backup_$time.zip"
Compress-Archive -Path $SourcePath -DestinationPath "$DestinationPath\$zipName"

Write-Host "Backup created successfully!"

این ساختار باعث می‌شود هم خودت و هم دیگران بعدها راحت‌تر اسکریپت را درک و نگهداری کنند.

۲. از نام‌گذاری استاندارد و قابل‌فهم استفاده کن

اسم متغیرها، توابع و فایل‌ها باید توصیفی باشند.

به‌جای:

$a = Get-ChildItem

بهتر است بنویسی:

$files = Get-ChildItem

برای توابع هم از الگوی Verb-Noun استفاده کن، مثل Get-Report یا Start-Backup.

۳. ورودی‌ها را با پارامترها بگیر

هیچ وقت مقادیر را داخل کد "سخت‌کد" نکن. همیشه از param() استفاده کن تا اسکریپتت انعطاف‌پذیر باشد:

param(
    [string]$Path,
    [switch]$Verbose
)

همچنین برای ورودی‌های حیاتی از ValidateNotNullOrEmpty() یا ValidateSet() استفاده کن تا از خطا جلوگیری شود.

۴. از خروجی استاندارد استفاده کن

به جای استفاده‌ی بی‌رویه از Write-Host (که فقط خروجی تصویری می‌دهد)، سعی کن داده‌ها را به‌صورت شیء برگردانی تا بتوان در pipeline استفاده کرد:

function Get-SystemInfo {
    [PSCustomObject]@{
        ComputerName = $env:COMPUTERNAME
        OSVersion    = (Get-CimInstance Win32_OperatingSystem).Version
    }
}

این روش باعث می‌شود خروجی تو برای پردازش‌های بعدی قابل‌استفاده باشد (مثلاً Export به CSV یا JSON).

۵. از Error Handling درست استفاده کن

به جای رها کردن خطاها، از try/catch/finally استفاده کن:

try {
    Remove-Item "C:\Temp\test.txt" -ErrorAction Stop
}
catch {
    Write-Error "Failed to remove file: $_"
}
finally {
    Write-Host "Cleanup complete."
}

همچنین از -ErrorAction Stop برای متوقف کردن پردازش هنگام خطای جدی استفاده کن.

۶. مستندسازی و کامنت‌گذاری

توضیح دادن منطق کدها یکی از نشانه‌های حرفه‌ای بودن است.

برای توضیحات خطی از # استفاده کن و برای اسکریپت‌های بزرگ از بلوک‌های <# #>:

# This part checks if the directory exists
if (-Not (Test-Path $Path)) {
    Write-Error "Path not found."
}

۷. از مسیرهای نسبی و متغیرهای محیطی استفاده کن

در اسکریپت‌ها از مسیرهای مطلق مثل C:\Users\Ali\Documents پرهیز کن.

به جای آن از متغیرهای عمومی استفاده کن:

$path = "$env:USERPROFILE\Documents"

یا از Join-Path برای ساخت مسیرها به‌صورت سازگار با سیستم‌عامل:

$backupPath = Join-Path $env:TEMP "Backup"

۸. از Verbose و Logging استفاده کن

برای اینکه اسکریپت‌ها در زمان اجرا وضعیت خود را نمایش دهند، از Write-Verbose یا Write-Output استفاده کن:

Write-Verbose "Copying files..."

همچنین می‌توانی از log file برای ثبت گزارش استفاده کنی:

"[$(Get-Date)] Backup completed." | Out-File -Append "C:\Logs\backup.log"

۹. تست و Debug

قبل از اجرای اسکریپت در محیط واقعی، آن را در محیط آزمایشی تست کن.

می‌توانی از دستور زیر برای شبیه‌سازی بدون اجرا استفاده کنی:

Remove-Item C:\Test -WhatIf

گزینه‌ی -WhatIf یکی از بهترین ابزارها برای جلوگیری از خطای ناخواسته است.

۱۰. از Style Consistency پیروی کن

یک سبک نوشتاری ثابت برای تورفتگی (indentation)، فاصله‌ها و حروف بزرگ رعایت کن.

مثلاً همیشه {} را در خط بعدی قرار بده و متغیرها را با $ دقیق بنویس.

۱۱. اسکریپتت را قابل استفاده‌ی مجدد کن

اگر بخشی از کد را در چند اسکریپت نیاز داری، آن را به صورت function یا module بساز تا تکرار کد کاهش یابد.

۱۲. امنیت را فراموش نکن

• رمزها یا اطلاعات حساس را به‌صورت مستقیم در کد ننویس.
• از SecureString یا Credential Manager برای ذخیره امن اطلاعات استفاده کن.
• اگر اسکریپت قرار است در سیستم‌های دیگر اجرا شود، Execution Policy را بررسی کن.

با رعایت این اصول، اسکریپت‌های PowerShell تو نه‌تنها بهتر کار خواهند کرد، بلکه نگهداری و توسعه‌ی آن‌ها در آینده هم بسیار راحت‌تر می‌شود. اسکریپت خوب، مثل کد خوب، باید خوانا، قابل اعتماد و ایمن باشد.