Adam the Automator

Lucrul cu modulele PowerShell este o parte importantă a automatizării PowerShell. Când începeți să învățați PowerShell, primii pași sunt, de obicei, utilizarea comenzilor unice. Acest lucru duce la construirea de scripturi care apoi duce la construirea de funcții.

Prin utilizarea funcțiilor, puteți face scripturile dvs. mai modulare. Acest lucru vă permite să puteți utiliza același cod în mai multe locuri fără a copia și lipi la cod peste tot. Folosirea funcțiilor vă permite să petreceți mai puțin timp făcând aceeași modificare a aceluiași cod peste tot unde este folosit. În schimb, puteți lucra la îmbunătățirea codului dvs. într-un singur loc.

Pentru a duce funcțiile la nivelul următor, puteți combina aceste funcții împreună într-un modul.

Un modul este o colecție de funcții într-un fișier text cu extensia psm1. Există unele adăugiri opționale, cum ar fi un manifest al modulului și un ajutor bazat pe comentarii sau extern, care pot fi, de asemenea, incluse. Acestea vor fi abordate mai târziu.

Precondiții

În acest articol voi folosi Windows PowerShell 5.1. Dacă utilizați o versiune mai veche sau PowerShell Core, kilometrajul poate varia în ceea ce privește rezultatele pe care le vedeți.

Interacțiunea cu modulele

După ce deschideți pentru prima dată o sesiune PowerShell, veți începe cu două module. Primul este Microsoft.PowerShell.Utility care conține multe funcții PowerShell de bază pe care le folosiți deja. Celălalt modul este PSReadline. Puteți vedea aceste module de pornire folosind comanda Get-Module.

Aceasta spus, aceasta nu este o listă completă a tuturor modulelor disponibile. Încă de la PowerShell 3, modulele care sunt instalate vor fi importate în funcție de necesități. Dacă executați o versiune mai veche de PowerShell, va trebui să utilizați comanda Import-Module pentru a importa mai întâi modulul înainte de a utiliza oricare dintre comenzi.

Există momente în care veți dori în continuare să utilizați Import-Module chiar și în versiunile ulterioare. Dacă ați dori să importați un modul după ce acesta este deja instalat, puteți utiliza Import-Module astfel:

În timp ce Get-Module va afișa toate modulele care sunt importate, nu veți vedea modulele care nu au fost încă importate. Puteți utiliza apoi parametrul ListAvailable pentru a afișa toate celelalte module care sunt disponibile.

Nu toate comenzile sunt afișate în mod implicit

Proprietatea ExportedCommands conține o listă a tuturor comenzilor disponibile care sunt exportate din modul. Este posibil să observați unele diferențe între această listă și ceea ce se află în fișierul modulului. Comenzile exportate reprezintă o caracteristică încorporată în manifestul modulului care permite autorului să lase o funcție ca fiind ascunsă. Autorii modulelor pot utiliza, de asemenea, cmdlet-ul Export-ModuleMember, dar acest lucru nu face parte din domeniul de aplicare al acestui articol.

Autorii modulelor pot dori ca o funcție să fie ascunsă deoarece este menită să sprijine alte funcții, nu să fie orientată către utilizator. Pentru ca o funcție să fie ascunsă, autorul ar trebui să o excludă din matricea FunctionsToExport din manifest. Aici puteți vedea o vedere extinsă a proprietății ExportedCommands.

Importul modulelor

Există mai multe moduri de a începe să folosiți modulele. Puteți importa manual modulul folosind calea către fișierele modulului. Acest lucru vă permite să puteți testa și actualiza modulul fără a fi nevoie să faceți multă muncă. Dar acest lucru nu permite o portabilitate prea mare, deoarece ar trebui să folosiți calea exactă către modul. De asemenea, PowerShell nu va importa automat modulele care nu se află în variabila $env:PSModulePath.

Importarea selectivă a comenzilor

Puteți utiliza Import-Module pentru a importa doar anumite funcții specifice în loc de întregul modul prin utilizarea parametrului Function. Acest lucru poate economisi timp atunci când se importă module din sisteme la distanță, cum ar fi modulele Office 365.

