about_Requires

Applies To: Windows PowerShell 2.0

TOPIC
    about_Requires

SHORT DESCRIPTION
    Prevents a script from running by requiring the specified snap-ins and 
    version.

LONG DESCRIPTION
    The #Requires statement prevents a script from running unless the Windows 
    PowerShell version, snap-in, and snap-in version prerequisites are met. If 
    the prerequisites are not met, Windows PowerShell does not run the script. 

    You can use #Requires statements in any script. You cannot use them in 
    functions, cmdlets, or snap-ins. 


  Syntax 

      Use the following syntax to specify the snap-in and the version of the 
      snap-in that you want to require: 

          #requires –PsSnapIn <PsSnapIn> [-Version <N>[.<n>]]


      Use the following syntax to specify the minimum version of 
      Windows PowerShell that you want to require: 

          #requires -Version <N>[.<n>]


      Use the following syntax to specify the shell that you want to require: 

          #requires –ShellId <ShellId>


  Rules for Use 

      - The #Requires statement must be the first item on a line in a script.

      - A script can include more than one #Requires statement. 

      - The #Requires statements can appear on any line in a script.


  Examples

      The following statement requires the Microsoft.PowerShell.Security 
      snap-in:

          #requires –PsSnapIn Microsoft.PowerShell.Security


      If the Microsoft.PowerShell.Security snap-in is not loaded, the script 
      does not run, and Windows PowerShell displays the following error 
      message: 

          "The script '<script-name>' cannot be run because the following 
          Windows PowerShell snap-ins that are specified by its "#requires" 
          statements are missing: Microsoft.PowerShell.Security." 


      The following statement requires the Windows PowerShell 2.0 version or
      any later version of the Microsoft.PowerShell.Security snap-in:

          #requires –PsSnapIn Microsoft.PowerShell.Security –Version 2


      The following statement requires Windows PowerShell 2.0 or a later 
      version:

          #requires –Version 2.0


      The following script has two #Requires statements. The requirements 
      specified in both statements must be met. Otherwise, the script will not
      run. Each #Requires statement must be the first item on a line:

          #requires –PsSnapIn Microsoft.PowerShell.Security –Version 2
          Get-WMIObject WIN32_LogicalDisk | out-file K:\status\DiskStatus.txt
          #requires –Version 2


      The following #Requires statement prevents a script from running if the 
      specified shell ID does not match the current shell ID. The current 
      shell ID is stored in the $ShellId variable:

          #requires –ShellId MyLocalShell


SEE ALSO
    about_Automatic_Variables 
    about_Language_Keywords
    about_PSSnapins
    get-PSSnapin