PowerShell : Dépannage avec Exemples Pratiques

PowerShell est excellent pour l'automatisation, mais les échecs peuvent être opaques : texte d'erreur rouge sans détail, commandes natives qui échouent silencieusement, ou scripts qui passent localement mais cassent sur un autre hôte. Ce guide montre une méthode pratique et reproductible pour diagnostiquer et corriger les problèmes PowerShell avec un risque minimal. Vous apprendrez à inventorier les versions et l'environnement pour circonscrire les causes, appliquer des changements de configuration sûrs et limités que vous pouvez annuler, activer juste assez de journalisation pour voir ce qui se passe, reproduire les problèmes avec des commandes minimales, appliquer des récupérations étape par étape pour les échecs courants, et utiliser une liste de contrôle courte pour garder les opérations fiables. Commencez petit : pilotez un scénario localement, observez le résultat, puis généralisez. Cela garde le dépannage rapide et sûr.

Inventaire des Versions et de l'Environnement

Avant de changer quoi que ce soit, collectez les faits. Ces commandes sont sûres à exécuter en lecture seule. Les résultats attendus sont inclus pour que vous puissiez repérer les anomalies tôt.

Identifier la version et l'édition de PowerShell

$PSVersionTable | Format-List

Attendu : Un tableau avec PSVersion (par exemple, 5.1.x ou 7.x), PSEdition (Desktop ou Core), et les infos OS. Les différences entre Windows PowerShell 5.1 et PowerShell 7+ expliquent souvent les changements de comportement dans les modules, les encodages par défaut et la communication à distance.

Vérifier la stratégie d'exécution par portée

Get-ExecutionPolicy -List | Format-Table -AutoSize

Attendu : Une liste de stratégies (MachinePolicy, UserPolicy, Process, CurrentUser, LocalMachine). Une stratégie CurrentUser ou LocalMachine restrictive peut bloquer les scripts. La stratégie n'est pas une frontière de sécurité mais elle peut arrêter les scripts non signés ou distants.

Capturer les scripts de profil qui pourraient altérer le comportement

$profile | Format-List *
Test-Path $profile.AllUsersAllHosts, $profile.AllUsersCurrentHost, $profile.CurrentUserAllHosts, $profile.CurrentUserCurrentHost

Attendu : Chemins vers les fichiers de profil et Vrai/Faux pour leur existence. Les profils peuvent changer les préférences d'erreur, le chargement automatique des modules ou les chemins.

Enregistrer l'état et les chemins des modules

$env:PSModulePath -split ';'
Get-Module -ListAvailable | Select-Object Name, Version, Path | Sort-Object Name

Attendu : Chemins de recherche des modules et versions visibles. Plusieurs versions ou chemins masqués peuvent causer des importations inattendues.

Vérifier la disponibilité de la communication à distance (Windows)

Test-WSMan -ErrorAction SilentlyContinue

Attendu : Si la communication à distance est activée et accessible localement, retourne les détails WS-Management. Si absente, les tests de communication à distance échoueront par conception.

Confirmer le contexte du système de fichiers et du répertoire personnel

Get-Location
$ExecutionContext.SessionState.Path.CurrentFileSystemLocation

Attendu : Votre répertoire de travail. Beaucoup d'échecs sont des problèmes de chemins relatifs.

Indices de triage rapide

Chemin de Configuration Sûr

Appliquez le plus petit changement le plus réversible qui révèle le problème ou débloque l'exécution. Capturez toujours les valeurs actuelles, changez la portée vers Process quand c'est possible, puis rétablissez.

Préférer les changements de stratégie d'exécution limités au processus

Capturez les valeurs actuelles :

$ep = Get-ExecutionPolicy -List | Tee-Object -Variable ep | Out-String; $ep

Autorisez temporairement ce processus à exécuter des scripts :

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

Rétablissement : Fermez la session ou remettez la portée Process. Ne changez pas LocalMachine sauf si requis.

Utiliser WhatIf et Confirm pour simuler les actions destructives

Remove-Item C:\Temp\*.log -WhatIf

Attendu : Décrit ce qui serait supprimé sans faire de changements. Quand vous êtes confiant, retirez -WhatIf.

Rendre la gestion d'erreurs explicite

Pour les cmdlets, utilisez -ErrorAction Stop pour que try/catch fonctionne :

try {
    Copy-Item source.txt dest\ -ErrorAction Stop
} catch {
    $_ | Format-List * -Force
}

