PowerShell כתיבת-יומן: מדריך לפונקצית לוגינג פשוטה

מדריכים
PowerShell

אם אתה כותב סקריפטים של PowerShell שעושים משהו משמעותי, אתה צריך רישום. בין אם אתה מפיץ תוכנה, מנהל שירותים או מאוטם משימות, זה חיוני שיהיה תיעוד של מה שהסקריפט שלך עשה (או לא עשה). במדריך זה, תלמד כיצד ליצור פונקציית רישום פשוטה אך יעילה ב-PowerShell.

דרישות מוקדמות

אם אתה רוצה לעקוב אחר המדריך הזה, ודא שיש לך:

  • Windows 10 או Windows Server עם PowerShell 5.1 או PowerShell 7+
  • עורך טקסט (VSCode מומלץ)
  • הבנה בסיסית של פונקציות PowerShell

הבעיה עם רישום בסיסי

נניח שאתה כותב סקריפט להתקנה שקטה של תוכנה כלשהי. הגישה הבסיסית עשויה להיראות כך:

Add-Content -Path "C:\\Scripts\\install.log" -Value "Starting install..."
Start-Process -FilePath 'installer.exe' -ArgumentList '/i /s' -Wait -NoNewWindow
Add-Content -Path "C:\\Scripts\\install.log" -Value "Finished install."

זה עובד, אבל יש לו כמה בעיות:

  • אין חותמות זמן
  • קוד חוזר
  • פורמט רישום לא עקבי
  • נתיב רישום קשה

בואו נתקן את הבעיות הללו על ידי בניית פונקציית רישום נכונה.

בניית פונקציית Write-Log בסיסית

ראשית, בואו ניצור פונקציה פשוטה שמוסיפה חותמות זמן לכניסות הרישום שלנו:

function Write-Log {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]$Message
    )

    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path "C:\\Scripts\\script.log" -Value "$timeGenerated - $Message"
}

עכשיו אתה יכול להשתמש בזה כך:

Write-Log -Message "Starting install..."
Start-Process -FilePath 'installer.exe' -ArgumentList '/i /s' -Wait -NoNewWindow
Write-Log -Message "Finished install."

קובץ הרישום (C:\Scripts\script.log) יכיל כניסות שיראו כך:

09:42:15 - Starting install...
09:43:22 - Finished install.

הרבה יותר נקי! אבל אנחנו יכולים לעשות יותר טוב.

הוספת יותר פונקציות

בואו נשפר את פונקציית הרישום שלנו עם כמה תכונות מועילות:

  • נתיבי רישום מותאמים
  • רמות דיווח שונות (מידע, אזהרה, שגיאה)
  • תאריך בשם הקובץ
  • טיפול בשגיאות

זוהי הגרסה המשופרת:

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Message,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]$LogFilePath = "C:\\Scripts\\Logs",

        [Parameter()]
        [ValidateSet('Information','Warning','Error')]
        [string]$Level = "Information"
    )

    # Create the log directory if it doesn't exist
    if (!(Test-Path $LogFilePath)) {
        New-Item -Path $LogFilePath -ItemType Directory -Force | Out-Null
    }

    # Build the log file path with date
    $date = Get-Date -Format "MM-dd-yyyy"
    $logFile = Join-Path $LogFilePath "log-$date.txt"

    # Get the current timestamp
    $timeStamp = Get-Date -Format "HH:mm:ss"

    # Create the log entry
    $logEntry = "$timeStamp [$Level] - $Message"

    try {
        Add-Content -Path $logFile -Value $logEntry -ErrorAction Stop
    }
    catch {
        Write-Error "Failed to write to log file: $_"
    }
}

הגרסה משופרת זו מעניקה לך גמישות רבה יותר. הנה כיצד להשתמש בה:

# Basic information logging
Write-Log -Message "Starting software installation"

# Warning about a non-critical issue
Write-Log -Message "Config file not found, using defaults" -Level Warning

# Log an error
Write-Log -Message "Installation failed!" -Level Error

# Use a custom log path
Write-Log -Message "Custom path log" -LogFilePath "D:\\CustomLogs"

הקובץ הלוג המתקבל (log-03-12-2024.txt) יראה כך:

10:15:22 [Information] - Starting software installation
10:15:23 [Warning] - Config file not found, using defaults
10:15:25 [Error] - Installation failed!

וב- D:\CustomLogs\log-03-12-2024.txt:

10:15:26 [Information] - Custom path log

שים לב שכל רשומה כוללת את הזמן, רמת הלוג בסוגריים מרובעות, וההודעה. פורמט מובנה זה עוזר לפענח יומנים ולזהות במהירות בעיות.

דוגמה ממחישה: סקריפט התקנת תוכנה

נניח לפונקציית הלוג שלנו לעבוד בסקריפט אמיתי שמתקין תוכנה באופן שקט:

# First, dot-source the logging function
. .\\Write-Log.ps1

# Script variables
$installer = "C:\\Installers\\software.exe"
$logPath = "C:\\Scripts\\InstallLogs"

# Start logging
Write-Log -Message "Beginning installation process" -LogFilePath $logPath

# Check if installer exists
if (Test-Path $installer) {
    Write-Log -Message "Found installer at: $installer"

    try {
        # Attempt installation
        Write-Log -Message "Starting installation..."
        $process = Start-Process -FilePath $installer -ArgumentList '/i /s' -Wait -NoNewWindow -PassThru

        # Check the exit code
        if ($process.ExitCode -eq 0) {
            Write-Log -Message "Installation completed successfully"
        }
        else {
            Write-Log -Message "Installation failed with exit code: $($process.ExitCode)" -Level Error
        }
    }
    catch {
        Write-Log -Message "Installation failed with error: $_" -Level Error
    }
}
else {
    Write-Log -Message "Installer not found at: $installer" -Level Error
}