All User Modules

Modulele instalate pentru toți utilizatorii sunt plasate în C:\Program Files\WindowsPowerShell\Modules. Acest director conține multe module pre-adăugate, inclusiv orice module instalate cu Install-Module folosind domeniul de aplicare implicit AllUsers.

Current User Modules

Dacă instalați un modul, dar doriți ca doar un singur utilizator să îl folosească, există un domeniu de aplicare CurrentUser. Acest lucru plasează fișierele modulului în dosarul Documents la C:\Users\<username>\Documents\WindowsPowerShell\Modules. Acest lucru poate fi util într-un mediu în care utilizați redirecționarea dosarelor cu dosarul Documents.

În acest caz, puteți instala un modul pe un calculator și îl puteți utiliza pe un altul, deoarece ambele ar împărți același dosar Documents.

Module de sistem

Pentru a fi complet, există, de asemenea, un director de module la C:\Windows\System32\WindowsPowerShell\1.0\Modules. Deși, din punct de vedere tehnic, un modul plasat în această cale ar fi importat la fel ca una dintre celelalte căi, dar nu este recomandat, deoarece aceasta este rezervată pentru modulele de sistem Microsoft.

Denumirea este importantă

Puteți plasa manual modulul dumneavoastră într-una dintre aceste căi pentru a-l face disponibil în mod implicit cu o nouă sesiune, dar trebuie să vă asigurați că respectați denumirea necesară pentru module. Dosarul în care sunt plasate fișierele modulului trebuie să aibă același nume ca și fișierul modulului psm1 și manifestul modulului psd1, dacă există unul.

Utilizarea Get-Module -ListAvailable pe care am menționat-o anterior face referire la aceste căi. Puteți vedea toate căile modulelor folosind $env:PSModulePath -Split ';'. Este posibil să observați în listă și alte căi decât cele afișate aici. Multe programe își adaugă propriile căi de acces la module atunci când sunt instalate. Unul dintre exemple este SQL, care are propriile module incluse în propriile căi de acces la module.

Există, de asemenea, unele module pe care le veți instala cu un proces diferit. Unul dintre cele mai semnificative exemple în acest sens este modulul ActiveDirectory. De la Windows 7 până la Windows 10 1803, ați instala acest modul cu programul de instalare Remote Server Administration Tools (RSAT).

La versiunile mai noi de Windows 10 (1809+), acesta este disponibil numai prin Features On Demand. Instalarea RSAT instalează modulele ActiveDirectory și multe altele pe care le-ați utiliza pentru a administra alte roluri Windows. Pe sistemele de operare pentru servere Windows, aceste module sunt instalate prin Server Manager.

Importul modulelor la distanță (Implicit Remoting)

Există unele cazuri în care nu este practic să aveți un modul care să ruleze local. În schimb, este mai bine să vă conectați la un dispozitiv la distanță și să importați un modul instalat pe acesta. Atunci când faceți acest lucru, comenzile sunt de fapt executate pe aparatul de la distanță. Acest lucru este utilizat frecvent cu modulele Microsoft Office 365. Multe dintre acestea se conectează la un server Office 365 care apoi importă un modul. Când executați oricare dintre comenzi, acestea sunt executate pe serverul de la distanță și apoi rezultatul este trimis înapoi în sesiunea dumneavoastră.

O altă utilizare a importului modulelor de la distanță este atunci când nu aveți modulul instalat local. Aceasta este ceea ce ați obține dacă nu ați avea modulul ActiveDirectory instalat, dar ați încercat să-l importați.

Pentru a importa un modul de la distanță, trebuie mai întâi să creați un PSSession. Puteți utiliza New-PSSession pentru a crea sesiunea. Apoi, veți importa modulul disponibil pe dispozitivul de la distanță folosind parametrul PSSession cu Import-Module.

PS51> $AdminServer = New-PSSession -ComputerName $AdminServerName -Credential (Get-Credential)PS51> Import-Module -Name ActiveDirectory -PSSession $AdminServer -Prefix 'Rmt'