Pour les commandes natives, vérifiez $LASTEXITCODE :

& robocopy src dest /MIR /R:1 /W:1 | Out-Host
if ($LASTEXITCODE -gt 7) { throw "Robocopy a échoué avec le code $LASTEXITCODE" }

Journaliser seulement le nécessaire

Transcrivez une session interactive :

Start-Transcript -Path "$env:TEMP\ps-trace-$(Get-Date -Format yyyyMMdd-HHmmss).log" -IncludeInvocationHeader
# ...reproduisez le problème...
Stop-Transcript

Attendu : Un fichier avec commandes et sorties que vous pouvez inspecter ou joindre à un ticket.

Éviter les changements permanents de confiance aux dépôts

Installez un module pour l'utilisateur courant sans approuver globalement le dépôt :

Install-Module -Name Pester -Scope CurrentUser -Repository PSGallery -Force

Attendu : L'installation se poursuit après une invite de confiance interactive si nécessaire. Préférez la portée par utilisateur pour éviter les changements système.

Référence rapide des portées de changement sûr

Vérification et Diagnostics

Une correction n'est bonne que si vous pouvez la prouver. Utilisez ces approches pour rendre le succès observable et les régressions évidentes.

Reproduction minimale

Remplacez les pipelines complexes par la plus petite commande qui échoue encore. Exemple : si un script casse à Get-Content, lancez Get-Content seul avec -LiteralPath pour écarter les problèmes de guillemets et de caractères génériques :

Get-Content -LiteralPath 'C:\Data\input [final].txt' -ErrorAction Stop

Détail d'erreur riche

PowerShell 7+ :

Get-Error -Newest 1

Attendu : Une vue détaillée incluant les exceptions internes et les enregistrements d'erreur.

Windows PowerShell 5.1 :

$Error[0] | Format-List * -Force

Découverte des paramètres

(Get-Command Copy-Item).Parameters.GetEnumerator() | Sort-Object Key | Format-Table Key, Value

Attendu : Noms des jeux de paramètres et types, à comparer avec vos entrées.

Assertion des sorties

Utilisez des tests pour vérifier les effets de bord :

$dest = 'C:\Out\report.csv'
.\build-report.ps1 -OutFile $dest -ErrorAction Stop
Test-Path $dest | Should -BeTrue  # Remplacez par votre méthode d'assertion

Si vous n'utilisez pas de framework de test, des gardes simples aident :

if (-not (Test-Path $dest)) { throw "Rapport non généré à $dest" }

Journaux d'événements et canaux opérationnels (Windows)

Journaux Windows PowerShell :

Get-WinEvent -LogName 'Windows PowerShell' -MaxEvents 20 | Format-Table TimeCreated, Id, Message -AutoSize
Get-WinEvent -LogName 'Microsoft-Windows-PowerShell/Operational' -MaxEvents 20 | Format-Table TimeCreated, Id, Message -AutoSize

PowerShell 7+ (si présent) :

Get-WinEvent -LogName 'PowerShellCore/Operational' -MaxEvents 20 | Format-Table TimeCreated, Id, Message -AutoSize

Attendu : Démarrages/arrêts récents du moteur (400/403/600) et messages opérationnels de blocs de script si activés.

Activer la journalisation de blocs de script temporairement (Windows)

Préférez la stratégie de groupe. Si vous devez activer rapidement sur une machine de test, capturez l'état actuel et remettez-le après.

# Capturer l'existant
$regPath = 'HKLM:\SOFTWARE\Microsoft\Windows\PowerShell\3\ScriptBlockLogging'
$existing = if (Test-Path $regPath) { Get-ItemProperty $regPath } else { $null }

# Activer
New-Item -Path $regPath -Force | Out-Null
New-ItemProperty -Path $regPath -Name EnableScriptBlockLogging -Value 1 -PropertyType DWord -Force | Out-Null

# Reproduire le problème, puis inspecter les logs dans les canaux opérationnels

# Rétablissement (restaurer ou désactiver)
if ($existing) {
    Set-ItemProperty -Path $regPath -Name EnableScriptBlockLogging -Value $existing.EnableScriptBlockLogging
} else {
    Remove-Item $regPath -Recurse -Force
}

Notes pour systèmes non-Windows

