TOPIC
	about_Scripts

SHORT DESCRIPTION
	Describes how to write and run scripts in Windows PowerShell.

LONG DESCRIPTION
	A script is a plain text file that contains one or more Windows PowerShell
	commands. Windows PowerShell scripts have a .ps1 file name extension. 

	Writing a script saves a command for later use and makes it easy to share
	with others. Most importantly, it lets you run the commands simply by typing
	the script path and the file name. Scripts can be as simple as a single 
	command in a file or as extensive as a complex program.

	Scripts have additional features, such as the #Requires special comment,
	the use of parameters, support for data sections, and digital signing for
	security. You can also write Help topics for scripts and for any functions
	in the script. 

  HOW TO WRITE A SCRIPT

	A script can contain any valid Windows PowerShell commands, including single
	commands, commands that use the pipeline, functions, and control structures
	such as If statements and For loops.

	To write a script, start a text editor (such as Notepad) or a script editor
	(such as the Windows PowerShell Integrated Scripting Environment [ISE]). Type 
	the commands and save them in a file with a valid file name and the .ps1 file
	name extension. 

	The following example is a simple script that gets the services that are
	running on the current system and saves them to a log file. The log file name
	is created from the current date.

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

	To create this script, open a text editor or a script editor, type these
	commands, and then save them in a file named ServiceLog.ps1. 


  HOW TO RUN A SCRIPT

	Before you can run a script, you need to change the default Windows
	PowerShell execution policy. The default execution policy, "Restricted",
	prevents all scripts from running, including scripts that you write on the
	local computer. For more information, see about_Execution_Policies.

	To run a script, type the full name and the full path to the script file. 

	For example, to run the ServicesLog script in the C:\Scripts directory, type:

		c:\scripts\ServicesLog.ps1

	To run a script in the current directory, type the path to the current
	directory, or use a dot to represent the current directory, followed by
	a path backslash (.\).

	For example, to run the ServicesLog.ps1 script in the local directory, type:

		.\ServicesLog.ps1

	As a security feature, Windows PowerShell does not run scripts when you
	double-click the script icon in Windows Explorer or when you type the 
	script name without a full path, even when the script is in the current 
	directory. For more information about running commands and scripts in
	Windows PowerShell, see about_Command_Precedence.


  RUNNING SCRIPTS REMOTELY

	To run a script on a remote computer, use the FilePath parameter of the
	Invoke-Command cmdlet.

	Enter the path and file name of the script as the value of the FilePath 
	parameter. The script must reside on the local computer or in a directory
	that the local computer can access. 

	The following command runs the ServicesLog.ps1 script on the Server01 remote
	computer.

		invoke-command -computername Server01 -filepath C:\scripts\servicesLog.ps1 


  PARAMETERS IN SCRIPTS

	To define parameters in a script, use a Param statement. The Param statement
	must be the first statement in a script, except for comments and any 
	#Requires statements.

	Script parameters work like function parameters. The parameter values are
	available to all of the commands in the script. All of the features of
	function parameters, including the Parameter attribute and its named
	arguments, are also valid in scripts.

	When running the script, script users type the parameters after the script
	name. 

	The following example shows a Test-Remote.ps1 script that has a ComputerName
	parameter. Both of the script functions can access the ComputerName
	parameter value.

		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}


	To run this script, type the parameter name after the script name.  
	For example:

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

		Ping succeeded: Server01
		Remote test failed: Server01


	For more information about the Param statement and the function parameters,
	see about_Functions and about_Functions_Advanced_Parameters.



  HELP FOR SCRIPTS

	The Get-Help cmdlet gets Help for scripts as well as for cmdlets,
	providers, and functions. To get Help for a script, type Get-Help and the
	path and file name of the script. If the script path is in your Path
	environment variable, you can omit the path.

	For example, to get Help for the ServicesLog.ps1 script, type:

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

	You can write Help for a script by using either of the two following methods:

	--  Comment-Based Help for Scripts

		Create a Help topic by using special keywords in the comments. To create
		comment-based Help for a script, the comments must be placed at the
		beginning or end of the script file. For more information about
		comment-based Help, see about_Comment_Based_Help.

	--  XML-Based Help  for Scripts

		Create an XML-based Help topic, such as the type that is typically
		created for cmdlets. XML-based Help is required if you are translating
		Help topics into multiple languages.  

		To associate the script with the XML-based Help topic, use the
		.ExternalHelp Help comment keyword. For more information about the
		ExternalHelp keyword, see about_Comment_Based_Help. For more information
		about XML-based help, see "How to Write Cmdlet Help" in the MSDN
		(Microsoft Developer Network) library at 
		http://go.microsoft.com/fwlink/?LinkID=123415.


  SCRIPT SCOPE AND DOT SOURCING

	Each script runs in its own scope. The functions, variables, aliases, and
	drives that are created in the script exist only in the script scope. You
	cannot access these items or their values in the scope in which the
	script runs.

	To run a script in a different scope, you can specify a scope, such as
	Global or Local, or you can dot source the script.

	The dot sourcing feature lets you run a script in the current scope instead
	of in the script scope. When you run a script that is dot sourced, the 
	commands in the script run as though you had typed them at the command 
	prompt. The functions, variables, aliases, and drives that the script 
	creates are created in the scope in which you are working. After the script
	runs, you can use the created items and access their values in your session.

	To dot source a script, type a dot (.) and a space before the script path.

	For example:

		. C:\scripts\UtilityFunctions.ps1

	-or-

		. .\UtilityFunctions.ps1


	After the UtilityFunctions script runs, the functions and variables that the
	script creates are added to the current scope. 
  
	For example, the UtilityFunctions.ps1 script creates the New-Profile
	function and the $ProfileName variable.

		#In UtilityFunctions.ps1

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

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


	If you run the UtilityFunctions.ps1 script in its own script scope, the
	New-Profile function and the $ProfileName variable exist only while the
	script is running. When the script exits, the function and variable are
	removed, as shown in the following example.

		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>


	When you dot source the script and run it, the script creates the
	New-Profile function and the $ProfileName variable in your session in your
	scope. After the script runs, you can use the New-Profile function in your
	session, as shown in the following example.

		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


	For more information about scope, see about_Scopes.


  SCRIPTS IN MODULES

	A module is a set of related Windows PowerShell resources that can be
	distributed as a unit. You can use modules to organize your scripts,
	functions, and other resources. You can also use modules to distribute your
	code to others, and to get code from trusted sources.

	You can include scripts in your modules, or you can create a script module,
	which is a module that consists entirely or primarily of a script and 
	supporting resources. A script module is just a script with a .psm1 file
	name extension.

	For more information about modules, see about_Modules.


  OTHER SCRIPT FEATURES 

	Windows PowerShell has many useful features that you can use in scripts.

	#Requires 
		You can use a #Requires statement to prevent a script from running
		without specified modules or snap-ins and a specified version of
		Windows PowerShell. For more information, see about_Requires.

	$MyInvocation
		The $MyInvocation automatic variable contains information about the
		current command, including the current script. You can use this variable
		and its properties to get information about the script while it is
		running. For example, the $MyInvocation.MyCommand.Path variable contains
		the path and file name of the script.

	Data sections
		You can use the Data keyword to separate data from logic in scripts.
		Data sections can also make localization easier. For more information,
		see about_Data_Sections and about_Script_Localization.

	Script Signing
		You can add a digital signature to a script. Depending on the execution
		policy, you can use digital signatures to restrict the running of scripts
		that could include unsafe commands. For more information, see
		about_Execution_Policies and about_Signing.



SEE ALSO
	about_Command_Precedence
	about_Comment_Based_Help
	about_Execution_Policies
	about_Functions
	about_Modules
	about_Profiles
	about_Requires
	about_Scopes
	about_Script_Blocks
	about_Signing
	Invoke-Command