Een PowerShell-module installeren

Nadat u de PowerShell-module hebt gemaakt, wilt u de module waarschijnlijk op een systeem installeren, zodat u of anderen deze kunnen gebruiken. Over het algemeen bestaat dit uit het kopiëren van de modulebestanden (dat wil zeggen, de .psm1 of de binaire assembly, het modulemanifest en andere bijbehorende bestanden) naar een map op die computer. Voor een zeer klein project kan dit net zo eenvoudig zijn als het kopiëren en kopiëren van de bestanden met Windows Explorer op één externe computer; Voor grotere oplossingen kunt u echter een geavanceerder installatieproces gebruiken. Ongeacht hoe u uw module op het systeem krijgt, kan PowerShell een aantal technieken gebruiken waarmee gebruikers uw modules kunnen vinden en gebruiken. Daarom is het belangrijkste probleem bij de installatie om ervoor te zorgen dat PowerShell uw module kan vinden. Zie Importing a PowerShell Module (Een PowerShell-module importeren) voor meer informatie.

Regels voor het installeren van modules

De volgende informatie heeft betrekking op alle modules, inclusief modules die u voor uw eigen gebruik maakt, modules die u van andere partijen krijgt en modules die u naar anderen distribueert.

Modules installeren in PSModulePath

Installeer indien mogelijk alle modules in een pad dat wordt vermeld in de omgevingsvariabele PSModulePath of voeg het modulepad toe aan de waarde van de omgevingsvariabele PSModulePath.

De omgevingsvariabele PSModulePath ( $Env:PSModulePath ) bevat de locaties van Windows PowerShell modules. Cmdlets zijn afhankelijk van de waarde van deze omgevingsvariabele om modules te vinden.

Standaard bevat de omgevingsvariabele PSModulePath de volgende systeem- en gebruikersmoduledirecties, maar u kunt de waarde toevoegen en bewerken.

• $PSHome\Modules (%Windir%\System32\WindowsPowerShell\v1.0\Modules)

  Waarschuwing

  Deze locatie is gereserveerd voor modules die met een Windows. Installeer geen modules op deze locatie.

• $Home\Documents\WindowsPowerShell\Modules (%UserProfile%\Documents\WindowsPowerShell\Modules)

• $Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)

  Gebruik een van de volgende opdrachten om de waarde van de omgevingsvariabele PSModulePath op te halen.

  $Env:PSModulePath
  [Environment]::GetEnvironmentVariable("PSModulePath")
  

  Als u een modulepad wilt toevoegen aan de waarde van de omgevingsvariabele PSModulePath, gebruikt u de volgende opdrachtindeling. Deze indeling maakt gebruik van de methode SetEnvironmentVariable van de klasse System.Environment om een sessieonafhankelijke wijziging aan te brengen in de omgevingsvariabele PSModulePath.

  #Save the current value in the $p variable.
  $p = [Environment]::GetEnvironmentVariable("PSModulePath")
  
  #Add the new path to the $p variable. Begin with a semi-colon separator.
  $p += ";C:\Program Files (x86)\MyCompany\Modules\"
  
  #Add the paths in $p to the PSModulePath value.
  [Environment]::SetEnvironmentVariable("PSModulePath",$p)
  

  Belangrijk

  Nadat u het pad hebt toegevoegd aan PSModulePath, moet u een omgevingsbericht over de wijziging verzenden. Door de wijziging uit te zenden, kunnen andere toepassingen, zoals de shell, de wijziging ophalen. Als u de wijziging wilt uitzenden, laat u de installatiecode van uw product een WM_SETTINGCHANGE verzenden met lParam ingesteld op de tekenreeks 'Omgeving'. Zorg ervoor dat u het bericht verzendt nadat de installatiecode van de module PSModulePath heeft bijgewerkt.

De mapnaam van de juiste module gebruiken

Een goed gevormde module is een module die is opgeslagen in een map met dezelfde naam als de basisnaam van ten minste één bestand in de modulemap. Als een module niet goed is gevormd, Windows PowerShell deze niet als module herkend.

De basisnaam van een bestand is de naam zonder de bestandsnaamextensie. In een goed gevormde module moet de naam van de map met de modulebestanden overeenkomen met de basisnaam van ten minste één bestand in de module.

In de Voorbeeldmodule van Fabrikam heeft de map met de modulebestanden bijvoorbeeld de naam Fabrikam en heeft ten minste één bestand de basisnaam Fabrikam. In dit geval hebben zowel Fabrikam.psd1 als Fabrikam.dll de basisnaam Fabrikam.

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

