home *** CD-ROM | disk | FTP | other *** search
/ Chip 2008 June / CHIP-2008-06.iso / software / PowerShell / PowerShell_Setup_x86.msi / product.cab / about_psjob.help_EN.txt < prev    next >
Encoding:
Text File  |  2007-10-29  |  8.7 KB  |  221 lines
  1. TOPIC
  2.     Background job
  3.  
  4. SHORT DESCRIPTION
  5.     A Windows PowerShell background job (PsJob) runs a command or expression 
  6.      "in the background" without interacting with the console. When you start
  7.     a background job, the command prompt returns immediately, even if the job takes
  8.     an extended time to complete. You can continue to use the console without
  9.     interruption while the job runs. You can run background jobs on a local or
  10.     remote computer.
  11.  
  12.     NOTE:  The Windows PowerShell 2.0 background job (PsJob) feature relies
  13.            on remoting technology. To use PsJob, remoting must be enabled on
  14.            Windows PowerShell, even if the PsJob runs on the local computer.
  15.  
  16.  
  17. LONG DESCRIPTION
  18.     A background job runs a command or expression asynchronously. It might run a 
  19.     cmdlet, a function, a script, a ScriptCmdlet, or any other command-based task.
  20.     It is designed to run commands that take an extended period of time, but you
  21.     can use it to run any command "in background".
  22.  
  23.     When a regular command runs, the Windows PowerShell command prompt is suppressed
  24.     until the command completes. But a background job does not suppress the Windows
  25.     PowerShell prompt; the prompt returns immediately after you start the job so you
  26.     can work on other tasks while the background job runs.
  27.   
  28.     However, when you start a background job, you do not get the results immediately, 
  29.     even if the job runs very quickly. Instead of the result, you get a job object
  30.     that represents the job. You can use the job object to request the result of the
  31.     background job. If the job is not completed, you can get partial results or wait
  32.     for the job to complete and then get complete results.
  33.  
  34.     To make the timing of a background job independent of other commands, each background
  35.     job run in its own Windows PowerShell environment (a "runspace"). However, this
  36.     can be a temporary runspace that is created only to run the job and is then destroyed,
  37.     or a persistent runspace that you can use to run several related jobs or commands.
  38.  
  39.     You can create and manage background jobs on a local or remote computer. To run a
  40.     background job remotely, use the ComputerName parameter of the Start-PsJob cmdlet
  41.     specify the name of the remote computer, or use the New-Runspace cmdlet to create
  42.     a persistent runspace on the remote computer, and then use Runspace parameter of
  43.     Start-PsJob to specify the remote runspace.
  44.  
  45.         
  46.  
  47. CREATING BACKGROUND JOBS
  48.     Windows PowerShell has a set of PsJob cmdlets to help you create and manage 
  49.     background jobs.
  50.     
  51.     To create a job, use the New-PsJob or Start-PsJob cmdlet. The following command
  52.     uses the Start-PsJob cmdlet to start a background job that runs a Get-Process 
  53.     command on the local computer.
  54.  
  55.         start-psjob -command "get-process"
  56.  
  57.     You can also start jobs on remote computers. The following command runs a 
  58.     similar background job in a temporary runspace on the Server01 computer.
  59.  
  60.         start-psjob -command "get-process" -computername Server01
  61.  
  62.     If the computer is in a different domain, you might need to use the Credential
  63.     parameter to run the command with the permissions of a member of the Administrators
  64.     group on the computer, as shown in the following command:
  65.  
  66.         start-psjob -command "get-process" -computername Server01 -credential domain01\admin01
  67.  
  68.     You can also run a background job in a runspace on a local or remote computer. The
  69.     following command creates a runspace on the Server01 computer and then runs the
  70.     background job in the new runspace.
  71.  
  72.         $r = new-runspace -computername Server01 
  73.         
  74.         start-psjob -command "get-process" -runspace $r
  75.  
  76.  
  77.  
  78. GETTING THE RESULTS OF A BACKGROUND JOB
  79.  
  80.     When you run a background job, the results do not appear immediately. Instead, the
  81.     Start-PsJob cmdlet returns a job object that respresents the job. The following command
  82.     saves the job object in the $job variable.
  83.  
  84.         $job = start-psjob -command "get-process" -computername Server01
  85.  
  86.     To get the results of the job, use the Receive-PsJob cmdlet. The following command gets
  87.     the results of the job running on the Server01 computer. The command uses the $job object
  88.     that represents the job.
  89.  
  90.     receive-psjob -job $job
  91.  
  92.            Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
  93.            -------  ------    -----      ----- -----   ------     -- -----------
  94.                103       4    11328       9692    56            1176 audiodg
  95.                804      14    12228      14108   100   101.74   1740 CcmExec
  96.                668       7     2672       6168   104    32.26    488 csrss
  97.                 79       4    11668       4076    90     2.50    552 csrss
  98.                374       5     3548       9284   143    10.19    836 csrss
  99.        ...
  100.  
  101.     
  102. WAITING FOR THE RESULTS
  103.  
  104.     If you run a command that takes a long time to complete, you can use the properties
  105.     of the job object to determine when the job is complete. The following command uses
  106.     the Get-PsJob object to get all of the background jobs in the current console.
  107.  
  108.     get-psjob
  109.  
  110.     The result appear in a table. The status of the job appears in the State column.
  111.  
  112.         SessionId       Name            Command                   State
  113.         ---------       ----            -------                   -----
  114.         2                               get-eventlog -log syst... Completed
  115.         4                               & .\search-files.ps1...   Failed
  116.         6                               get-process               Failed
  117.         8                               get-process               Completed
  118.         10                              get-eventlog -system      Running
  119.  
  120.  
  121.     In this case, the State property reveals that Job 10 is still running. If you were to
  122.     use the Receive-PsJob cmdlet to get the job results now, the results would be incomplete.
  123.     You can use the Receive-PsJob cmdlet repeatedly to get all of the results. By default, each
  124.     time you use it, you get only the results that were not already received, but you can use
  125.     the Keep parameter of the Receive-PsJob cmdlet to retain the results, even though they are
  126.     received.
  127.  
  128.     At this point, you can write the results to a file and then append the newly received
  129.     results as they arrive, or simply wait and check the state of the job later.
  130.  
  131.     Or, you can use the Wait-PsJob cmdlet to wait for any or all of the results of the job. 
  132.     Wait-PsJob lets you wait for a particular job, for all jobs, or for any of the job
  133.     to complete.
  134.   
  135.     The following command uses the Wait-PsJob cmdlet to wait for a job with SessionID 10.
  136.  
  137.     wait-psjob -sessionID 10
  138.  
  139.     As a result, the Windows Powershell prompt is suppressed until the job completes.
  140.  
  141.     You can also wait for a predetermined period of time. This command uses the Timeout 
  142.     parameter to limit the wait to 
  143.  
  144.  
  145. STOPPING A JOB
  146.  
  147.     To stop a background job, use the Stop-PsJob cmdlet. The following command 
  148.     starts a job to get every entry in the System event log. It saves the job
  149.     object in the $job variable.
  150.  
  151.     $job = start-psjob -command "get-eventlog -log system"
  152.     
  153.     The following command stops the job. It uses a pipeline operator (|) to
  154.     send the job in the $job variable to Stop-PsJob.
  155.  
  156.     $job | stop-psjob
  157.  
  158.  
  159. DELETING A JOB
  160.  
  161.     To delete a background job, use the Remove-PsJob cmdlet. The following command 
  162.     deletes all jobs in the current console.
  163.  
  164.     remove-psjob
  165.  
  166.  
  167. INVESTIGATING A FAILED JOB
  168.  
  169.     To find out why a job failed, use the Reason subproperty of the job object. 
  170.  
  171.     The following command starts a job on a remote computer without the required
  172.     credentials. It saves the job object in the $job variable.
  173.  
  174.  
  175.          $job = start-psjob -computername Server02 -command "dir"
  176.  
  177.              SessionId       Name            Command                   State
  178.              ---------       ----            -------                   -----
  179.              3                               dir                        Failed
  180.  
  181.     The following command uses the Reason property to find the error that caused
  182.     the job to fail.
  183.  
  184.          $job.ChildJobs[0].JobStateInfo.Reason
  185.  
  186.  
  187.     In this case, the job failed because the remote computer required explicit 
  188.     credentials to run the command. The value of the Reason property is:
  189.  
  190.         Connection attempt failed.
  191.  
  192.  
  193. SEE ALSO
  194.  
  195.     For a list of background job (psjob) cmdlets, type:
  196.     
  197.     get-help *-psjob
  198.  
  199.  
  200.     For a list of runspace cmdlets, type:
  201.     
  202.     get-help *-runspace
  203.  
  204.  
  205.     For more information about Windows PowerShell remote operation, type:
  206.  
  207.     get-help about_remoting
  208.  
  209.  
  210.  
  211.     
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.