Utilizarea acestei metode de import al modulelor de la distanță permite o execuție mai rapidă a codului într-un mediu distribuit. De exemplu, dacă lucrați de pe computerul dumneavoastră, dar serverele pe care lucrați se află în cealaltă parte a SUA, ar putea dura semnificativ mai mult timp pentru a executa anumite comenzi la nivel local împotriva serverelor. În timp ce rularea comenzilor pe un server și alimentarea ieșirii înapoi în sesiunea locală este mult mai rapidă.

Adăugarea unui prefix de modul

De asemenea, puteți adăuga un prefix pe funcțiile importate de pe mașina de la distanță. Această opțiune este disponibilă în timpul importării modulelor locale, dar este rareori folosită în afara testării unor versiuni diferite ale unui modul unul lângă altul.

Dacă ați rulat comanda de import de mai sus și iată ce ați vedea când vă uitați la comenzi:

În acest caz, puteți folosi un prefix pentru a arăta că nu este un modul local. Acest lucru poate fi utilizat în cazurile în care importați un modul care este disponibil și la nivel local. Adăugarea prefixului reduce confuzia cu privire la locul în care se execută codul.

Eliminarea modulelor

De asemenea, puteți elimina un modul din sesiunea curentă fără a utiliza Remove-Module. Acest lucru elimină un modul din sesiunea locală fără a elimina fișierele modulului. Este posibil să doriți să utilizați acest lucru în cazul în care ați folosit o sesiune la distanță pentru a utiliza un modul. Ați putea utiliza Remove-Module pentru a vă curăța sesiunea și apoi să deconectați sesiunea de la distanță.

O altă utilizare a Remove-Module este în cazul în care faceți modificări la un modul și nu doriți să lansați o nouă sesiune PowerShell. În acest caz, veți folosi Remove-Module urmat de Import-Module pentru a-l reîncărca în sesiune. Alternativ, puteți utiliza parametrul Force cu Import-Module. Acest lucru va finaliza descărcarea și reîncărcarea modulului pentru dvs.

Ce compune un modul PowerShell

Un modul poate fi format din unul sau mai multe fișiere. Pentru a îndeplini cerințele minime pentru un modul, trebuie să aveți un fișier de modul. Acesta poate fi un fișier PSM1 sau orice alt fișier de modul, cum ar fi un fișier de modul binar. Pentru a construi pe baza acestuia, psm1-ul dvs. ar trebui să aibă funcții definite în el, altfel nu va fi de mare folos nimănui.

În timp ce nu există cerințe privind modul în care ar trebui să arate funcțiile sau ce ar trebui să facă, există câteva linii directoare. De obicei, este de preferat ca toate funcțiile dintr-un modul să fie construite în jurul aceluiași concept.

Modulele conțin funcții asemănătoare

De exemplu, modulul ActiveDirectory include numai funcții care interacționează cu Active Directory într-un anumit fel. De obicei, numele funcțiilor conțin și un prefix. Revenind la modulul ActiveDirectory ca exemplu, toate substantivele din numele funcțiilor încep cu AD.

Utilizarea acestor orientări ajută la descoperirea funcțiilor. Imaginați-vă că tocmai ați importat acest nou modul și doriți să parcurgeți funcțiile. Acest lucru este mult mai ușor de făcut dacă toate funcțiile au o structură de nume similară. Deși este posibil să vedeți frecvent module care încep cu PS, acest prefix este rezervat oficial doar pentru modulele Microsoft. Probabil că nu veți cauza o problemă dacă folosiți PS la începutul modulului dumneavoastră, s-ar putea să creați un conflict cu un alt nume de modul.

Utilizând aceste linii directoare, dacă ați avea o grămadă de funcții care au toate legătură cu interacțiunea cu registrul, ați putea avea ceva de genul:

function Get-ATARegistryKey {...}function Set-ATARegistryKey {...}

Manifestări de module

Pentru a construi pe baza fișierului de module text, puteți include, de asemenea, un manifest de module. Aceste fișiere au o extensie PSD1 și conțin metadate despre modul. Aici veți include informații despre autor, descrierea modulului, alte module necesare și multe alte atribute. Pentru a publica într-un depozit, este necesar să aibă câmpurile Author și Description populate.