Effect van onjuiste installatie

Als de module niet goed is gevormd en de locatie ervan niet is opgenomen in de waarde van de omgevingsvariabele PSModulePath, werken basisdetectiefuncties van Windows PowerShell, zoals de volgende, niet.

• De functie Module automatisch laden kan de module niet automatisch importeren.

• De ListAvailable parameter van de cmdlet Get-Module kan de module niet vinden.

• De cmdlet Import-Module kan de module niet vinden. Als u de module wilt importeren, moet u het volledige pad naar het hoofdmodulebestand of het manifestbestand van de module verstrekken.

  Aanvullende functies, zoals de volgende, werken alleen als de module wordt geïmporteerd in de sessie. In goed gevormde modules in de omgevingsvariabele PSModulePath werken deze functies zelfs wanneer de module niet in de sessie wordt geïmporteerd.

• De Cmdlet Get-Command kan geen opdrachten vinden in de module.

• De cmdlets Update-Help en Save-Help kunnen geen help bijwerken of opslaan voor de module.

• De cmdlet Show-Command kan de opdrachten in de module niet vinden en weergeven.

  De opdrachten in de module ontbreken in het Show-Command venster in Windows PowerShell IsE (Integrated Scripting Environment).

Waar modules installeren

In deze sectie wordt uitgelegd waar in het bestandssysteem u de modules Windows PowerShell installeren. De locatie is afhankelijk van hoe de module wordt gebruikt.

Modules voor een specifieke gebruiker installeren

Als u uw eigen module maakt of een module van een andere partij krijgt, zoals een Windows PowerShell-communitywebsite, en u wilt dat de module alleen beschikbaar is voor uw gebruikersaccount, installeert u de module in uw gebruikersspecifieke map Modules.

$home\Documents\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

De gebruikersspecifieke map Modules wordt standaard toegevoegd aan de waarde van de omgevingsvariabele PSModulePath.

Modules installeren voor alle gebruikers in programmabestanden

Als u wilt dat een module beschikbaar is voor alle gebruikersaccounts op de computer, installeert u de module op de locatie Programmabestanden.

$Env:ProgramFiles\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

Notitie

De locatie programmabestanden wordt standaard toegevoegd aan de waarde van de omgevingsvariabele PSModulePath in Windows PowerShell 4.0 en hoger. Voor eerdere versies van Windows PowerShell kunt u handmatig de locatie programmabestanden maken (%ProgramFiles%\WindowsPowerShell\Modules) en dit pad toevoegen aan de omgevingsvariabele PSModulePath, zoals hierboven beschreven.

Modules installeren in een productmap

Als u de module distribueert naar andere partijen, gebruikt u de standaardlocatie programmabestanden die hierboven wordt beschreven of maakt u uw eigen bedrijfsspecifieke of productspecifieke submap van de map %ProgramFiles%.

Fabrikam Technologies, een fictief bedrijf, verzend bijvoorbeeld een Windows PowerShell module voor hun Fabrikam Manager-product. Het installatieprogramma voor de module maakt een subdirectory Modules in de subdirectory van fabrikam Manager-producten.

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

Om de detectiefuncties Windows PowerShell de Fabrikam-module te vinden, voegt het installatieprogramma van de Fabrikam-module de modulelocatie toe aan de waarde van de omgevingsvariabele PSModulePath.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam Technologies\Fabrikam Manager\Modules\"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Modules installeren in de map Common Files

Als een module wordt gebruikt door meerdere onderdelen van een product of door meerdere versies van een product, installeert u de module in een modulespecifieke subdirectory van de subdirectory %ProgramFiles%\Common Files\Modules.

In het volgende voorbeeld wordt de Fabrikam-module geïnstalleerd in een Fabrikam-subdirectory van de %ProgramFiles%\Common Files\Modules subdirectory. Houd er rekening mee dat elke module zich in een eigen subdirectory bevindt in de subdirectory Modules.

C:\Program Files
  Common Files
    Modules
      Fabrikam
        Fabrikam.psd1 (module manifest)
        Fabrikam.dll (module assembly)

Vervolgens zorgt het installatieprogramma ervoor dat de waarde van de omgevingsvariabele PSModulePath het pad van de subdirectory van de algemene bestandsmodules bevat.