Write-Log -Message "Installation script completed"

הקובץ הלוג שמתקבל יראה משהו כזה:

09:15:22 [Information] - Beginning installation process
09:15:22 [Information] - Found installer at: C:\\Installers\\software.exe
09:15:22 [Information] - Starting installation...
09:16:45 [Information] - Installation completed successfully
09:16:45 [Information] - Installation script completed

טיפים שימושיים

הנה כמה המלצות נכונות בעת השימוש בפונקציית הלוגים הזו:

  1. תמיד לשמור על רישום תחילת וסיום הסקריפט שלך – זה עוזר למעקב אחר זמן הפעולה של הסקריפט ומצב השלמות שלו.

  2. השתמש ברמות דיווח מתאימות – אל תסמן הכול כשגיאה; השתמש ברמה הנכונה למצב:

    • מידע: פעולות רגילות
    • אזהרה: בעיות לא קריטיות
    • שגיאה: בעיות קריטיות שדורשות תשומת לב

  3. כלול פרטים רלוונטיים – רשום מספיק מידע כדי להבין מה קרה:

    # רע
Write-Log "לא הצליח להתחבר"

# טוב
Write-Log "לא הצליח להתחבר לשרת 'SQL01' - זמן המתנה לאחר 30 שניות" -Level Error

  4. נקה יומנים ישנים – שקול להוסיף סיבוב יומנים כדי למנוע תפיסת מקום בדיסק:

    # מחק יומנים בני 30 ימים ומעלה
Get-ChildItem -Path $LogFilePath -Filter "*.txt" |
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
    Remove-Item

סיכום

פונקציית רישום טובה היא חיונית לכל סקריפט PowerShell רציני. עם פונקציית Write-Log שבנינו, יש לך עכשיו דרך גמישה וניתנת לשימוש חוזר להוסיף רישום נכון לכל הסקריפטים שלך. זכור להתאים את הפונקציה לצרכים הספציפיים שלך – ייתכן שתרצה להוסיף תכונות כמו:

סיבוב יומנים

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Message,

        [Parameter()]
        [int]$MaxLogFiles = 30  # Keep last 30 days of logs
    )

    # Remove old log files
    Get-ChildItem -Path $LogFilePath -Filter "*.txt" |
        Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-$MaxLogFiles) } |
        Remove-Item -Force

    # Continue with normal logging...
}

פורמטי פלט שונים (CSV, JSON)

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Message,

        [Parameter()]
        [ValidateSet('TXT','CSV','JSON')]
        [string]$Format = 'TXT'
    )

    $logEntry = [PSCustomObject]@{
        Timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
        Level = $Level
        Message = $Message
    }

    switch ($Format) {
        'CSV'  { $logEntry | Export-Csv -Path "$LogFilePath\\log.csv" -Append -NoTypeInformation }
        'JSON' { $logEntry | ConvertTo-Json | Add-Content -Path "$LogFilePath\\log.json" }
        'TXT'  { "$($logEntry.Timestamp) [$($logEntry.Level)] - $($logEntry.Message)" |
                 Add-Content -Path "$LogFilePath\\log.txt" }
    }
}

תמיכה בנתיבי רשת

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Message,

        [Parameter()]
        [string]$NetworkPath = "\\\\server\\logs"
    )

    # Test network path connectivity
    if (!(Test-Path $NetworkPath)) {
        # Fallback to local logging if network is unavailable
        $NetworkPath = "C:\\Scripts\\Logs"
        Write-Warning "Network path unavailable. Using local path: $NetworkPath"
    }

    # Continue with normal logging...
}

התראות דוא"ל על שגיאות

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Message,

        [Parameter()]
        [string]$SmtpServer = "smtp.company.com",

        [Parameter()]
        [string[]]$NotifyOnError = "[email protected]"
    )

    # Normal logging first...

    # Send email if this is an error
    if ($Level -eq 'Error' -and $NotifyOnError) {
        $emailParams = @{
            From = "[email protected]"
            To = $NotifyOnError
            Subject = "PowerShell Script Error"
            Body = "Error occurred at $timeStamp`n`nMessage: $Message"
            SmtpServer = $SmtpServer
        }

        try {
            Send-MailMessage @emailParams
        }
        catch {
            Write-Warning "Failed to send error notification: $_"
        }
    }
}

החשוב הוא להתחיל עם בסיס יציב ולבנות משם בהתאם לצרכים הספציפיים שלך. הדוגמאות הללו צריכות לתת לך נקודת התחלה טובה להרחבת פונקציית הרישום הבסיסית עם תכונות מתקדמות יותר.

לדוגמה, ייתכן שתשלב מספר תכונות הללו לפתרון רישום כולל:

Write-Log -Message "Critical error in payment processing" `
          -Level Error `
          -Format CSV `
          -NetworkPath "\\\\server\\logs" `
          -NotifyOnError "[email protected]","[email protected]" `
          -MaxLogFiles 90

זה י:

  • ירשום את השגיאה בפורמט CSV
  • יאחסן אותה במשותף על הרשת
  • ישלח דוא"ל למספר נמענים
  • ישמור 90 ימים של היסטוריית רישום

זכור לבדוק היטב, במיוחד בעת יישום נתיבי רשת או התראות דוא"ל, מכיוון שתלות חיצונית זו יכולה להשפיע על אמינות הסקריפט שלך. סקריפטינג מהנה!

Source:
https://adamtheautomator.com/powershell-write-log-tutorial/