Iată un exemplu de manifest pe care îl putem avea pentru modulul nostru de registru:

#Module manifest for module 'ATARegistry'#Generated by: Tyler#Generated on: 8/11/2019@{#Script module or binary module file associated with this manifest.RootModule = 'ATARegistry'#Version number of this module.ModuleVersion = '1.0'#Supported PSEditions#CompatiblePSEditions = @()#ID used to uniquely identify this moduleGUID = 'fef619fa-016d-4b11-a09d-b222e094de3e'#Author of this moduleAuthor = 'Tyler Muir'#Company or vendor of this moduleCompanyName = 'Adam the Automator'#Copyright statement for this moduleCopyright = '(c) 2019 tyler. All rights reserved.'#Description of the functionality provided by this moduleDescription = 'This is a test module.'#Minimum version of the Windows PowerShell engine required by this module#PowerShellVersion = ''#Name of the Windows PowerShell host required by this module#PowerShellHostName = ''#Minimum version of the Windows PowerShell host required by this module#PowerShellHostVersion = ''#Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.#DotNetFrameworkVersion = ''#Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.#CLRVersion = ''#Processor architecture (None, X86, Amd64) required by this module#ProcessorArchitecture = ''#Modules that must be imported into the global environment prior to importing this module#RequiredModules = @()#Assemblies that must be loaded prior to importing this module#RequiredAssemblies = @()#Script files (.ps1) that are run in the caller's environment prior to importing this module.#ScriptsToProcess = @()#Type files (.ps1xml) to be loaded when importing this module#TypesToProcess = @()#Format files (.ps1xml) to be loaded when importing this module#FormatsToProcess = @()#Modules to import as nested modules of the module specified in RootModule/ModuleToProcess#NestedModules = @()#Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.FunctionsToExport = @('Get-RegistryKey','Set-RegistryKey')#Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.CmdletsToExport = @()#Variables to export from this moduleVariablesToExport = '*'#Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.AliasesToExport = @()#DSC resources to export from this module#DscResourcesToExport = @()#List of all modules packaged with this module#ModuleList = @()#List of all files packaged with this module#FileList = @()#Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.PrivateData = @{PSData = @{#Tags applied to this module. These help with module discovery in online galleries.#Tags = @()#A URL to the license for this module.#LicenseUri = ''#A URL to the main website for this project.#ProjectUri = ''#A URL to an icon representing this module.#IconUri = ''#ReleaseNotes of this module#ReleaseNotes = ''} #End of PSData hashtable} #End of PrivateData hashtable#HelpInfo URI of this module#HelpInfoURI = ''#Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.#DefaultCommandPrefix = ''}

În timp ce acest lucru poate părea intimidant la început, Microsoft are un cmdlet la îndemână pe care îl puteți utiliza pentru a genera un manifest de modul. Comanda inclusă este New-ModuleManifest. Pentru a genera manifestul prezentat mai sus ați putea folosi:

PS51> New-ModuleManifest -Path .\Scripts\TestModule.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule 'TestModule.psm1' -FunctionsToExport @('Get-RegistryKey','Set-RegistryKey') -Description 'This is a test module.'

External Help Files

De asemenea, este posibil să vedeți fișiere de ajutor externe în unele module. Acestea ar putea fi identificate prin <ModuleName>-Help.xml la sfârșitul numelui fișierului. Aceste fișiere de ajutor extern conțin aceleași informații care ar fi conținute în mod normal în ajutorul bazat pe comenzi pe care îl puteți găsi în definiția unei funcții.

Acesta ar necesita, de asemenea, să adăugați # .ExternalHelp <ModulePath>-Help.xml la funcția dvs. pentru ca aceasta să funcționeze corect atunci când utilizați comanda Get-Help după importarea modulului. De obicei, este obișnuit să vedeți fișiere de ajutor extern doar în cazul modulelor foarte mari și, din acest motiv, acestea nu fac parte din domeniul de aplicare.

În timp ce acestea sunt cele mai frecvente tipuri de fișiere pe care le veți vedea într-un modul, acestea nu sunt singurele fișiere. Uneori veți vedea fișiere binare în plus față de un modul text, deoarece există alte dependențe. Explorând prin căile de acces la module, puteți găsi multe exemple de tipuri de fișiere suplimentare în module.