Utilisez les transcriptions et la capture stdout/stderr. Quand les scripts sont lancés par des planificateurs (cron, launchd, minuteurs systemd), vérifiez leurs journaux respectifs (par exemple, journalctl pour un minuteur systemd) pour le processus wrapper ; combinez cela avec votre transcription PowerShell et les vérifications $LASTEXITCODE.

Aperçu des sources de logs

Modes d'Échec et Récupération

Cette section donne des remédiations étape par étape avec vérification et rétablissement.

1) Stratégie d'exécution bloque le script

Symptôme : Erreur rouge comme "ne peut pas être chargé car l'exécution de scripts est désactivée" ou un .ps1 d'internet est bloqué.

Remédiation (temporaire et sûre) :

# Afficher les stratégies
Get-ExecutionPolicy -List | Format-Table -AutoSize

# Autoriser le processus courant seulement
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

# Si le fichier est marqué comme venant d'internet
Unblock-File .\script.ps1

# Relancer le script
.\script.ps1 -Verbose

Vérification : Le script s'exécute ; plus d'erreur de stratégie d'exécution.

Rétablissement : La fermeture de la session rétablit automatiquement la portée Process. Aucun changement permanent.

Si vous devez persister pour votre utilisateur : envisagez RemoteSigned à la portée CurrentUser, mais enregistrez d'abord les valeurs précédentes et obtenez l'approbation dans votre organisation.

2) Le terme 'X' n'est pas reconnu

Symptôme : La commande n'existe pas dans la session.

Remédiation :

# Est-ce un cmdlet/alias/fonction ?
Get-Command X -All

# Est-ce un module qui s'importe automatiquement ?
$PSModuleAutoLoadingPreference
Get-Module -ListAvailable | Where-Object Name -Like '*X*' | Select Name, Version, Path

# Essayer l'import explicite
Import-Module X -ErrorAction Stop

# Si manquant, installer par utilisateur
Install-Module X -Scope CurrentUser -Repository PSGallery -Force

# Pour les exécutables natifs, vérifier PATH
$env:PATH -split ';' | Where-Object { $_ -match 'X' }

Vérification : Get-Command X retourne la définition et le chemin attendus.

Rétablissement : Si l'import d'un module cause des effets de bord, supprimez-le :

Remove-Module X -Force

3) ParameterBindingException ou mauvais types d'entrée

Symptôme : Erreurs sur les jeux de paramètres, paramètres obligatoires manquants, ou conversion de type.

Remédiation :

# Inspecter les paramètres et jeux
(Get-Command Invoke-RestMethod).ParameterSets | Select Name, Parameters

# Afficher l'aide avec exemples
Get-Help Invoke-RestMethod -Detailed

# Forcer les erreurs dans les blocs catch
try {
    Invoke-RestMethod -Uri $u -Method Post -Body $b -ErrorAction Stop
} catch {
    $_ | Format-List * -Force
}

Vérification : La commande sélectionne le jeu de paramètres voulu ; plus d'erreurs de liaison.

Rétablissement : Aucun nécessaire ; c'est une correction d'usage. Gardez l'exemple minimal dans la documentation ou les commentaires du script pour référence future.

4) Surprises de chemin, guillemets et caractères génériques

Symptôme : Fichier non trouvé, ou caractères génériques se développent inattendu.

Remédiation :

# Utiliser -LiteralPath pour éviter l'expansion des caractères génériques
Remove-Item -LiteralPath 'C:\data\[2026]\*' -WhatIf

# Résoudre en chemin absolu tôt
$root = Split-Path -Parent $MyInvocation.MyCommand.Path  # dans les scripts
$in = Join-Path $root 'input [final].txt'
Test-Path -LiteralPath $in

Vérification : Test-Path retourne Vrai pour le fichier visé ; WhatIf décrit seulement les éléments attendus.

Rétablissement : Aucun ; conservez -LiteralPath dans les opérations de fichiers critiques.

5) Outils natifs échouent silencieusement

Symptôme : Un exécutable natif écrit sur stderr mais le pipeline PowerShell continue.

Remédiation :

# Capturer sortie et codes de sortie
& some.exe /arg1 2>&1 | Tee-Object -Variable nativeOut | Out-Host
if ($LASTEXITCODE -ne 0) {
    $nativeOut | Out-String | Write-Error
    throw "some.exe a échoué avec le code de sortie $LASTEXITCODE"
}

Vérification : En cas d'échec, le script lance une exception ; en cas de succès, $LASTEXITCODE vaut 0.

