创建 Cmdlet 来访问数据存储

本部分介绍如何创建通过 Windows PowerShell 提供程序访问存储数据的 cmdlet。此类 cmdlet 使用 Windows PowerShell 运行时的 Windows PowerShell 提供程序基础结构，因此 cmdlet 类必须派生自 System.Management.Automation.PSCmdlet 基类。

此处描述的 Select-Str cmdlet 可以定位并选择文件或对象中的字符串。用于标识字符串的模式可以通过 cmdlet 的 Path 参数显式指定，也可以通过 Script 参数隐式指定。

该 cmdlet 设计为使用派生自 System.Management.Automation.Provider.Icontentcmdletprovider 的任何 Windows PowerShell 提供程序。例如，cmdlet 可以指定 Windows PowerShell 提供的文件系统提供程序或变量提供程序。有关 Windows PowerShell 提供程序的详细信息，请参阅设计 Windows PowerShell 提供程序。

定义 Cmdlet 类

创建 cmdlet 的第一步始终是命名 cmdlet 并声明实现该 cmdlet 的 .NET 类。此 cmdlet 检测某些字符串，因此此处选择的动词名称是“Select”，由 System.Management.Automation.Verbscommon 类定义。使用名词名称“Str”是因为 cmdlet 作用于字符串。在下面的声明中，请注意 cmdlet 动词和名词名称反映在 cmdlet 类的名称中。有关批准的 cmdlet 动词的详细信息，请参阅 Cmdlet 动词名称。

此 cmdlet 的 .NET 类必须派生自 System.Management.Automation.PSCmdlet 基类，因为它提供 Windows PowerShell 运行时公开 Windows PowerShell 提供程序基础结构所需的支持。请注意，此 cmdlet 还使用 .NET Framework 正则表达式类，例如 System.Text.Regularexpressions.Regex。

以下代码是此 Select-Str cmdlet 的类定义。

[Cmdlet(VerbsCommon.Select, "Str", DefaultParameterSetName="PatternParameterSet")]
public class SelectStringCommand : PSCmdlet

此 cmdlet 通过将 DefaultParameterSetName 属性关键字添加到类声明中来定义默认参数集。当未指定 Script 参数时，将使用默认参数集 PatternParameterSet。有关此参数集的更多信息，请参阅下一节中的 Pattern 和 Script 参数讨论。

定义数据访问参数

此 cmdlet 定义了多个参数，允许用户访问和检查存储的数据。这些参数包括一个 Path 参数（用于指示数据存储的位置）、一个 Pattern 参数（用于指定搜索中使用的模式）以及其他几个支持搜索方式的参数。执行搜索。

笔记

有关定义参数的基础知识的更多信息，请参阅添加处理命令行输入的参数。

声明路径参数

要查找数据存储，此 cmdlet 必须使用 Windows PowerShell 路径来标识旨在访问数据存储的 Windows PowerShell 提供程序。因此，它定义了一个字符串数组类型的Path参数来指示提供者的位置。

[Parameter(
           Position = 0,
           ParameterSetName = "ScriptParameterSet",
           Mandatory = true)]
[Parameter(
           Position = 0,
           ParameterSetName = "PatternParameterSet",
           ValueFromPipeline = true,
           Mandatory = true)]
           [Alias("PSPath")]
public string[] Path
{
  get { return paths; }
  set { paths = value; }
}
private string[] paths;

请注意，此参数属于两个不同的参数集，并且它有一个别名。

两个 System.Management.Automation.Parameterattribute 属性声明 Path 参数属于 ScriptParameterSet 和 PatternParameterSet。有关参数集的详细信息，请参阅将参数集添加到 Cmdlet。

System.Management.Automation.Aliasattribute 属性为 Path 参数声明一个 PSPath 别名。强烈建议声明此别名，以便与访问 Windows PowerShell 提供程序的其他 cmdlet 保持一致。有关 Windows PowerShell 路径的详细信息，请参阅 Windows PowerShell 的工作原理中的“PowerShell 路径概念”。

声明模式参数

为了指定要搜索的模式，此 cmdlet 声明一个 Pattern 参数，它是一个字符串数组。当在数据存储中找到任何模式时，将返回肯定结果。请注意，这些模式可以编译为已编译正则表达式数组或用于文字搜索的通配符模式数组。

[Parameter(
           Position = 1,
           ParameterSetName = "PatternParameterSet",
           Mandatory = true)]
public string[] Pattern
{
  get { return patterns; }
  set { patterns = value; }
}
private string[] patterns;
private Regex[] regexPattern;
private WildcardPattern[] wildcardPattern;