$m = $env:ProgramFiles + '\Common Files\Modules'
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$q = $p -split ';'
if ($q -notContains $m) {
    $q += ";$m"
}
$p = $q -join ';'
[Environment]::SetEnvironmentVariable("PSModulePath", $p)

Meerdere versies van een module installeren

Als u meerdere versies van dezelfde module wilt installeren, gebruikt u de volgende procedure.

1. Maak een map voor elke versie van de module. Neem het versienummer op in de mapnaam.
2. Maak een modulemanifest voor elke versie van de module. Voer in de waarde van de ModuleVersion-sleutel in het manifest het versienummer van de module in. Sla het manifestbestand (.psd1) op in de versiespecifieke map voor de module.
3. Voeg het pad van de hoofdmap van de module toe aan de waarde van de omgevingsvariabele PSModulePath, zoals wordt weergegeven in de volgende voorbeelden.

Als u een bepaalde versie van de module wilt importeren, kan de eindgebruiker de parameters of van MinimumVersion RequiredVersion de cmdlet Import-Module gebruiken.

Als de Fabrikam-module bijvoorbeeld beschikbaar is in versies 8.0 en 9.0, kan de mapstructuur van de Fabrikam-module er als volgt uit zien.

C:\Program Files
Fabrikam Manager
 Fabrikam8
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "8.0")
     Fabrikam.dll (module assembly)
 Fabrikam9
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "9.0")
     Fabrikam.dll (module assembly)

Het installatieprogramma voegt beide modulepaden toe aan de waarde van de omgevingsvariabele PSModulePath.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam\Fabrikam8;C:\Program Files\Fabrikam\Fabrikam9"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Wanneer deze stappen zijn voltooid, haalt de parameter ListAvailable van de cmdlet Get-Module beide Fabrikam-modules op. Als u een bepaalde module wilt importeren, gebruikt u MinimumVersion de parameters of van de RequiredVersion cmdlet Import-Module.

Als beide modules in dezelfde sessie worden geïmporteerd en de modules cmdlets met dezelfde namen bevatten, zijn de cmdlets die als laatste zijn geïmporteerd van kracht in de sessie.

Opdrachtnaamconflicten verwerken

Opdrachtnaamconflicten kunnen optreden wanneer de opdrachten die een module exporteert dezelfde naam hebben als opdrachten in de sessie van de gebruiker.

Wanneer een sessie twee opdrachten met dezelfde naam bevat, Windows PowerShell het opdrachttype dat prioriteit heeft. Wanneer een sessie twee opdrachten bevat met dezelfde naam en hetzelfde type, wordt Windows PowerShell opdracht uitgevoerd die het laatst aan de sessie is toegevoegd. Als gebruikers een opdracht willen uitvoeren die niet standaard wordt uitgevoerd, kunnen ze de naam van de opdracht kwalificeren met de modulenaam.

Als de sessie bijvoorbeeld een functie en de Get-Date Get-Date cmdlet bevat, wordt Windows PowerShell functie standaard uitgevoerd. Als u de cmdlet wilt uitvoeren, moet u de opdracht vooraf laten gaan door de modulenaam, zoals:

Microsoft.PowerShell.Utility\Get-Date

Om naamconflicten te voorkomen, kunnen moduleauteurs de sleutel DefaultCommandPrefix in het modulemanifest gebruiken om een zelfstandig naamwoord op te geven voor alle opdrachten die uit de module worden geëxporteerd.

Gebruikers kunnen de parameter Voorvoegsel van de Import-Module cmdlet gebruiken om een alternatief voorvoegsel te gebruiken. De waarde van de parameter Prefix heeft voorrang op de waarde van de sleutel DefaultCommandPrefix.

Ondersteunende paden op niet-Windows systemen

Niet-Windows platforms gebruiken de dubbele punt ( ) als een padscheidingsteken en een : slash / () als mapscheidingsteken. De [System.IO.Path] klasse heeft statische leden die kunnen worden gebruikt om uw code op elk platform te laten werken:

• [System.IO.Path]::PathSeparator - retourneert het teken dat wordt gebruikt om paden te scheiden in een PATH-omgevingsvariabele voor het hostplatform
• [System.IO.Path]::DirectorySeparatorChar - retourneert het teken dat wordt gebruikt om mapnamen te scheiden met een pad voor het hostplatform

Gebruik deze statische eigenschappen in plaats van de ; tekens en wanneer u \ padtekenreeksen maakt.

Zie ook

about_Command_Precedence

Een Windows PowerShell-module schrijven