Rétablissement : Si le comportement d'échec strict est trop agressif pour un travail par lots, rétrogradez vers des avertissements mais enregistrez quand même $LASTEXITCODE et stderr dans un fichier de log.

6) Problèmes de communication à distance et réseau

Symptôme : Enter-PSSession ou Invoke-Command échoue ; WinRM non configuré ou bloqué.

Remédiation (Windows) :

# Valider WS-Man localement
Test-WSMan

# Activer la communication à distance sur une machine de test (admin)
Enable-PSRemoting -Force

# Tester une session en boucle locale
Invoke-Command -ComputerName localhost -ScriptBlock { $PSVersionTable }

Vérification : Test-WSMan réussit et Invoke-Command retourne un PSVersionTable.

Rétablissement : Désactivez sur une machine de test si plus nécessaire :

Disable-PSRemoting -Force

Vérifiez aussi le profil réseau et les règles de pare-feu dans votre politique d'environnement avant d'activer sur des hôtes de production.

7) Incompatibilités d'encodage et de contenu

Symptôme : Fichier créé par Windows PowerShell illisible par un autre outil ou par PowerShell 7 ; caractères inattendus.

Remédiation :

# Rendre l'encodage explicite
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[Console]::OutputEncoding = $utf8NoBom

Set-Content -Path .\out.txt -Value $data -Encoding UTF8
Get-Content -Path .\out.txt -Encoding UTF8 | Out-Host

Vérification : Les outils en aval lisent le fichier correctement ; les allers-retours préservent les caractères.

Rétablissement : Si un partenaire spécifique exige UTF16LE, définissez -Encoding Unicode pour cette intégration et documentez-le.

8) Effets de bord des profils

Symptôme : Les scripts se comportent différemment dans ISE, VS Code, ou tâches planifiées comparé à la console.

Remédiation :

# Contourner les profils temporairement
powershell.exe -NoProfile -File .\script.ps1
pwsh.exe -NoProfile -File .\script.ps1

# Ou renommer le profil utilisateur pour isoler
Rename-Item -LiteralPath $profile.CurrentUserAllHosts -NewName ($profile.CurrentUserAllHosts + '.bak') -ErrorAction SilentlyContinue

Vérification : Le comportement se stabilise sans profils. Différez le .bak pour trouver les changements.

Rétablissement :

# Restaurer le nom de fichier du profil
if (Test-Path ($profile.CurrentUserAllHosts + '.bak')) {
    Move-Item ($profile.CurrentUserAllHosts + '.bak') $profile.CurrentUserAllHosts -Force
}

Liste de Contrôle Opérationnelle

Utilisez cette liste courte pour garder le dépannage cohérent et sûr.

1. Inventorier

• $PSVersionTable, édition, OS hôte
• Get-ExecutionPolicy -List
• Profils présents ? Test-Path $profile.*
• Chemins et versions des modules

2. Isoler

• Reproduire avec une commande minimale
• Exécuter avec -NoProfile
• Utiliser -LiteralPath et chemins absolus

3. Journaliser minimalement

• Start-Transcript
• Capturer $LASTEXITCODE pour outils natifs
• Sur Windows, lire les journaux opérationnels (ne pas sur-collecter)

4. Appliquer des corrections limitées

• Préférer -Scope Process pour la stratégie
• Utiliser -ErrorAction Stop et try/catch
• Utiliser -WhatIf et -Confirm avant changements

5. Vérifier

• Assertion codes de sortie et Test-Path
• Inspecter Get-Error ou $Error[0]
• Confirmer que seuls les effets de bord attendus ont eu lieu

6. Rétablir

• Stop-Transcript ; archiver les logs
• Rétablir les changements de registre temporaires s'il y en a
• Restaurer les noms de profils ; fermer la session pour abandonner la portée Process

7. Documenter

• Garder l'exemple minimal d'échec et la correction exacte pour le prochain incident

Conclusion

Le dépannage PowerShell devient prévisible quand vous rassemblez les faits d'abord, changez seulement ce qui est nécessaire, et prouvez le résultat. Commencez avec un scénario étroit et mesurable sur votre machine locale, confirmez le résultat avec transcriptions et assertions, puis déployez la correction dans un usage plus large. Gardez les changements limités au processus, rendez la gestion d'erreurs explicite, et fiez-vous à une journalisation minimale et ciblée. Cette approche réduit le retravail et rend les futurs incidents plus rapides à résoudre.