指定此参数后，cmdlet 将使用默认参数集 PatternParameterSet。在这种情况下，cmdlet 使用此处指定的模式来选择字符串。相反，Script 参数也可用于提供包含模式的脚本。 Script 和 Pattern 参数定义了两个单独的参数集，因此它们是互斥的。

声明搜索支持参数

此 cmdlet 定义了以下支持参数，可用于修改 cmdlet 的搜索功能。

Script 参数指定可用于为 cmdlet 提供备用搜索机制的脚本块。该脚本必须包含用于匹配的模式并返回 System.Management.Automation.PSObject 对象。请注意，此参数也是标识 ScriptParameterSet 参数集的唯一参数。当 Windows PowerShell 运行时看到此参数时，它仅使用属于 ScriptParameterSet 参数集的参数。

[Parameter(
           Position = 1,
           ParameterSetName = "ScriptParameterSet",
           Mandatory = true)]
public ScriptBlock Script
{
  set { script = value; }
  get { return script; }
}
ScriptBlock script;

SimpleMatch 参数是一个开关参数，指示 cmdlet 是否显式匹配所提供的模式。当用户在命令行指定参数 (true) 时，cmdlet 将使用所提供的模式。如果未指定参数 (false)，则 cmdlet 使用正则表达式。此参数的默认值为 false。

[Parameter]
public SwitchParameter SimpleMatch
{
  get { return simpleMatch; }
  set { simpleMatch = value; }
}
private bool simpleMatch;

CaseSensitive 参数是一个开关参数，指示是否执行区分大小写的搜索。当用户在命令行指定参数 (true) 时，cmdlet 在比较模式时检查字符的大写和小写。如果未指定参数 (false)，则 cmdlet 不区分大小写。例如，“MyFile”和“myfile”都将作为肯定命中返回。此参数的默认值为 false。

[Parameter]
public SwitchParameter CaseSensitive
{
  get { return caseSensitive; }
  set { caseSensitive = value; }
}
private bool caseSensitive;

Exclude 和 Include 参数标识明确从搜索中排除或包含在搜索中的项目。默认情况下，cmdlet 将搜索数据存储中的所有项目。但是，为了限制 cmdlet 执行的搜索，这些参数可用于显式指示要包含在搜索中或省略的项目。

[Parameter]
public SwitchParameter CaseSensitive
{
  get { return caseSensitive; }
  set { caseSensitive = value; }
}
private bool caseSensitive;

[Parameter]
[ValidateNotNullOrEmpty]
public string[] Include
{
  get
  {
    return includeStrings;
  }
  set
  {
    includeStrings = value;

    this.include = new WildcardPattern[includeStrings.Length];
    for (int i = 0; i < includeStrings.Length; i++)
    {
      this.include[i] = new WildcardPattern(includeStrings[i], WildcardOptions.IgnoreCase);
    }
  }
}

internal string[] includeStrings = null;
internal WildcardPattern[] include = null;

声明参数集

此 cmdlet 使用两个参数集（ScriptParameterSet 和 PatternParameterSet，这是默认值）作为数据访问中使用的两个参数集的名称。 PatternParameterSet 是默认参数集，在指定 Pattern 参数时使用。当用户通过 Script 参数指定备用搜索机制时，将使用 ScriptParameterSet。有关参数集的详细信息，请参阅将参数集添加到 Cmdlet。

重写输入处理方法

Cmdlet 必须重写 System.Management.Automation.PSCmdlet 类的一种或多种输入处理方法。有关输入处理方法的详细信息，请参阅创建您的第一个 Cmdlet。

此 cmdlet 重写 System.Management.Automation.Cmdlet.BeginProcessing 方法以在启动时构建已编译正则表达式的数组。这可以提高不使用简单匹配的搜索期间的性能。