Pentru a avea fișiere de modul non-standard publicate în mod corespunzător, veți include alte fișiere în parametrul FileList din manifestul modulului.

În manifestul modulului, veți observa mulți alți parametri care sunt în prezent goi. Îi puteți utiliza pe aceștia pentru a defini alte cerințe pentru utilizarea modulului dumneavoastră. De exemplu, puteți defini versiunile de PowerShell cu care poate funcționa modulul. Dacă încercați să importați modulul pe o versiune neacceptată de PowerShell, iată ce veți vedea:

PSRepositories

Una dintre opțiunile cheie de distribuție pentru module este un PSRepository. La o vedere de 1000′, un PSRepository este un local în care mai multe persoane sau mai multe dispozitive pot accesa fișierele modulelor. Acestea sunt în mod frecvent servere web unde puteți publica fișiere.

Puteți utiliza, de asemenea, un director pentru depozit, dar acest lucru vă limitează în ceea ce privește funcționalitatea depozitului dumneavoastră. Puteți găzdui singur un PSRepository sau puteți utiliza una dintre numeroasele opțiuni disponibile pe internet, cum ar fi PowerShell Gallery. Vă puteți vedea PSRepositoriile PSRepositories utilizând comanda Get-PSRepository.

În mod implicit, veți avea doar o singură intrare și aceasta va fi pentru PowerShell Gallery. Este posibil să observați că va scrie untrusted. Acest lucru se datorează faptului că PowerShell vă face să conștientizați că, prin utilizarea PowerShell Gallery, este posibil să folosiți cod care nu a fost scris și aprobat de Microsoft. Acest lucru înseamnă că, înainte de a instala orice modul din ea, va trebui să acordați permisiunea explicită.

Adăugarea de PSRepositories

De asemenea, puteți adăuga propriile depozite. Pentru a avea încredere în Galeria PowerShell, puteți rula Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted sau puteți accepta avertismentul prima dată când instalați un modul din Galeria PowerShell.

Toate comenzile pe care le veți folosi pentru a interacționa cu aceste PSRepositories pot fi găsite în modulul PowerShellGet. Puteți vedea funcțiile aici:

Modulul PowerShellGet poate fi necesar să fie actualizat înainte de a interacționa cu anumite depozite.

Găsirea modulelor

O altă caracteristică cheie a utilizării unui PSRepository este posibilitatea de a căuta module. Acest lucru se realizează cu ajutorul comenzii Find-Module. Există mai multe modalități de filtrare pentru a găsi în mod specific ceea ce căutați, dar deocamdată puteți căuta modulele VMware astfel:

Aceasta va arăta toate modulele care încep cu VMware. Deși cele mai multe dintre acestea sunt de la VMware, trebuie să vă uitați la atributul autorului pentru a vedea cine a publicat modulul.

Din moment ce oricine poate încărca pe PowerShell Gallery, există mii de module disponibile. Acest lucru înseamnă că este posibil să găsiți module care nu funcționează corect pentru cazul dvs. de utilizare. Multe dintre modulele pe care le veți găsi sunt open source, astfel încât puteți contribui la ele pentru a îmbunătăți funcționalitatea modulului.

Instalarea modulelor

Pentru a utiliza comanda Install-Module, trebuie să aveți un PSRepository de încredere care găzduiește modulul. Acesta poate fi Galeria PowerShell, un alt PSRepository de pe internet sau un site găzduit de sine stătător. Puteți pipeta din comanda Find-Module pentru a fi disponibil pentru a confirma cu ușurință modulul înainte de a-l instala.

De asemenea, puteți defini versiunea unui modul utilizând parametrii MinimumVersion, MaximumVersion sau RequiredVersion.

Pentru a vedea toate modulele instalate utilizând Install-Module puteți utiliza Get-InstalledModule. Aceasta va lista toate modulele instalate în domeniul de aplicare AllUsers sau în domeniul de aplicare CurrentUser.

Dezinstalarea modulelor

