Julien Ref Powershell

PowerShell - Conventions de Nommage et Organisation

Vue d'Ensemble

Observability

First: At the start of execution, display:

🔧 Skill "julien-ref-powershell" activated

Ce document définit les conventions de nommage et d'organisation pour les projets PowerShell, garantissant cohérence, maintenabilité et scalabilité.

Structure d'Organisation Générique

Structure de Base

PowerShell-Project/
├── Core/                    # Scripts essentiels et infrastructure
├── Modules/                 # Modules PowerShell organisés
├── Scripts/                 # Scripts par domaine fonctionnel
│   ├── Administration/      # Scripts d'administration système
│   ├── Development/         # Outils de développement
│   ├── Network/            # Scripts réseau
│   ├── Security/           # Scripts sécurité
│   └── Utilities/          # Utilitaires génériques
├── Config/                  # Fichiers de configuration
├── Templates/               # Templates et modèles
├── Tests/                   # Tests automatisés
├── Docs/                    # Documentation
└── Resources/               # Ressources (JSON, XML, etc.)

Conventions de Nommage

1. Fichiers PowerShell

Scripts (.ps1)

Format : Verb-Noun-Context.ps1

# CORRECT
Get-SystemInfo.ps1
Set-EnvironmentPath.ps1
Start-ServiceMonitor.ps1
Remove-TempFiles.ps1
Test-NetworkConnectivity.ps1
Backup-UserProfiles.ps1

# ÉVITER
get_system_info.ps1          # snake_case
systemInfo.ps1               # camelCase
SystemInformationScript.ps1  # trop long
sys-info.ps1                 # pas descriptif
GetSysInfo.ps1              # PascalCase sans tiret

Modules (.psm1)

Format : ModuleName.psm1 (PascalCase)

# CORRECT
SystemAdministration.psm1
NetworkUtilities.psm1
SecurityTools.psm1
DatabaseConnector.psm1

# ÉVITER
system_admin.psm1
networkUtils.psm1
security-tools.psm1

2. Fonctions PowerShell

Convention Standard PowerShell

Format : Verb-Noun (verbes approuvés PowerShell)

# CORRECT - Verbes approuvés
function Get-UserPermissions { }
function Set-NetworkConfiguration { }
function Start-BackupProcess { }
function Stop-RunningServices { }
function Test-DatabaseConnection { }
function New-SecurityPolicy { }
function Remove-TempDirectories { }
function Update-SystemConfiguration { }

# ÉVITER - Verbes non-standard
function Fetch-UserData { }         # Utiliser Get-
function Configure-Network { }      # Utiliser Set-
function Launch-Application { }     # Utiliser Start-
function Destroy-TempFiles { }      # Utiliser Remove-

Verbes PowerShell Approuvés par Catégorie

Données :

• Get-, Set-, Clear-, Copy-, Move-, Remove-

Lifecycle :

• New-, Start-, Stop-, Restart-, Suspend-, Resume-

Diagnostic :

• Test-, Trace-, Measure-, Debug-, Repair-

Sécurité :

• Block-, Grant-, Revoke-, Protect-, Unprotect-

Changements :

• Add-, Update-, Install-, Uninstall-, Register-, Unregister-

3. Variables

Variables Locales

Format : camelCase

# CORRECT
$userName = "admin"
$connectionString = "Server=localhost"
$maxRetryCount = 3
$isConfigurationValid = $true
$systemServices = Get-Service

# ÉVITER
$UserName = "admin"              # PascalCase pour locales
$connection_string = "..."       # snake_case
$max-retry-count = 3            # kebab-case

Variables Globales

Format : PascalCase avec préfixe explicite

# CORRECT
$Global:ApplicationSettings = @{}
$Global:ModuleConfiguration = @{}
$Global:SystemEnvironment = @{}
$Script:ModulePrivateData = @{}

# ÉVITER
$Global:settings = @{}           # camelCase pour globales
$appConfig = @{}                 # sans préfixe Global

Variables d'Environnement

Format : UPPER_CASE

# CORRECT
$env:POWERSHELL_PROFILE_LOADED = "1"
$env:APPLICATION_LOG_LEVEL = "INFO"
$env:DATABASE_CONNECTION_TIMEOUT = "30"

4. Paramètres de Fonctions

Format : PascalCase

function Get-UserInformation {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$UserName,

        [Parameter(Mandatory = $false)]
        [string]$DomainName = "localhost",

        [switch]$IncludeGroups,

        [ValidateRange(1, 100)]
        [int]$MaxResults = 50
    )
}

5. Alias

Format : [Domaine][Action] (2-4 caractères)

# Navigation
Set-Alias -Name "nf" -Value "Navigate-ToFolder"
Set-Alias -Name "nh" -Value "Navigate-ToHome"

# Recherche
Set-Alias -Name "sf" -Value "Search-Files"
Set-Alias -Name "sc" -Value "Search-Content"

# Système
Set-Alias -Name "ss" -Value "Show-SystemStatus"
Set-Alias -Name "sl" -Value "Show-SystemLogs"

6. Constantes

Format : UPPER_CASE avec préfixe de module

$MODULE_VERSION = "1.0.0"
$DEFAULT_TIMEOUT = 30
$MAX_RETRY_ATTEMPTS = 3
$LOG_LEVEL_DEBUG = "DEBUG"

Documentation Standard

En-tête de Script

<#
.SYNOPSIS
    Description courte et précise du script (max 80 caractères)

.DESCRIPTION
    Description détaillée du script, de son fonctionnement et de ses objectifs.
    Explique les dépendances, les prérequis et les effets de bord.

.PARAMETER ParameterName
    Description détaillée du paramètre et de son utilisation

.EXAMPLE
    Script-Name -Parameter "Value"
    Description du résultat attendu

.NOTES
    Author: Nom de l'auteur
    Version: X.Y.Z
    Created: YYYY-MM-DD
    Last Updated: YYYY-MM-DD
    Dependencies: Liste des dépendances requises
#>

Validation et Tests

Checklist de Validation

• Nommage respecte les conventions Verb-Noun
• Variables suivent les conventions de casse
• Documentation complète avec exemples
• Gestion d'erreur implémentée
• Tests unitaires présents
• Performance acceptable
• Sécurité validée

Obtenir les Verbes Approuvés

# Obtenir la liste complète des verbes approuvés
Get-Verb | Sort-Object Verb | Format-Table -AutoSize

# Vérifier si un verbe est approuvé
$verb = "Configure"
if ($verb -notin (Get-Verb).Verb) {
    Write-Warning "Verbe non-standard: $verb"
    Write-Host "Verbes suggérés: Set, Update, Install"
}

Outils de Formatage

• PSScriptAnalyzer : Analyse statique et conventions
• Plaster : Templates de projets PowerShell
• Pester : Framework de tests
• PowerShell-Beautifier : Formatage automatique