protected override void BeginProcessing()
{
  WriteDebug("Validating patterns.");
  if (patterns != null)
  {
    foreach(string pattern in patterns)
    {
      if (pattern == null)
      ThrowTerminatingError(new ErrorRecord(
                            new ArgumentNullException(
                            "Search pattern cannot be null."),
                            "NullSearchPattern",
                            ErrorCategory.InvalidArgument,
                            pattern)
                            );
    }

    WriteVerbose("Search pattern(s) are valid.");

    // If a simple match is not specified, then
    // compile the regular expressions once.
    if (!simpleMatch)
    {
      WriteDebug("Compiling search regular expressions.");

      RegexOptions regexOptions = RegexOptions.Compiled;
      if (!caseSensitive)
         regexOptions |= RegexOptions.Compiled;
      regexPattern = new Regex[patterns.Length];

      for (int i = 0; i < patterns.Length; i++)
      {
        try
        {
          regexPattern[i] = new Regex(patterns[i], regexOptions);
        }
        catch (ArgumentException ex)
        {
          ThrowTerminatingError(new ErrorRecord(
                        ex,
                        "InvalidRegularExpression",
                        ErrorCategory.InvalidArgument,
                        patterns[i]
                     ));
        }
      } //Loop through patterns to create RegEx objects.

      WriteVerbose("Pattern(s) compiled into regular expressions.");
    }// If not a simple match.

    // If a simple match is specified, then compile the
    // wildcard patterns once.
    else
    {
      WriteDebug("Compiling search wildcards.");

      WildcardOptions wildcardOptions = WildcardOptions.Compiled;

      if (!caseSensitive)
      {
        wildcardOptions |= WildcardOptions.IgnoreCase;
      }

      wildcardPattern = new WildcardPattern[patterns.Length];
      for (int i = 0; i < patterns.Length; i++)
      {
        wildcardPattern[i] =
                     new WildcardPattern(patterns[i], wildcardOptions);
      }

      WriteVerbose("Pattern(s) compiled into wildcard expressions.");
    }// If match is a simple match.
  }// If valid patterns are available.
}// End of function BeginProcessing().

此 cmdlet 还重写 System.Management.Automation.Cmdlet.ProcessRecord 方法来处理用户在命令行上所做的字符串选择。它通过调用私有 MatchString 方法以自定义对象的形式写入字符串选择的结果。

protected override void ProcessRecord()
{
  UInt64 lineNumber = 0;
  MatchInfo result;
  ArrayList nonMatches = new ArrayList();

  // Walk the list of paths and search the contents for
  // any of the specified patterns.
  foreach (string psPath in paths)
  {
    // Once the filepaths are expanded, we may have more than one
    // path, so process all referenced paths.
    foreach(PathInfo path in
            SessionState.Path.GetResolvedPSPathFromPSPath(psPath)
           )
    {
      WriteVerbose("Processing path " + path.Path);

      // Check if the path represents one of the items to be
      // excluded. If so, continue to next path.
      if (!MeetsIncludeExcludeCriteria(path.ProviderPath))
         continue;

      // Get the content reader for the item(s) at the
      // specified path.
      Collection<IContentReader> readerCollection = null;
      try
      {
        readerCollection =
                    this.InvokeProvider.Content.GetReader(path.Path);
      }
      catch (PSNotSupportedException ex)
      {
        WriteError(new ErrorRecord(ex,
                   "ContentAccessNotSupported",
                    ErrorCategory.NotImplemented,
                    path.Path)
                   );
        return;
      }

      foreach(IContentReader reader in readerCollection)
      {
        // Reset the line number for this path.
        lineNumber = 0;

        // Read in a single block (line in case of a file)
        // from the object.
        IList items = reader.Read(1);

        // Read and process one block(line) at a time until
        // no more blocks(lines) exist.
        while (items != null && items.Count == 1)
        {
          // Increment the line number each time a line is
          // processed.
          lineNumber++;

          String message = String.Format("Testing line {0} : {1}",
                                        lineNumber, items[0]);

          WriteDebug(message);

          result = SelectString(items[0]);

          if (result != null)
          {
            result.Path = path.Path;
            result.LineNumber = lineNumber;

            WriteObject(result);
          }
          else
          {
            // Add the block(line) that did not match to the
            // collection of non matches , which will be stored
            // in the SessionState variable $NonMatches
            nonMatches.Add(items[0]);
          }

          // Get the next line from the object.
          items = reader.Read(1);

        }// While loop for reading one line at a time.
      }// Foreach loop for reader collection.
    }// Foreach loop for processing referenced paths.
  }// Foreach loop for walking of path list.

  // Store the list of non-matches in the
  // session state variable $NonMatches.
  try
  {
    this.SessionState.PSVariable.Set("NonMatches", nonMatches);
  }
  catch (SessionStateUnauthorizedAccessException ex)
  {
    WriteError(new ErrorRecord(ex,
               "CannotWriteVariableNonMatches",
               ErrorCategory.InvalidOperation,
               nonMatches)
              );
  }

}// End of protected override void ProcessRecord().

访问内容