La fel cum puteți instala un modul, puteți, de asemenea, dezinstala un modul. Dacă modulul nu a fost instalat prin intermediul comenzii Install-Module, nu îl puteți dezinstala cu comanda Uninstall-Module.

După cum puteți vedea aici încercăm să dezinstalăm modulul ActiveDirectory. Deoarece acest modul nu este instalat cu Install-Module, veți primi o eroare atunci când încercați să utilizați Uninstall-Module. Pentru a dezinstala acest modul, ar trebui să îl dezinstalăm prin inversarea a ceea ce ați folosit pentru a instala modulul.

Pentru a vedea o dezinstalare reușită a unui modul, puteți dezinstala modulul VMware.PowerCLI pe care l-ați instalat mai devreme.

Chiar dacă ați dezinstalat VMware.PowerCLI, puteți vedea că există încă multe dependențe care sunt instalate. Dacă ați dori să dezinstalați toate modulele am putea folosi Get-InstalledModule VMware.* | Uninstall-Module -Force.

Motivul pentru care ați avea atâtea dificultăți în dezinstalarea completă a acestui modul este că are atât de multe dependențe. În plus, unele dintre aceste module sunt dependențe unele de altele, motiv pentru care ar fi necesar parametrul Force.

Actualizarea modulelor

Acum că știți cum să instalați și să dezinstalați un modul, poate vă întrebați cum actualizați un modul pe care l-ați instalat.

La fel ca și în cazul altor procese, dacă modulul nu a fost instalat folosind Install-Module, nu îl puteți actualiza folosind comenzile PowerShell. Puteți utiliza Update-Module pentru a actualiza un modul la cea mai nouă versiune sau la o versiune specifică mai nouă.

Există, de asemenea, un comutator pentru AllowPreRelease care v-ar permite să actualizați la o versiune care nu a fost lansată oficial. Uneori, acest lucru poate fi de ajutor, deoarece este posibil să se fi rezolvat o eroare cu care vă confruntați sau să se fi adăugat o nouă caracteristică pe care ați dori să o utilizați.

Inspectarea/Salvarea unui modul

Una dintre comenzile mult mai puțin utilizate, care este foarte utilă atunci când se verifică modulele înainte de utilizare, este Save-Module. Cu ajutorul acestei comenzi, puteți descărca un modul într-o cale fără a-l instala.

Puteți apoi inspecta fișierele și, dacă modulul nu este un modul binar, îl puteți deschide și vă puteți uita la codul care îl compune. Acest lucru poate fi bun nu numai pentru a vă asigura că un modul nu face nimic rău intenționat, ci și pentru a învăța cum își structurează alții modulele.

În acest exemplu, nu este descărcat numai modulul VMware.PowerCLI, ci și toate dependențele. Iată ce se afișează în folderul VMware.PowerCLI:

Acesta este un bun exemplu pentru a arăta cum există uneori fișiere de modul non-standard incluse în modul, cum ar fi contractul de licență pentru utilizatorul final.

Scrierea propriului modul

Acum ați văzut cum să interacționați cu modulul altcuiva. Acum doriți să învățați cum să vă creați propriul modul, astfel încât să puteți începe să vă optimizați codul pentru scalabilitate.

Crearea fișierelor șablon

În primul rând trebuie să creați un dosar pentru toate fișierele modulului dumneavoastră. După ce aveți containerul, trebuie să vă creați fișierul de modul. Trebuie să vă asigurați că fișierul de modul are același nume ca și dosarul, altfel, atunci când încercați să vă publicați modulul, PowerShell nu va descoperi modulul corect.

PS51> New-Item -Path .\Scripts -Name ATARegistry -ItemType DirectoryPS51> New-Item -Path .\Scripts\ATARegistry -Name ATARegistry.psm1

Acum doriți să folosiți și un manifest, va trebui, de asemenea, să îl numiți la fel ca și containerul și fișierul de modul.

PS51> New-ModuleManifest -Path .\Scripts\ATARegistry\ATARegistry.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule ATARegistry.psm1 -Description 'Used for interacting with registry keys'

