Développer et distribuer le module Powershell
Malgré le fait que sur Internet, il existe des tonnes de guides et d'instructions variés sur la façon de créer votre propre module Powershell, après tout, même la documentation officielle ne donne pas une compréhension complète, comment créer correctement un module avec flexibilité\évolutivité pour un ajout facile de fonctions.
J'ai passé plusieurs heures à apprendre et à lire quelques articles, et, comme d'habitude, j'en suis venu à ma propre approche, qui me semble suffisamment confortable, élastique, et que je veux partager avec vous tous maintenant.
Trouvez le nom
C'est important :-). Plus tard avec ce nom vous vivrez assez longtemps, alors pensez au nom, qui sera agréable à voir pour vous tous les jours =).
Dans mon cas, j'ai décidé de suivre l'approche: <code_client\nom_client>.<code_projet>.Powershell.
Pour les besoins de ce guide, utilisons le nom de module My.OwnModule.Powershell.
Créer un préfixe pour les noms de fonction
Si vous développez/supportez/utilisez plusieurs modules à la fois (par exemple, pour différentes entreprises ou équipes), vous utiliserez parfois la même fonction dans tous les modules (juste parce que c'est pratique). Et, si vous commencez à utiliser ces modules, vous rencontrerez des conflits de noms lors de l'importation. C'est pourquoi il y a une raison pour laquelle vous devriez utiliser un préfixe unique pour les noms de fonctions.
Dans notre exemple, j'utiliserai le préfixe MyOwn. Par exemple, le nom standard de la célèbre applet de commande New-Item se transformera en New-MyOwnItem.
Installer les prérequis
À l'exception de Powershell lui-même, vous aurez besoin de l'outil de ligne de commande nuget. Il est nécessaire d'emballer le module dans un package nuget et de le distribuer à d'autres ordinateurs ou utilisateurs.
Créer une structure de dossiers
À l'exception du dossier racine, qui portera le même nom que le module, vous aurez besoin de la structure de dossier initiale.
D:.└───My.OwnModule.Powershell ├───images ├───private ├───public │ └───common └───_bin
- images. Il y aura un fichier d'icône pour un paquet, qui en théorie serait vu dans un référentiel comme Artifactory.
- private. C'est un dossier pour les scripts, qui ne doit être utilisé que pour les besoins du service. Par exemple, pour lire le fichier à partir du disque avec la gestion des erreurs.
- public. Ici, vous stockerez des fichiers de script avec des fonctions qui seront accessibles directement par les utilisateurs du module. Ici, vous pouvez regrouper vos scripts dans des sous-dossiers pour plus de commodité uniquement.
- public -> common. Ceci est un exemple de sous-dossier. Le répertoire est utilisé exclusivement à des fins de structure et de regroupement de fichiers. Tout ce qui se trouve dans le dossier public sera lu de manière récursive.
- _bin. L'outil Nuget placera les packages compilés ici.
Créer et remplir les fichiers nécessaires
Vous devez sûrement créer des fichiers qui, à proprement parler, convertissent un ensemble de scripts Powershell en module Powershell.
D:.│ LICENSE│ PSScriptAnalyzerSettings.psd1│ README.md│└───My.OwnModule.Powershell │ local-build.ps1 │ local-install.ps1 │ My.OwnModule.Powershell.nuspec │ My.OwnModule.Powershell.psd1 │ My.OwnModule.Powershell.psm1 │ ├───images │ icon.png │ ├───private │ _stub.ps1 │ ├───public │ └───common │ Read-MyOwnJsonFile.ps1 │ └───_bin
Nous nous intéressons aux fichiers situés dans le dossier racine du module, privé et public. Autres - sont les fichiers de service du référentiel git. Vous trouverez ci-dessous le contenu de chaque fichier avec des commentaires.
Ecriture des fichiers de service du module Powershell
My.OwnModule.Powershell.nuspec
Ceci est nécessaire pour que l'outil nuget génère le package.
<?xml version="1.0" encoding="utf-8"?>
<package >
<metadata>
<id>My.OwnModule.Powershell</id>
<version>0.0.2</version>
<authors>Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser. </authors>
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<icon>images\icon.png</icon>
<description>
There is no any description available at this time. Sorry for that.
</description>
<releaseNotes>Initial release.</releaseNotes>
<tags>PSEdition_Core PSEdition_Desktop Linux Mac PSModule PSIncludes_Cmdlet</tags>
</metadata>
</package>
My.OwnModule.Powershell.psd1
Ce fichier - est un manifeste de module, une description du module dans les termes de Powershell lui-même. Il existe différents détails sur l'auteur, les fonctions prises en charge par le module, etc.
Notez la ligne 11 et le paramètre FunctionsToExport. Ce sont des fonctions qui seront accessibles aux utilisateurs de votre module. C'est pourquoi, lors de l'ajout de nouvelles fonctions au module, pensez à les ajouter ici.
@{
RootModule = "My.OwnModule.Powershell.psm1"
ModuleVersion = "0.0.2"
CompatiblePSEditions = "Desktop", "Core"
GUID = "8f37ba7b-be77-4b6e-8ceb-d30c0c328674"
Author = "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser. "
PowerShellVersion = "7.0"
ScriptsToProcess = @();
FunctionsToExport = @(
"Read-MyOwnJsonFile"
);
CmdletsToExport = "*"
VariablesToExport = "*"
AliasesToExport = "*"
}
My.OwnModule.Powershell.psm1
Ce fichier est un script qui s'exécute lorsque vous exécutez (ou que le système exécute) Import-Module. C'est un fichier principal du module. De manière générale, ce fichier représente le module lui-même (ce qui signifie que vous pouvez créer le module Powershell sans le fichier psd1, mais non recommandé, bien sûr).
#Requires -Version 7.0
$public = @( Get-ChildItem -Path $PSScriptRoot\public\*.ps1 -Recurse; );
$private = @( Get-ChildItem -Path $PSScriptRoot\private\*.ps1 -Recurse; );
# Dot source the files
foreach ($import in @($public + $private))
{
try
{
Write-Verbose "Importing '$($import.FullName)'.";
. $import.FullName;
}
catch
{
Write-Error -Message "Failed to import function $($import.fullname): $_";
}
}
Export-ModuleMember -Function $public.Basename;_stub.ps1
J'ai mis ce fichier-stub, afin que le script du fichier psm1 soit capable de lire normalement le dossier sans problèmes possibles. Mais en général, il est complètement vide.
Read-MyOwnJsonFile.ps1
Ceci est un fichier de l'applet de commande, que nous fournissons avec notre module. Remarquez son nom - Read-MyOwnJsonFile, je veux dire ici que j'utilise un préfixe pour les noms de fonctions.
local-build.ps1
Ce fichier ne fait pas directement partie du module Powershell. C'est un script que j'utilise pour compiler le module dans un nuget-package, de sorte que je le place plus tard quelque part dans le référentiel. De plus, ce script incrémente la version du module de 1.
# Config
$moduleName = "My.OwnModule.Powershell";
# Clear old packages
# Get-ChildItem .\$moduleName\_bin | Remove-Item -Force -Verbose;
#region Get current package version and increment Patch
$version = Select-String -Path .\$moduleName\$moduleName.nuspec -Pattern "<version>(\d)\.(\d)\.(\d{1,})</version>";
[int]$majorVersion = $version | Select-Object @{name="version"; expression={$_.Matches.Groups[1].Value}} | select-object -ExpandProperty version;
[int]$minorVersion = $version | Select-Object @{name="version"; expression={$_.Matches.Groups[2].Value}} | select-object -ExpandProperty version;
[int]$patchVersion = $version | Select-Object @{name="version"; expression={$_.Matches.Groups[3].Value}} | select-object -ExpandProperty version;
$patchVersion++;
$nuspecVersionString = "<version>$majorVersion.$minorVersion.$patchVersion</version>";
$psd1VersionString = "ModuleVersion = `"$majorVersion.$minorVersion.$patchVersion`"";
#endregion /Get current package version and increment Patch
#region Update package version
$a = Get-Content -Path ".\$moduleName\$moduleName.nuspec" | %{$_ -replace "<version>(\d)\.(\d)\.(\d{1,})<\/version>", $nuspecVersionString };
$a | Out-File ".\$moduleName\$moduleName.nuspec" -Verbose;
$a = Get-Content -Path ".\$moduleName\$moduleName.psd1" | %{$_ -replace "ModuleVersion = `"\d\.\d.\d{1,}`"", $psd1VersionString };
$a | Out-File ".\$moduleName\$moduleName.psd1" -Verbose;
#endregion /Update package version
nuget pack ".\$moduleName\$moduleName.nuspec" -OutputDirectory .\$moduleName\_bin -Properties NoWarn=NU5111,NU5110,NU5100
$package = Get-ChildItem .\$moduleName\_bin\*.nupkg | Sort-Object -Property CreationTime | Select-Object -Last 1;
$packagelocal-install.ps1
Par conséquent, ce script personnalisé sert à installer le module.
$moduleName = "My.OwnModule.Powershell";
$repoName = "My.OwnModule.Powershell.Repository";
$repoPath = "D:\Private\My.OwnModule.Powershell\My.OwnModule.Powershell\_bin\";
Register-PSRepository -Name $repoName -SourceLocation $repoPath -InstallationPolicy Trusted -ScriptSourceLocation $repoPath;
Install-Module -Name $moduleName -Repository $repoName -Verbose;
Get-Module $moduleName -ListAvailable;Emballage du module Powershell
Essayons d'exécuter local-build.ps1 et voyons ce qui se passe.
Super! Nuget-package est prêt et poussé dans le dossier My.OwnModule.Powershell\_bin\My.OwnModule.Powershell.0.0.3.nupkg. Essayons maintenant d'installer le module à partir du package et de l'utiliser.
Installation du module Powershell à partir du package nuget
Merveilleux, le module est prêt à fonctionner !
Verbose dit que la version 0.0.5 a déjà été installée et ainsi de suite. C'est parce que j'ai essayé de réduire la version manuellement au lieu d'augmenter. Ne fais pas attention à ça.
Référentiel GitHub
Vous pouvez trouver tous ces fichiers dans mon référentiel GitHub: https://github.com/vicioussn/My.OwnModule.Powershell.
- Affichages : 365