您的 cmdlet 必须打开 Windows PowerShell 路径指示的提供程序，以便它可以访问数据。运行空间的 System.Management.Automation.Sessionstate 对象用于访问提供程序，而 cmdlet 的 System.Management.Automation.PSCmdlet.Invokeprovider* 属性用于打开提供程序。通过检索打开的提供程序的 System.Management.Automation.Providerintrinsics 对象来提供对内容的访问。

此示例 Select-Str cmdlet 使用 System.Management.Automation.Providerintrinsics.Content* 属性公开要扫描的内容。然后，它可以调用 System.Management.Automation.Contentcmdletproviderintrinsics.Getreader* 方法，传递所需的 Windows PowerShell 路径。

代码示例

以下代码显示了此版本的 Select-Str cmdlet 的实现。请注意，此代码包括 cmdlet 类、cmdlet 使用的私有方法以及用于注册 cmdlet 的 Windows PowerShell 管理单元代码。有关注册 cmdlet 的详细信息，请参阅构建 Cmdlet。

//
// Copyright (c) 2006 Microsoft Corporation. All rights reserved.
//
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
using System;
using System.Text.RegularExpressions;
using System.Collections;
using System.Collections.ObjectModel;
using System.Management.Automation;
using System.Management.Automation.Provider;
using System.ComponentModel;

namespace Microsoft.Samples.PowerShell.Commands
{
  #region SelectStringCommand
  /// <summary>
  /// This cmdlet searches through PSObjects for particular patterns.
  /// </summary>
  /// <remarks>
  /// This cmdlet can be used to search any object, such as a file or a
  /// variable, whose provider exposes methods for reading and writing
  /// content.
  /// </remarks>
  [Cmdlet(VerbsCommon.Select, "Str", DefaultParameterSetName="PatternParameterSet")]
  public class SelectStringCommand : PSCmdlet
  {
    #region Parameters
    /// <summary>
    /// Declare a Path parameter that specifies where the data is stored.
    /// This parameter must specify a PowerShell that indicates the
    /// PowerShell provider that is used to access the objects to be
    /// searched for matching patterns. This parameter should also have
    /// a PSPath alias to provide consistency with other cmdlets that use
    /// PowerShell providers.
    /// </summary>
    /// <value>Path of the object(s) to search.</value>
    [Parameter(
               Position = 0,
               ParameterSetName = "ScriptParameterSet",
               Mandatory = true)]
    [Parameter(
               Position = 0,
               ParameterSetName = "PatternParameterSet",
               ValueFromPipeline = true,
               Mandatory = true)]
               [Alias("PSPath")]
    public string[] Path
    {
      get { return paths; }
      set { paths = value; }
    }
    private string[] paths;

    /// <summary>
    /// Declare a Pattern parameter that specifies the pattern(s)
    /// used to find matching patterns in the string representation
    /// of the objects. A positive result will be returned
    /// if any of the patterns are found in the objects.
    /// </summary>
    /// <remarks>
    /// The patterns will be compiled into an array of wildcard
    /// patterns for a simple match (literal string matching),
    /// or the patterns will be converted into an array of compiled
    /// regular expressions.
    /// </remarks>
    /// <value>Array of patterns to search.</value>
    [Parameter(
               Position = 1,
               ParameterSetName = "PatternParameterSet",
               Mandatory = true)]
    public string[] Pattern
    {
      get { return patterns; }
      set { patterns = value; }
    }
    private string[] patterns;
    private Regex[] regexPattern;
    private WildcardPattern[] wildcardPattern;

    /// <summary>
    /// Declare a Script parameter that specifies a script block
    /// that is called to perform the matching operations
    /// instead of the matching performed by the cmdlet.
    /// </summary>
    /// <value>Script block that will be called for matching</value>
    [Parameter(
               Position = 1,
               ParameterSetName = "ScriptParameterSet",
               Mandatory = true)]
    public ScriptBlock Script
    {
      set { script = value; }
      get { return script; }
    }
    ScriptBlock script;

    /// <summary>
    /// Declare a switch parameter that specifies if the pattern(s) are used
    /// literally. If not (default), searching is
    /// done using regular expressions.
    /// </summary>
    /// <value>If True, a literal pattern is used.</value>
    [Parameter]
    public SwitchParameter SimpleMatch
    {
      get { return simpleMatch; }
      set { simpleMatch = value; }
    }
    private bool simpleMatch;

    /// <summary>
    /// Declare a switch parameter that specifies if a case-sensitive
    /// search is performed.  If not (default), a case-insensitive search
    /// is performed.
    /// </summary>
    /// <value>If True, a case-sensitive search is made.</value>
    [Parameter]
    public SwitchParameter CaseSensitive
    {
      get { return caseSensitive; }
      set { caseSensitive = value; }
    }
    private bool caseSensitive;