Cu containerul, fișierul de modul și fișierul manifest, aveți un modul complet funcțional. Ați putea publica acest modul într-un PSRepository și ați putea începe să îl instalați oriunde doriți. Deși, din moment ce fișierul modulului este gol, probabil că nu vă va fi de mare folos. Puteți totuși să folosiți aceste fișiere pentru a testa publicarea pentru a vă asigura că depozitul dumneavoastră funcționează.

Înregistrarea unui PSRepository

Înainte de a vă putea publica modulul, va trebui să adăugați un alt PSRepository la sesiunea dumneavoastră. Pentru testare, puteți folosi o cale locală ca PSRepository, deoarece va fi ușor de configurat și desființat.

Normal, dacă ați avea de gând să configurați un PSRepository cu un director, ați dori să vă asigurați că mai multe calculatoare îl pot accesa. Puteți crea un depozit local astfel:

PS51> New-Item -Path C:\ -Name Repo -ItemType DirectoryPS51> Register-PSRepository -Name 'LocalRepo' -SourceLocation 'C:\Repo' -PublishLocation 'C:\Repo' -InstallationPolicy Trusted

Dacă ați descărca numai din PSRepository și nu ați publica niciodată, ați putea exclude parametrul PublishLocation.

Publicarea modulului

Din moment ce ați setat deja politica de instalare la încredere, nu veți primi o confirmare pentru a permite instalarea unui modul din depozit. Acum că aveți un nou PSRepository disponibil, vă puteți publica modulul utilizând Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

După ce ați publicat modulul, puteți utiliza comenzile de mai sus pentru a găsi modulul și a-l instala.

Acum că ați instalat modulul, puteți utiliza Get-Module pentru a vedea modulul importat în sesiunea dvs. locală. Deoarece nu ați adăugat nicio funcție la matricea FunctionsToExport din manifest, proprietatea ExportedCommands este goală.

Adăugarea la modulul dumneavoastră

Acum că știți că puteți publica și instala modulul dumneavoastră, puteți începe să adăugați unele funcționalități la acesta. Ați putea adăuga o funcție care să returneze o cheie de registru, astfel încât să arate astfel:

function Get-ATARegistryKey { param ( $Path ) Get-Item $Path}

Dacă ați lăsa manifestul așa cum este și ați încerca să încărcați noul dvs. modul, v-ați confrunta cu două probleme. Prima este că ați primi o eroare care ar indica faptul că versiunea modulului dvs. există deja în depozitul dvs. Acest lucru se datorează faptului că nu ați modificat versiunea modulului în fișierul manifest.

Exportul funcțiilor modulului

Altă problemă ar fi că, după ce ați importat modulul, tot nu ați vedea nicio funcție în proprietatea ExportedCommands, deoarece nu ați adăugat noua dvs. funcție în manifest.

În timp ce funcția dvs. ar putea fi utilizată fără a fi listată în lista FunctionsToExport, ar fi mult mai dificil de localizat.

Pentru a rezolva aceste două probleme, puteți actualiza fișierul modulului dumneavoastră astfel:

ModuleVersion = '1.1'FunctionsToExport = 'Get-RegistryKey'

Acum că ați adăugat o funcție la modulul dumneavoastră și ați actualizat manifestul pentru a reflecta aceste modificări, puteți publica noua versiune a modulului dumneavoastră folosind aceeași comandă ca și înainte.

PS51> Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Actualizarea modulului dumneavoastră

Ultimul pas ar fi ca dumneavoastră să vă actualizați modulul în sesiune pentru a putea utiliza fișierele actualizate. Folosind Update-Module ATARegistry descărcați actualizarea pe care tocmai ați publicat-o în depozit.

Acum puteți vedea că aveți noua versiune a modulului și puteți vedea funcția pe care ați definit-o în manifest.

Construirea conținutului de ajutor

Una dintre opțiunile care a fost trecută mai devreme este sistemul de ajutor care este integrat în PowerShell. Probabil că la un moment dat ați folosit Get-Help pe o funcție. Aceste informații pot fi adăugate în două moduri principale.

