about_Scripts

Korte beschrijving

Hierin wordt beschreven hoe u scripts uitvoert en schrijft in PowerShell.

Lange beschrijving

Een script is een tekstbestand zonder opmaak dat een of meer PowerShell-opdrachten bevat. PowerShell-scripts hebben een .ps1 bestandsextensie.

Het uitvoeren van een script is veel vergelijkbaar met het uitvoeren van een cmdlet. U typt het pad en de bestandsnaam van het script en gebruikt parameters om gegevens in te dienen en opties in te stellen. U kunt scripts uitvoeren op uw computer of in een externe sessie op een andere computer.

Als u een script schrijft, wordt een opdracht opgeslagen voor later gebruik en kunt u deze eenvoudig delen met anderen. Het belangrijkste is dat u de opdrachten eenvoudig kunt uitvoeren door het scriptpad en de bestandsnaam te typen. Scripts kunnen net zo eenvoudig zijn als één opdracht in een bestand of zo uitgebreid als een complex programma.

Scripts hebben extra functies, zoals de #Requires speciale opmerking, het gebruik van parameters, ondersteuning voor gegevenssecties en digitale ondertekening voor beveiliging. U kunt ook Help-onderwerpen schrijven voor scripts en voor alle functies in het script.

Een script uitvoeren

Voordat u een script in Windows kunt uitvoeren, moet u het standaard powerShell-uitvoeringsbeleid wijzigen. Uitvoeringsbeleid is niet van toepassing op PowerShell die wordt uitgevoerd op niet-Windows-platforms.

Het standaarduitvoeringsbeleid voorkomt Restricteddat alle scripts worden uitgevoerd, inclusief scripts die u op de lokale computer schrijft. Raadpleeg about_Execution_Policies voor meer informatie.

Het uitvoeringsbeleid wordt opgeslagen in het register, dus u moet het slechts één keer op elke computer wijzigen.

Gebruik de volgende procedure om het uitvoeringsbeleid te wijzigen.

Typ bij de opdrachtprompt:

Set-ExecutionPolicy AllSigned

or

Set-ExecutionPolicy RemoteSigned

De wijziging is onmiddellijk van kracht.

Als u een script wilt uitvoeren, typt u de volledige naam en het volledige pad naar het scriptbestand.

Voer het volgende in om het script Get-ServiceLog.ps1 uit te voeren in de map C:\Scripts:

C:\Scripts\Get-ServiceLog.ps1

Als u een script in de huidige map wilt uitvoeren, typt u het pad naar de huidige map of gebruikt u een punt om de huidige map weer te geven, gevolgd door een padbackslash (.\).

Als u bijvoorbeeld het Script ServicesLog.ps1 wilt uitvoeren in de lokale map, typt u:

.\Get-ServiceLog.ps1

Als het script parameters heeft, typt u de parameters en parameterwaarden na de bestandsnaam van het script.

Met de volgende opdracht wordt bijvoorbeeld de servicenaamparameter van het Get-ServiceLog-script gebruikt om een logboek van WinRM-serviceactiviteit aan te vragen.

.\Get-ServiceLog.ps1 -ServiceName WinRM

PowerShell voert als beveiligingsfunctie geen scripts uit wanneer u dubbelklikt op het scriptpictogram in Bestandenverkenner of wanneer u de scriptnaam zonder een volledig pad typt, zelfs niet wanneer het script zich in de huidige map bevindt. Zie about_Command_Precedence voor meer informatie over het uitvoeren van opdrachten en scripts in PowerShell.

Uitvoeren met PowerShell

Vanaf PowerShell 3.0 kunt u scripts uitvoeren vanaf Bestandenverkenner.

De functie Uitvoeren met PowerShell gebruiken:

Voer Bestandenverkenner uit, klik met de rechtermuisknop op de bestandsnaam van het script en selecteer Vervolgens Uitvoeren met PowerShell.

De functie Uitvoeren met PowerShell is ontworpen om scripts uit te voeren die geen vereiste parameters hebben en geen uitvoer retourneren naar de opdrachtprompt.

Zie about_Run_With_PowerShell voor meer informatie.

Scripts uitvoeren op andere computers

Als u een script wilt uitvoeren op een of meer externe computers, gebruikt u de parameter FilePath van de Invoke-Command cmdlet.