    /// <summary>
    /// Declare an Include parameter that species which
    /// specific items are searched.  When this parameter
    /// is used, items that are not listed here are omitted
    /// from the search.
    /// </summary>
    [Parameter]
    [ValidateNotNullOrEmpty]
    public string[] Include
    {
      get
      {
        return includeStrings;
      }
      set
      {
        includeStrings = value;

        this.include = new WildcardPattern[includeStrings.Length];
        for (int i = 0; i < includeStrings.Length; i++)
        {
          this.include[i] = new WildcardPattern(includeStrings[i], WildcardOptions.IgnoreCase);
        }
      }
    }

    internal string[] includeStrings = null;
    internal WildcardPattern[] include = null;

    /// <summary>
    /// Declare an Exclude parameter that species which
    /// specific items are omitted from the search.
    /// </summary>
    ///
    [Parameter]
    [ValidateNotNullOrEmpty]
    public string[] Exclude
    {
      get
      {
        return excludeStrings;
      }
      set
      {
        excludeStrings = value;

        this.exclude = new WildcardPattern[excludeStrings.Length];
        for (int i = 0; i < excludeStrings.Length; i++)
        {
          this.exclude[i] = new WildcardPattern(excludeStrings[i], WildcardOptions.IgnoreCase);
        }
      }
    }
    internal string[] excludeStrings;
    internal WildcardPattern[] exclude;

    #endregion Parameters

    #region Overrides
    /// <summary>
    /// If regular expressions are used for pattern matching,
    /// then build an array of compiled regular expressions
    /// at startup. This increases performance during scanning
    /// operations when simple matching is not used.
    /// </summary>
    protected override void BeginProcessing()
    {
      WriteDebug("Validating patterns.");
      if (patterns != null)
      {
        foreach(string pattern in patterns)
        {
          if (pattern == null)
          ThrowTerminatingError(new ErrorRecord(
                                new ArgumentNullException(
                                "Search pattern cannot be null."),
                                "NullSearchPattern",
                                ErrorCategory.InvalidArgument,
                                pattern)
                                );
        }

        WriteVerbose("Search pattern(s) are valid.");

        // If a simple match is not specified, then
        // compile the regular expressions once.
        if (!simpleMatch)
        {
          WriteDebug("Compiling search regular expressions.");

          RegexOptions regexOptions = RegexOptions.Compiled;
          if (!caseSensitive)
             regexOptions |= RegexOptions.Compiled;
          regexPattern = new Regex[patterns.Length];

          for (int i = 0; i < patterns.Length; i++)
          {
            try
            {
              regexPattern[i] = new Regex(patterns[i], regexOptions);
            }
            catch (ArgumentException ex)
            {
              ThrowTerminatingError(new ErrorRecord(
                            ex,
                            "InvalidRegularExpression",
                            ErrorCategory.InvalidArgument,
                            patterns[i]
                         ));
            }
          } //Loop through patterns to create RegEx objects.

          WriteVerbose("Pattern(s) compiled into regular expressions.");
        }// If not a simple match.

        // If a simple match is specified, then compile the
        // wildcard patterns once.
        else
        {
          WriteDebug("Compiling search wildcards.");

          WildcardOptions wildcardOptions = WildcardOptions.Compiled;

          if (!caseSensitive)
          {
            wildcardOptions |= WildcardOptions.IgnoreCase;
          }

          wildcardPattern = new WildcardPattern[patterns.Length];
          for (int i = 0; i < patterns.Length; i++)
          {
            wildcardPattern[i] =
                         new WildcardPattern(patterns[i], wildcardOptions);
          }

          WriteVerbose("Pattern(s) compiled into wildcard expressions.");
        }// If match is a simple match.
      }// If valid patterns are available.
    }// End of function BeginProcessing().

