cadjou
f9ef170872
- Interface bilingue FR/EN - Auto-mise à jour - Fenêtre unique avec logs intégrés - liste par badges - README bilingue
127 lines
4.0 KiB
Markdown
127 lines
4.0 KiB
Markdown
# Guide de conception de scripts pour cadMasterCLI
|
|
|
|
Ce guide décrit les règles minimales pour qu'un script PowerShell soit correctement reconnu et piloté par cadMasterCLI : détection des paramètres, affichage de l'aide, types lisibles, etc.
|
|
|
|
---
|
|
|
|
## Règles minimales
|
|
|
|
### 1. Comment-based help obligatoire
|
|
|
|
Le script **doit** avoir un bloc `.SYNOPSIS` et un bloc `.PARAMETER` pour **chaque paramètre**.
|
|
cadMasterCLI lit ces blocs via `Get-Help` pour afficher les descriptions dans l'interface (bouton "Voir l'aide").
|
|
|
|
```powershell
|
|
<#
|
|
.SYNOPSIS
|
|
Courte description en une ligne (affichée dans la liste de sélection).
|
|
|
|
.PARAMETER MonParam
|
|
Description claire de ce que fait ce paramètre, ses valeurs attendues,
|
|
son impact sur l'exécution du script.
|
|
#>
|
|
```
|
|
|
|
### 2. Bloc `param()` avec types et ValidateSet
|
|
|
|
- **Toujours typer** les paramètres : `[string]`, `[int]`, `[double]`, `[switch]`...
|
|
- **Utiliser `[ValidateSet(...)]`** pour les paramètres à choix limité — cadMasterCLI affichera automatiquement des **RadioButtons**.
|
|
- **Marquer les paramètres obligatoires** avec `[Parameter(Mandatory)]`.
|
|
|
|
```powershell
|
|
param(
|
|
[Parameter(Mandatory)]
|
|
[ValidateSet("Read", "Write")]
|
|
[string]$Action,
|
|
|
|
[Parameter(Mandatory)]
|
|
[string]$CsvInput,
|
|
|
|
[string]$Username = "admin"
|
|
)
|
|
```
|
|
|
|
### 3. Nommage des paramètres fichier/CSV
|
|
|
|
cadMasterCLI détecte automatiquement un paramètre comme **fichier** et affiche un bouton "Parcourir" si le nom contient l'un des mots-clés suivants :
|
|
|
|
| Mot-clé | Exemple de paramètre |
|
|
|---|---|
|
|
| `Path` | `$OutputPath` |
|
|
| `File` | `$InputFile` |
|
|
| `Csv` | `$CsvExport` |
|
|
| `Input` | `$CsvInput` |
|
|
| `Output` | `$OutputFile` |
|
|
|
|
Si le nom contient `Csv` ou `Input`, une zone de collage d'IPs avec conversion automatique en CSV est également proposée.
|
|
|
|
### 4. README bilingue FR/EN
|
|
|
|
Depuis cadMasterCLI v2, l'interface peut s'afficher en français ou en anglais. Pour que la documentation du script (panneau de gauche) suive la langue active, le `README.md` du dépôt peut contenir les deux versions dans un seul fichier, séparées par des marqueurs HTML :
|
|
|
|
```markdown
|
|
<!-- FR -->
|
|
# Nom du script
|
|
|
|
Description en français...
|
|
|
|
## Paramètres
|
|
|
|
- `MonParam` : ce que fait ce paramètre.
|
|
|
|
<!-- EN -->
|
|
# Script name
|
|
|
|
Description in English...
|
|
|
|
## Parameters
|
|
|
|
- `MonParam`: what this parameter does.
|
|
```
|
|
|
|
Règles :
|
|
|
|
- Les marqueurs `<!-- FR -->` et `<!-- EN -->` doivent être seuls sur leur ligne.
|
|
- L'ordre des sections n'a pas d'importance.
|
|
- Si une seule des deux langues est présente, cadMasterCLI l'affiche quelle que soit la langue active (pas d'erreur).
|
|
- **Rétro-compatibilité** : un `README.md` sans aucun marqueur continue de s'afficher tel quel dans les deux langues (comportement identique aux versions précédentes de cadMasterCLI).
|
|
|
|
Voir `_template_script.README.md` dans ce dépôt pour un exemple complet.
|
|
|
|
### 5. Structure du dépôt Gitea
|
|
|
|
Le dépôt doit contenir à sa racine :
|
|
|
|
```
|
|
MonScript/
|
|
├── MonScript.ps1 ← script principal (nom identique au dépôt recommandé)
|
|
├── README.md ← documentation affichée dans cadMasterCLI avant exécution
|
|
└── modules/ ← (optionnel) modules PowerShell importés par le script
|
|
└── MonModule.psm1
|
|
```
|
|
|
|
> cadMasterCLI télécharge tout le dépôt récursivement : les modules, configs et fichiers annexes sont préservés.
|
|
|
|
---
|
|
|
|
## Types reconnus et leur affichage
|
|
|
|
| Type PowerShell | Affiché dans l'interface |
|
|
|---|---|
|
|
| `[string]` | Texte |
|
|
| `[int]` / `[int32]` / `[int64]` | Nombre entier |
|
|
| `[double]` / `[single]` | Nombre décimal |
|
|
| `[bool]` | Vrai/Faux |
|
|
| `[datetime]` | Date |
|
|
| `[System.IO.FileInfo]` | Fichier |
|
|
| `[switch]` | Case à cocher |
|
|
| `[ValidateSet(...)]` | RadioButtons (un bouton par valeur) |
|
|
|
|
---
|
|
|
|
## Exemple minimal conforme
|
|
|
|
Voir `_template_script.ps1` (script) et `_template_script.README.md` (documentation bilingue) dans ce dépôt pour un squelette prêt à l'emploi.
|
|
|
|
Pour un exemple complet et fonctionnel, voir le script **DaliACLI**.
|