description | ms.date | ms.topic | title |
---|---|---|---|
How to Support Jobs |
09/22/2021 |
reference |
How to Support Jobs |
This example shows how to support jobs when you write cmdlets. If you want users to run your cmdlet as a background job, you must include the code described in the following procedure. For more information about background jobs, see Background Jobs.
-
Define an
AsJob
switch parameter so that the user can decide whether to run the cmdlet as a job.The following example shows an AsJob parameter declaration.
[Parameter()] public SwitchParameter AsJob { get { return asjob; } set { asjob = value; } } private bool asjob;
-
Create an object that derives from the System.Management.Automation.Job class. This object can be a custom job object or one of the job objects provided by Windows PowerShell, such a System.Management.Automation.Pseventjob object.
The following example shows a custom job object.
private SampleJob job = new SampleJob("Get-ProcAsJob");
-
In a record processing method, add an
if
statement to detect whether the cmdlet should run as a job. The following code uses the System.Management.Automation.Cmdlet.ProcessRecord method.protected override void ProcessRecord() { if (asjob) { // Add the job definition to the job repository, // return the job object, and then create the thread // used to run the job. JobRepository.Add(job); WriteObject(job); ThreadPool.QueueUserWorkItem(WorkItem); } else { job.ProcessJob(); foreach (PSObject p in job.Output) { WriteObject(p); } } }
-
For custom job objects, implement the job class.
private class SampleJob : Job { internal SampleJob(string command) : base(command) { SetJobState(JobState.NotStarted); } public override string StatusMessage { get { throw new NotImplementedException(); } } public override bool HasMoreData { get { return hasMoreData; } } private bool hasMoreData = true; public override string Location { get { throw new NotImplementedException(); } } public override void StopJob() { throw new NotImplementedException(); } internal void ProcessJob() { SetJobState(JobState.Running); DoProcessLogic(); SetJobState(JobState.Completed); } // Retrieve the processes of the local computer. void DoProcessLogic() { Process[] p = Process.GetProcesses(); foreach (Process pl in p) { Output.Add(PSObject.AsPSObject(pl)); } Output.Complete(); } // End DoProcessLogic. } // End SampleJob class.
-
If the cmdlet performs the work, call the System.Management.Automation.Cmdlet.WriteObject method to return a process object to the pipeline. If the work is performed as a job, add child job to the job.
void DoProcessLogic(bool asJob) { Process[] p = Process.GetProcesses(); foreach (Process pl in p) { if (!asjob) { WriteObject(pl); } else { job.ChildJobs[0].Output.Add(PSObject.AsPSObject(pl)); } } } // End DoProcessLogic.
The following sample code shows the code for a Get-Proc
cmdlet that can retrieve processes
internally or by using a background job.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Management.Automation; // Windows PowerShell namespace.
using System.Threading; // Thread pool namespace for posting work.
using System.Diagnostics; // Diagnostics namespace for retrieving
// process objects.
// This sample shows a cmdlet whose work can be done by the cmdlet or by using
// a background job. Background jobs are executed in their own thread,
// independent of the pipeline thread in which the cmdlet is executed.
//
// To load this cmdlet, create a module folder and copy the GetProcessSample06.dll
// assembly into the module folder. Make sure that the path to the module folder
// is added to the $PSModulePath environment variable.
// Module folder path:
// user/documents/WindowsPowerShell/modules/GetProcessSample06
//
// To import the module, run the following command: Import-Module GetProcessSample06.
// To test the cmdlet, run the following command: Get-Proc -name <process name>
//
//
namespace Microsoft.Samples.PowerShell.Commands
{
/// <summary>
/// This cmdlet retrieves process internally or returns
/// a job that retrieves the processes.
/// </summary>
[Cmdlet(VerbsCommon.Get, "Proc")]
public sealed class GetProcCommand : PSCmdlet
{
#region Parameters
/// <summary>
/// Specify the Name parameter. This parameter accepts
/// process names from the command line.
/// </summary>
[Parameter(
Position = 0,
ValueFromPipeline = true,
ValueFromPipelineByPropertyName = true)]
[ValidateNotNullOrEmpty]
public string[] Name
{
get { return processNames; }
set { processNames = value; }
}
private string[] processNames;
/// <summary>
/// Specify the AsJob parameter. This parameter indicates
/// whether the cmdlet should retrieve the processes internally
/// or return a Job object that retrieves the processes.
/// </summary>
[Parameter()]
public SwitchParameter AsJob
{
get { return asjob; }
set { asjob = value; }
}
private bool asjob;
#endregion Parameters
#region Cmdlet Overrides
// Create a custom job object.
private SampleJob job = new SampleJob("Get-ProcAsJob");
/// <summary>
/// Determines if the processes should be retrieved
/// internally or if a Job object should be returned.
/// </summary>
protected override void ProcessRecord()
{
if (asjob)
{
// Add the job definition to the job repository,
// return the job object, and then create the thread
// used to run the job.
JobRepository.Add(job);
WriteObject(job);
ThreadPool.QueueUserWorkItem(WorkItem);
}
else
{
job.ProcessJob();
foreach (PSObject p in job.Output)
{
WriteObject(p);
}
}
}
#endregion Overrides
// Implement a custom job that derives
// from the System.Management.Automation.Job class.
private class SampleJob : Job
{
internal SampleJob(string command)
: base(command)
{
SetJobState(JobState.NotStarted);
}
public override string StatusMessage
{
get { throw new NotImplementedException(); }
}
public override bool HasMoreData
{
get
{
return hasMoreData;
}
}
private bool hasMoreData = true;
public override string Location
{
get { throw new NotImplementedException(); }
}
public override void StopJob()
{
throw new NotImplementedException();
}
internal void ProcessJob()
{
SetJobState(JobState.Running);
DoProcessLogic();
SetJobState(JobState.Completed);
}
// Retrieve the processes of the local computer.
void DoProcessLogic()
{
Process[] p = Process.GetProcesses();
foreach (Process pl in p)
{
Output.Add(PSObject.AsPSObject(pl));
}
Output.Complete();
} // End DoProcessLogic.
} // End SampleJob class.
void WorkItem(object dummy)
{
job.ProcessJob();
}
// Display the results of the work. If not a job,
// process objects are returned. If a job, the
// output is added to the job as a child job.
void DoProcessLogic(bool asJob)
{
Process[] p = Process.GetProcesses();
foreach (Process pl in p)
{
if (!asjob)
{
WriteObject(pl);
}
else
{
job.ChildJobs[0].Output.Add(PSObject.AsPSObject(pl));
}
}
} // End DoProcessLogic.
} //End GetProcCommand
}