    /// <summary>
    /// Process the input and search for the specified patterns.
    /// </summary>
    protected override void ProcessRecord()
    {
      UInt64 lineNumber = 0;
      MatchInfo result;
      ArrayList nonMatches = new ArrayList();

      // Walk the list of paths and search the contents for
      // any of the specified patterns.
      foreach (string psPath in paths)
      {
        // Once the filepaths are expanded, we may have more than one
        // path, so process all referenced paths.
        foreach(PathInfo path in
                SessionState.Path.GetResolvedPSPathFromPSPath(psPath)
               )
        {
          WriteVerbose("Processing path " + path.Path);

          // Check if the path represents one of the items to be
          // excluded. If so, continue to next path.
          if (!MeetsIncludeExcludeCriteria(path.ProviderPath))
             continue;

          // Get the content reader for the item(s) at the
          // specified path.
          Collection<IContentReader> readerCollection = null;
          try
          {
            readerCollection =
                        this.InvokeProvider.Content.GetReader(path.Path);
          }
          catch (PSNotSupportedException ex)
          {
            WriteError(new ErrorRecord(ex,
                       "ContentAccessNotSupported",
                        ErrorCategory.NotImplemented,
                        path.Path)
                       );
            return;
          }

          foreach(IContentReader reader in readerCollection)
          {
            // Reset the line number for this path.
            lineNumber = 0;

            // Read in a single block (line in case of a file)
            // from the object.
            IList items = reader.Read(1);

            // Read and process one block(line) at a time until
            // no more blocks(lines) exist.
            while (items != null && items.Count == 1)
            {
              // Increment the line number each time a line is
              // processed.
              lineNumber++;

              String message = String.Format("Testing line {0} : {1}",
                                            lineNumber, items[0]);

              WriteDebug(message);

              result = SelectString(items[0]);

              if (result != null)
              {
                result.Path = path.Path;
                result.LineNumber = lineNumber;

                WriteObject(result);
              }
              else
              {
                // Add the block(line) that did not match to the
                // collection of non matches , which will be stored
                // in the SessionState variable $NonMatches
                nonMatches.Add(items[0]);
              }

              // Get the next line from the object.
              items = reader.Read(1);

            }// While loop for reading one line at a time.
          }// Foreach loop for reader collection.
        }// Foreach loop for processing referenced paths.
      }// Foreach loop for walking of path list.

      // Store the list of non-matches in the
      // session state variable $NonMatches.
      try
      {
        this.SessionState.PSVariable.Set("NonMatches", nonMatches);
      }
      catch (SessionStateUnauthorizedAccessException ex)
      {
        WriteError(new ErrorRecord(ex,
                   "CannotWriteVariableNonMatches",
                   ErrorCategory.InvalidOperation,
                   nonMatches)
                  );
      }

    }// End of protected override void ProcessRecord().
    #endregion Overrides

    #region PrivateMethods
    /// <summary>
    /// Check for a match using the input string and the pattern(s)
    /// specified.
    /// </summary>
    /// <param name="input">The string to test.</param>
    /// <returns>MatchInfo object containing information about
    /// result of a match</returns>
    private MatchInfo SelectString(object input)
    {
      string line = null;

      try
      {
        // Convert the object to a string type
        // safely using language support methods
        line = (string)LanguagePrimitives.ConvertTo(
                                                    input,
                                                    typeof(string)
                                                    );
        line = line.Trim(' ','\t');
      }
      catch (PSInvalidCastException ex)
      {
        WriteError(new ErrorRecord(
                   ex,
                   "CannotCastObjectToString",
                   ErrorCategory.InvalidOperation,
                   input)
                   );

        return null;
      }

      MatchInfo result = null;

      // If a scriptblock has been specified, call it
      // with the path for processing.  It will return
      // one object.
      if (script != null)
      {
        WriteDebug("Executing script block.");

        Collection<PSObject> psObjects =
                             script.Invoke(
                                           line,
                                           simpleMatch,
                                           caseSensitive
                                          );

        foreach (PSObject psObject in psObjects)
        {
          if (LanguagePrimitives.IsTrue(psObject))
          {
            result = new MatchInfo();
            result.Line = line;
            result.IgnoreCase = !caseSensitive;

            break;
          } //End of If.
        } //End ForEach loop.
      } // End of If if script exists.

      // If script block exists, see if this line matches any
      // of the match patterns.
      else
      {
        int patternIndex = 0;

        while (patternIndex < patterns.Length)
        {
          if ((simpleMatch &&
              wildcardPattern[patternIndex].IsMatch(line))
              || (regexPattern != null
              && regexPattern[patternIndex].IsMatch(line))
             )
          {
            result = new MatchInfo();
            result.IgnoreCase = !caseSensitive;
            result.Line = line;
            result.Pattern = patterns[patternIndex];

            break;
          }

          patternIndex++;

        }// While loop through patterns.
      }// Else for no script block specified.

      return result;

    }// End of SelectString