Voer het pad en de bestandsnaam van het script in als de waarde van de Parameter FilePath . Het script moet zich op de lokale computer of in een map bevinden waartoe de lokale computer toegang heeft.

Met de volgende opdracht wordt het Get-ServiceLog.ps1 script uitgevoerd op de externe computers met de naam Server01 en Server02.

Invoke-Command -ComputerName Server01,Server02 -FilePath `
  C:\Scripts\Get-ServiceLog.ps1

Hulp krijgen voor scripts

De Cmdlet Get-Help haalt de Help-onderwerpen voor scripts op, evenals voor cmdlets en andere typen opdrachten. Als u het Help-onderwerp voor een script wilt ophalen, typt Get-Help u gevolgd door het pad en de bestandsnaam van het script. Als het scriptpad zich in uw Path omgevingsvariabele bevindt, kunt u het pad weglaten.

Als u bijvoorbeeld hulp wilt krijgen voor het script ServicesLog.ps1, typt u:

get-help C:\admin\scripts\ServicesLog.ps1

Een script schrijven

Een script kan geldige PowerShell-opdrachten bevatten, waaronder enkele opdrachten, opdrachten die gebruikmaken van de pijplijn, functies en besturingsstructuren, zoals If-instructies en For-lussen.

Als u een script wilt schrijven, opent u een nieuw bestand in een teksteditor, typt u de opdrachten en slaat u deze op in een bestand met een geldige bestandsnaam met de .ps1 bestandsextensie.

Het volgende voorbeeld is een eenvoudig script waarmee de services die op het huidige systeem worden uitgevoerd, worden opgeslagen in een logboekbestand. De bestandsnaam van het logboek wordt gemaakt op basis van de huidige datum.

$date = (get-date).dayofyear
get-service | out-file "$date.log"

Als u dit script wilt maken, opent u een teksteditor of een scripteditor, typt u deze opdrachten en slaat u deze op in een bestand met de naam ServiceLog.ps1.

Parameters in scripts

Als u parameters in een script wilt definiëren, gebruikt u een Param-instructie. De Param instructie moet de eerste instructie in een script zijn, met uitzondering van opmerkingen en eventuele #Require instructies.

Scriptparameters werken als functieparameters. De parameterwaarden zijn beschikbaar voor alle opdrachten in het script. Alle functies van functieparameters, inclusief het kenmerk Parameter en de benoemde argumenten, zijn ook geldig in scripts.

Bij het uitvoeren van het script typen scriptgebruikers de parameters na de scriptnaam.

In het volgende voorbeeld ziet u een Test-Remote.ps1 script met een computernaamparameter . Beide scriptfuncties hebben toegang tot de parameterwaarde ComputerName .

param ($ComputerName = $(throw "ComputerName parameter is required."))

function CanPing {
   $error.clear()
   $tmp = test-connection $computername -erroraction SilentlyContinue

   if (!$?)
       {write-host "Ping failed: $ComputerName."; return $false}
   else
       {write-host "Ping succeeded: $ComputerName"; return $true}
}

function CanRemote {
    $s = new-pssession $computername -erroraction SilentlyContinue

    if ($s -is [System.Management.Automation.Runspaces.PSSession])
        {write-host "Remote test succeeded: $ComputerName."}
    else
        {write-host "Remote test failed: $ComputerName."}
}

if (CanPing $computername) {CanRemote $computername}

Als u dit script wilt uitvoeren, typt u de parameternaam achter de scriptnaam. Voorbeeld:

C:\PS> .\test-remote.ps1 -computername Server01

Ping succeeded: Server01
Remote test failed: Server01

Zie about_Functions en about_Functions_Advanced_Parameters voor meer informatie over de parameter Param en de functieparameters.

Hulp schrijven voor scripts

U kunt een Help-onderwerp voor een script schrijven met behulp van een van de volgende twee methoden:

• Hulp op basis van opmerkingen voor scripts

  Een Help-onderwerp maken met speciale trefwoorden in de opmerkingen. Als u hulp op basis van opmerkingen voor een script wilt maken, moeten de opmerkingen aan het begin of einde van het scriptbestand worden geplaatst. Zie about_Comment_Based_Help voor meer informatie over Help op basis van opmerkingen.

• Op XML gebaseerde Help voor scripts

  Maak een Help-onderwerp op basis van XML, zoals het type dat doorgaans wordt gemaakt voor cmdlets. Help op basis van XML is vereist als u Help-onderwerpen in meerdere talen vertaalt.

Als u het script wilt koppelen aan het Help-onderwerp op basis van XML, gebruikt u het . Trefwoord voor opmerkingen van ExternalHelp Help. Zie about_Comment_Based_Help voor meer informatie over het sleutelwoord ExternalHelp. Zie Help voor cmdlets schrijven voor meer informatie over help op basis van XML.

Een afsluitwaarde retourneren

Scripts retourneren standaard geen afsluitstatus wanneer het script eindigt. U moet de exit instructie gebruiken om een afsluitcode van een script te retourneren. Standaard retourneert 0de exit instructie . U kunt een numerieke waarde opgeven om een andere afsluitstatus te retourneren. Een niet-nul-afsluitcode geeft meestal een fout aan.

In Windows is een willekeurig getal tussen [int]::MinValue en [int]::MaxValue toegestaan.

Op Unix zijn alleen positieve getallen tussen [byte]::MinValue (0) en [byte]::MaxValue (255) toegestaan. Een negatief getal in het bereik van -1 doorloop -255 wordt automatisch omgezet in een positief getal door 256 toe te voegen. Wordt bijvoorbeeld -2 getransformeerd naar 254.

In PowerShell stelt de exit instructie de waarde van de $LASTEXITCODE variabele in. In de Windows Command Shell (cmd.exe) stelt de afsluitinstructie de waarde van de %ERRORLEVEL% omgevingsvariabele in.

Elk argument dat niet-numeriek of buiten het platformspecifieke bereik valt, wordt omgezet in de waarde van 0.

Scriptbereik en puntbronnen

Elk script wordt uitgevoerd in een eigen bereik. De functies, variabelen, aliassen en stations die in het script zijn gemaakt, bestaan alleen in het scriptbereik. U hebt geen toegang tot deze items of de bijbehorende waarden in het bereik waarin het script wordt uitgevoerd.

Als u een script in een ander bereik wilt uitvoeren, kunt u een bereik opgeven, zoals Globaal of Lokaal, of u kunt een punt toevoegen aan de bron van het script.

Met de functie dot-sourcing kunt u een script uitvoeren in het huidige bereik in plaats van in het scriptbereik. Wanneer u een script uitvoert dat is afkomstig van een punt, worden de opdrachten in het script uitgevoerd alsof u ze bij de opdrachtprompt hebt getypt. De functies, variabelen, aliassen en stations die door het script worden gemaakt, worden gemaakt in het bereik waarin u werkt. Nadat het script is uitgevoerd, kunt u de gemaakte items gebruiken en de bijbehorende waarden in uw sessie openen.

Als u een script wilt toevoegen aan een punt, typt u een punt (.) en een spatie vóór het scriptpad.

Voorbeeld:

. C:\scripts\UtilityFunctions.ps1

or

. .\UtilityFunctions.ps1

Nadat het UtilityFunctions.ps1 script is uitgevoerd, worden de functies en variabelen die door het script worden gemaakt, toegevoegd aan het huidige bereik.

Het script maakt bijvoorbeeld UtilityFunctions.ps1 de New-Profile functie en de $ProfileName variabele.

#In UtilityFunctions.ps1

function New-Profile
{
  Write-Host "Running New-Profile function"
  $profileName = split-path $profile -leaf

  if (test-path $profile)
    {write-error "Profile $profileName already exists on this computer."}
  else
    {new-item -type file -path $profile -force }
}

Als u het UtilityFunctions.ps1 script uitvoert in een eigen scriptbereik, bestaan de New-Profile functie en de $ProfileName variabele alleen terwijl het script wordt uitgevoerd. Wanneer het script wordt afgesloten, worden de functie en variabele verwijderd, zoals wordt weergegeven in het volgende voorbeeld.

C:\PS> .\UtilityFunctions.ps1

C:\PS> New-Profile
The term 'new-profile' is not recognized as a cmdlet, function, operable
program, or script file. Verify the term and try again.
At line:1 char:12
+ new-profile <<<<
   + CategoryInfo          : ObjectNotFound: (new-profile:String) [],
   + FullyQualifiedErrorId : CommandNotFoundException

C:\PS> $profileName
C:\PS>

Wanneer u een punt in het script opgeeft en het uitvoert, maakt het script de New-Profile functie en de $ProfileName variabele in uw sessie in uw bereik. Nadat het script is uitgevoerd, kunt u de New-Profile functie in uw sessie gebruiken, zoals wordt weergegeven in het volgende voorbeeld.

C:\PS> . .\UtilityFunctions.ps1

C:\PS> New-Profile

    Directory: C:\Users\juneb\Documents\WindowsPowerShell

    Mode    LastWriteTime     Length Name
    ----    -------------     ------ ----
    -a---   1/14/2009 3:08 PM      0 Microsoft.PowerShellISE_profile.ps1

C:\PS> $profileName
Microsoft.PowerShellISE_profile.ps1

Zie about_Scopes voor meer informatie over het bereik.

Scripts in modules

Een module is een set gerelateerde PowerShell-resources die kunnen worden gedistribueerd als een eenheid. U kunt modules gebruiken om uw scripts, functies en andere resources te ordenen. U kunt ook modules gebruiken om uw code naar anderen te distribueren en om code op te halen uit vertrouwde bronnen.

U kunt scripts opnemen in uw modules of u kunt een scriptmodule maken. Dit is een module die volledig of voornamelijk uit een script en ondersteunende resources bestaat. Een scriptmodule is slechts een script met de bestandsextensie .psm1.

Zie about_Modules voor meer informatie over modules.

Andere scriptfuncties

PowerShell heeft veel nuttige functies die u in scripts kunt gebruiken.

• #Requires - U kunt een #Requires instructie gebruiken om te voorkomen dat een script wordt uitgevoerd zonder opgegeven modules of modules en een opgegeven versie van PowerShell. Zie about_Requires voor meer informatie.

• $PSCommandPath - Bevat het volledige pad en de naam van het script dat wordt uitgevoerd. Deze parameter is geldig in alle scripts. Deze automatische variabele wordt geïntroduceerd in PowerShell 3.0.

• $PSScriptRoot - Bevat de map waaruit een script wordt uitgevoerd. In PowerShell 2.0 is deze variabele alleen geldig in scriptmodules (.psm1). Vanaf PowerShell 3.0 is deze geldig in alle scripts.

• $MyInvocation - De $MyInvocation automatische variabele bevat informatie over het huidige script, inclusief informatie over hoe deze is gestart of 'aangeroepen'. U kunt deze variabele en de eigenschappen ervan gebruiken om informatie over het script op te halen terwijl het wordt uitgevoerd. Bijvoorbeeld de $MyInvocation. De variabele MyCommand.Path bevat het pad en de bestandsnaam van het script. $MyInvocation. Regel bevat de opdracht waarmee het script is gestart, inclusief alle parameters en waarden.

  Vanaf PowerShell 3.0 $MyInvocation beschikt u over twee nieuwe eigenschappen die informatie bieden over het script dat het huidige script heeft aangeroepen of aangeroepen. De waarden van deze eigenschappen worden alleen ingevuld wanneer de aanroeper of aanroeper een script is.

  • PSCommandPath bevat het volledige pad en de naam van het script dat het huidige script heeft aangeroepen of aangeroepen.

  • PSScriptRoot bevat de map van het script dat het huidige script heeft aangeroepen of aangeroepen.

  In tegenstelling tot de $PSCommandPath en $PSScriptRoot automatische variabelen, die informatie over het huidige script bevatten, bevatten de eigenschappen PSCommandPath en PSScriptRoot van de $MyInvocation variabele informatie over het script dat het huidige script wordt genoemd.

• Gegevenssecties: u kunt het Data trefwoord gebruiken om gegevens te scheiden van logica in scripts. Gegevenssecties kunnen ook lokalisatie vereenvoudigen. Zie about_Data_Sections en about_Script_Internationalization voor meer informatie.

• Scriptondertekening: u kunt een digitale handtekening toevoegen aan een script. Afhankelijk van het uitvoeringsbeleid kunt u digitale handtekeningen gebruiken om het uitvoeren van scripts met onveilige opdrachten te beperken. Zie about_Execution_Policies en about_Signing voor meer informatie.

Zie ook

• about_Command_Precedence
• about_Comment_Based_Help
• about_Execution_Policies
• about_Functions
• about_Modules
• about_Profiles
• about_Requires
• about_Run_With_PowerShell
• about_Scopes
• about_Script_Blocks
• about_Signing
• Invoke-Command