Primul este de a adăuga ajutor bazat pe comentarii în definiția funcției. Aceasta este de obicei modalitatea pe care o implementează mulți autori de module. Celălalt mod este de a utiliza un fișier de ajutor extern. Puteți utiliza parametrul Full pentru a afișa tot ceea ce are de oferit ajutorul.

După cum puteți vedea, nu există cu adevărat prea multe informații, iar puținele informații pe care le obțineți cel mai probabil nu ar fi de ajutor nimănui.

Puteți adăuga un ajutor bazat pe comentarii în fișierul dvs. de modul pentru a umple aceste câmpuri în sistemul de ajutor. Puteți citi despre toate opțiunile pentru ajutorul bazat pe comentarii folosind Get-Help about_Comment_Based_Help.

Pentru moment, puteți să vă actualizați funcția pentru a arăta ca mai jos. Aceasta este o listă a celor mai frecvent utilizați parametri de ajutor, dar toți aceștia sunt încă opționali și există și alții care ar putea fi adăugați în locul lor.

Acum funcția dvs. arată astfel:

 function Get-RegistryKey {<# .SYNOPSIS Returns registry key using provided path. .DESCRIPTION The function uses the Get-Item command to return the information for a provided registry key. .PARAMETER Path The path that will be searched for a registry key. .EXAMPLE Get-RegistryKey -Path 'HKLM:\HARDWARE\DESCRIPTION\System' .INPUTS System.String .OUTPUTS Microsoft.Win32.RegistryKey .NOTES This module is an example of what a well documented function could look. .LINKhttps://adamtheautomator.com#>param($Path)Get-Item $Path}

Există unii parametri de ajutor speciali, cum ar fi .FORWARDHELPTARGETNAME. Această opțiune redirecționează toate cererile de ajutor primite către o altă comandă. Aceasta ar putea fi utilizată într-un caz în care ajutorul ar trebui să afișeze aceleași informații pentru mai multe comenzi.

Acum că ați adăugat ajutorul, puteți actualiza versiunea în manifestul modulului, publica noua versiune și actualiza versiunea instalată pentru sesiunea dvs. așa cum ați făcut mai devreme.

Dacă vă uitați acum la ajutorul pentru funcție, puteți vedea că sunt disponibile mult mai multe informații. Aceasta este o modalitate excelentă de a include documentație privind modul de utilizare a funcțiilor, în special pentru cineva care are mai puțină experiență și care s-ar putea să nu fie capabil să înțeleagă rapid ce face modulul uitându-se la cod.

În cazul unui fișier de ajutor extern, informațiile adăugate sunt aceleași, dar informațiile sunt plasate într-un fișier separat și sunt legate în cadrul funcției.

Dacă vă uitați în calea modulului AllUsers puteți vedea versiunea modulului și toate fișierele modulului pe care le-ați instalat.

Dacă vă întoarceți la calea PSRepository C:\Repo pe care ați creat-o mai devreme, puteți vedea o mulțime de fișiere NUPKG. Va exista unul pentru fiecare versiune care a fost publicată. Acestea sunt versiuni comprimate a ceea ce ați publicat atunci când ați folosit Publish-Module.

Rezumat

După ce v-ați descurcat cu consola PowerShell, PowerShell ca limbaj și scrierea de scripturi, construirea propriilor module este ultimul pas. Modulele vă permit să începeți să dezvoltați instrumente utile în PowerShell. Dacă sunt proiectate și construite corect prin crearea de module cu un singur scop, vă veți trezi în mod inevitabil că veți scrie din ce în ce mai puțin cod în timp. Veți începe să faceți referire la funcțiile modulelor dvs. în mai mult cod și să construiți de acolo.

Funcțiile modulelor vă permit să faceți abstracție de codul pe care vă treziți că îl repetați în scripturi. Ele reprezintă „etichete” la care să faceți referire mai târziu în codul care poate fi apelat în orice moment, mai degrabă decât să reinventați roata și să încercați să vă dați seama cum v-ați îndeplinit deja obiectivul anterior. Modulele reprezintă „împachetarea” finală a codului PowerShell care grupează codul asemănător pentru a preveni pierderea de timp cu probleme pe care le-ați rezolvat deja.

.