    /// <summary>
    /// Check whether the supplied name meets the include/exclude criteria.
    /// That is - it's on the include list if the include list was
    /// specified, and not on the exclude list if the exclude list was specified.
    /// </summary>
    /// <param name="path">path to validate</param>
    /// <returns>True if the path is acceptable.</returns>
    private bool MeetsIncludeExcludeCriteria(string path)
    {
      bool ok = false;

      // See if the file is on the include list.
      if (this.include != null)
      {
        foreach (WildcardPattern patternItem in this.include)
        {
          if (patternItem.IsMatch(path))
          {
            ok = true;
            break;
          }
        }
      }
      else
      {
        ok = true;
      }

      if (!ok)
         return false;

      // See if the file is on the exclude list.
      if (this.exclude != null)
      {
        foreach (WildcardPattern patternItem in this.exclude)
        {
          if (patternItem.IsMatch(path))
          {
            ok = false;
            break;
          }
        }
      }

      return ok;
    } //MeetsIncludeExcludeCriteria
    #endregion Private Methods

  }// class SelectStringCommand

  #endregion SelectStringCommand

  #region MatchInfo

  /// <summary>
  /// Class representing the result of a pattern/literal match
  /// that is passed through the pipeline by the Select-Str cmdlet.
  /// </summary>
  public class MatchInfo
  {
    /// <summary>
    /// Indicates if the match was done ignoring case.
    /// </summary>
    /// <value>True if case was ignored.</value>
    public bool IgnoreCase
    {
      get { return ignoreCase; }
      set { ignoreCase = value; }
    }
    private bool ignoreCase;

    /// <summary>
    /// Specifies the number of the matching line.
    /// </summary>
    /// <value>The number of the matching line.</value>
    public UInt64 LineNumber
    {
      get { return lineNumber; }
      set { lineNumber = value; }
    }
    private UInt64 lineNumber;

    /// <summary>
    /// Specifies the text of the matching line.
    /// </summary>
    /// <value>The text of the matching line.</value>
    public string Line
    {
      get { return line; }
      set { line = value; }
    }
    private string line;

    /// <summary>
    /// Specifies the full path of the object(file) containing the
    /// matching line.
    /// </summary>
    /// <remarks>
    /// It will be "inputStream" if the object came from the input
    /// stream.
    /// </remarks>
    /// <value>The path name</value>
    public string Path
    {
      get { return path; }
      set
      {
        pathSet = true;
        path = value;
      }
    }
    private string path;
    private bool pathSet;

    /// <summary>
    /// Specifies the pattern that was used in the match.
    /// </summary>
    /// <value>The pattern string</value>
    public string Pattern
    {
      get { return pattern; }
      set { pattern = value; }
    }
    private string pattern;

    private const string MatchFormat = "{0}:{1}:{2}";

    /// <summary>
    /// Returns the string representation of this object. The format
    /// depends on whether a path has been set for this object or
    /// not.
    /// </summary>
    /// <remarks>
    /// If the path component is set, as would be the case when
    /// matching in a file, ToString() returns the path, line
    /// number and line text.  If path is not set, then just the
    /// line text is presented.
    /// </remarks>
    /// <returns>The string representation of the match object.</returns>
    public override string ToString()
    {
      if (pathSet)
         return String.Format(
         System.Threading.Thread.CurrentThread.CurrentCulture,
         MatchFormat,
         this.path,
         this.lineNumber,
         this.line
         );
      else
         return this.line;
    }
  }// End class MatchInfo

  #endregion

  #region PowerShell snap-in

  /// <summary>
  /// Create a PowerShell snap-in for the Select-Str cmdlet.
  /// </summary>
  [RunInstaller(true)]
  public class SelectStringPSSnapIn : PSSnapIn
  {
    /// <summary>
    /// Create an instance of the SelectStrPSSnapin class.
    /// </summary>
    public SelectStringPSSnapIn()
           : base()
    {
    }

    /// <summary>
    /// Specify the name of the PowerShell snap-in.
    /// </summary>
    public override string Name
    {
      get
      {
        return "SelectStrPSSnapIn";
      }
    }

    /// <summary>
    /// Specify the vendor of the PowerShell snap-in.
    /// </summary>
    public override string Vendor
    {
      get
      {
        return "Microsoft";
      }
    }

    /// <summary>
    /// Specify the localization resource information for the vendor.
    /// Use the format: SnapinName,VendorName.
    /// </summary>
    public override string VendorResource
    {
      get
      {
        return "SelectStrSnapIn,Microsoft";
      }
    }

    /// <summary>
    /// Specify the description of the PowerShell snap-in.
    /// </summary>
    public override string Description
    {
      get
        {
          return "This is a PowerShell snap-in for the Select-Str cmdlet.";
        }
    }

