如何支持就业

此示例演示如何在编写 cmdlet 时支持作业。如果您希望用户将 cmdlet 作为后台作业运行，则必须包含以下过程中描述的代码。有关后台作业的更多信息，请参阅后台作业。

支持就业

1. 定义 AsJob 开关参数，以便用户可以决定是否将 cmdlet 作为作业运行。

   以下示例显示了 AsJob 参数声明。

   [Parameter()]
   public SwitchParameter AsJob
   {
     get { return asjob; }
     set { asjob = value; }
   }
   private bool asjob;
   

2. 创建一个派生自 System.Management.Automation.Job 类的对象。此对象可以是自定义作业对象或 Windows PowerShell 提供的作业对象之一，例如 System.Management.Automation.Pseventjob 对象。

   以下示例显示了自定义作业对象。

   private SampleJob job = new SampleJob("Get-ProcAsJob");
   

3. 在记录处理方法中，添加 if 语句来检测 cmdlet 是否应作为作业运行。以下代码使用 System.Management.Automation.Cmdlet.ProcessRecord 方法。

   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);
       }
     }
   }
   

4. 对于自定义作业对象，实现作业类。

   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.
   

5. 如果 cmdlet 执行该工作，请调用 System.Management.Automation.Cmdlet.WriteObject 方法将进程对象返回到管道。如果工作作为作业执行，请将子作业添加到作业中。

   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.
   

例子

以下示例代码显示了可以在内部或使用后台作业检索进程的 Get-Proc cmdlet 的代码。

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
}