    /// <summary>
    /// Specify the localization resource information for the description.
    /// Use the format: SnapinName,Description.

    /// </summary>
    public override string DescriptionResource
    {
      get
      {
          return "SelectStrSnapIn,This is a PowerShell snap-in for the Select-Str cmdlet.";
      }
    }
  }
  #endregion PowerShell snap-in

} //namespace Microsoft.Samples.PowerShell.Commands;

构建 Cmdlet

实施 cmdlet 后，您必须通过 Windows PowerShell 管理单元将其注册到 Windows PowerShell。有关注册 cmdlet 的详细信息，请参阅如何注册 Cmdlet、提供程序和主机应用程序。

测试 Cmdlet

当您的 cmdlet 已注册到 Windows PowerShell 后，您可以通过在命令行上运行它来测试它。以下过程可用于测试示例 Select-Str cmdlet。

1. 启动 Windows PowerShell，然后在 Notes 文件中搜索包含表达式“.NET”的行。请注意，仅当路径由多个单词组成时，才需要在路径名称两边加上引号。

   select-str -Path "notes" -Pattern ".NET" -SimpleMatch=$false
   

   将出现以下输出。

   IgnoreCase   : True
   LineNumber   : 8
   Line         : Because Windows PowerShell works directly with .NET objects, there is often a .NET object
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes
   Pattern      : .NET
   IgnoreCase   : True
   LineNumber   : 21
   Line         : You should normally define the class for a cmdlet in a .NET namespace
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes
   Pattern      : .NET
   

2. 搜索 Notes 文件中出现的包含单词“over”的行，后跟任何其他文本。 SimpleMatch 参数使用默认值false。搜索不区分大小写，因为 CaseSensitive 参数设置为 false。

   select-str -Path notes -Pattern "over*" -SimpleMatch -CaseSensitive:$false
   

   将出现以下输出。

   IgnoreCase   : True
   LineNumber   : 45
   Line         : Override StopProcessing
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes
   Pattern      : over*
   IgnoreCase   : True
   LineNumber   : 49
   Line         : overriding the StopProcessing method
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes
   Pattern      : over*
   

3. 使用正则表达式作为模式搜索 Notes 文件。该 cmdlet 搜索字母字符和括号内的空格。

   select-str -Path notes -Pattern "\([A-Za-z:blank:]" -SimpleMatch:$false
   

   将出现以下输出。

   IgnoreCase   : True
   LineNumber   : 1
   Line         : Advisory Guidelines (Consider Following)
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes
   Pattern      : \([A-Za-z:blank:]
   IgnoreCase   : True
   LineNumber   : 53
   Line         : If your cmdlet has objects that are not disposed of (written to the pipeline)
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes
   Pattern      : \([A-Za-z:blank:]
   

4. 在 Notes 文件中执行区分大小写的搜索，查找单词“Parameter”的出现情况。

   select-str -Path notes -Pattern Parameter -CaseSensitive
   

   将出现以下输出。

   IgnoreCase   : False
   LineNumber   : 6
   Line         : Support an InputObject Parameter
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes
   Pattern      : Parameter
   IgnoreCase   : False
   LineNumber   : 30
   Line         : Support Force Parameter
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes
   Pattern      : Parameter
   

5. 在 Windows PowerShell 附带的变量提供程序中搜索数值为 0 到 9 的变量。

   select-str -Path * -Pattern "[0-9]"
   

   将出现以下输出。

   IgnoreCase   : True
   LineNumber   : 1
   Line         : 64
   Path         : Variable:\MaximumHistoryCount
   Pattern      : [0-9]
   

6. 使用脚本块在文件 SelectStrCommandSample.cs 中搜索字符串“Pos”。该脚本的 cmatch 函数执行不区分大小写的模式匹配。

   select-str -Path "SelectStrCommandSample.cs" -Script { if ($args[0] -cmatch "Pos"){ return $true } return $false }
   

   将出现以下输出。

   IgnoreCase   : True
   LineNumber   : 37
   Line         :    Position = 0.
   Path         : C:\PowerShell-Progs\workspace\Samples\SelectStr\SelectStrCommandSample.cs
   Pattern      :
   

参见

如何创建 Windows PowerShell Cmdlet

创建您的第一个 Cmdlet

创建修改系统的 Cmdlet

设计您的 Windows PowerShell 提供程序

Windows PowerShell 的工作原理

如何注册 Cmdlet、提供程序和主机应用程序

Windows PowerShell SDK