创建 Windows PowerShell 项提供程序

本主题介绍如何创建可以操作数据存储中的数据的 Windows PowerShell 提供程序。在本主题中，存储中的数据元素称为数据存储的“项”。因此，可以操作存储中的数据的提供程序称为 Windows PowerShell 项目提供程序。

笔记

您可以使用适用于 Windows Vista 和 .NET Framework 3.0 运行时组件的 Microsoft Windows 软件开发工具包下载此提供程序的 C# 源文件 (AccessDBSampleProvider03.cs)。有关下载说明，请参阅如何安装 Windows PowerShell 和下载 Windows PowerShell SDK。下载的源文件位于 PowerShell Samples 目录中。有关其他 Windows PowerShell 提供程序实现的详细信息，请参阅设计 Windows PowerShell 提供程序。

本主题中描述的 Windows PowerShell 项目提供程序从 Access 数据库获取数据项目。在这种情况下，“项目”可以是 Access 数据库中的一个表，也可以是表中的一行。

定义 Windows PowerShell 项提供程序类

Windows PowerShell 项提供程序必须定义派生自 System.Management.Automation.Provider.ItemCmdletProvider 基类的 .NET 类。以下是本节中描述的项目提供程序的类定义。

[CmdletProvider("AccessDB", ProviderCapabilities.None)]

public class AccessDBProvider : ItemCmdletProvider

请注意，在此类定义中，System.Management.Automation.Provider.CmdletProviderAttribute 属性包括两个参数。第一个参数指定 Windows PowerShell 使用的提供程序的用户友好名称。第二个参数指定提供程序在命令处理期间向 Windows PowerShell 运行时公开的 Windows PowerShell 特定功能。对于此提供程序，没有添加 Windows PowerShell 特定功能。

定义基本功能

如设计您的 Windows PowerShell 提供程序中所述，System.Management.Automation.Provider.DriveCmdletProvider 类派生自提供不同提供程序功能的其他几个类。因此，Windows PowerShell 项提供程序必须定义这些类提供的所有功能。

有关如何实现添加特定于会话的初始化信息和释放提供程序使用的资源的功能的详细信息，请参阅创建基本 Windows PowerShell 提供程序。但是，大多数提供程序（包括此处描述的提供程序）可以使用 Windows PowerShell 提供的此功能的默认实现。

在 Windows PowerShell 项提供程序可以操作存储中的项之前，它必须实现 System.Management.Automation.Provider.DriveCmdletProvider 基类的方法以访问数据存储。有关实现此类的详细信息，请参阅创建 Windows PowerShell 驱动器提供程序。

检查路径有效性

查找数据项时，Windows PowerShell 运行时会提供提供程序的 Windows PowerShell 路径，如 Windows PowerShell 工作原理的“PSPath 概念”部分中所定义。 Windows PowerShell 项提供程序必须通过实现 System.Management.Automation.Provider.ItemCmdletProvider.IsValidPath 方法来验证传递给它的任何路径的语法和语义有效性。如果路径有效，则此方法返回 true，否则返回 false。请注意，此方法的实现不应验证路径中项目是否存在，而仅验证路径在语法和语义上是否正确。

以下是此提供程序的 System.Management.Automation.Provider.ItemCmdletProvider.IsValidPath 方法的实现。请注意，此实现调用 NormalizePath 辅助方法将路径中的所有分隔符转换为统一分隔符。

protected override bool IsValidPath(string path)
{
    bool result = true;

    // check if the path is null or empty
    if (String.IsNullOrEmpty(path))
    {
        result = false;
    }

    // convert all separators in the path to a uniform one
    path = NormalizePath(path);

    // split the path into individual chunks
    string[] pathChunks = path.Split(pathSeparator.ToCharArray());

    foreach (string pathChunk in pathChunks)
    {
        if (pathChunk.Length == 0)
        {
            result = false;
        }
    }
    return result;
} // IsValidPath

确定项目是否存在

验证路径后，Windows PowerShell 运行时必须确定该路径中是否存在数据项。为了支持这种类型的查询，Windows PowerShell 项提供程序实现 System.Management.Automation.Provider.ItemCmdletProvider.ItemExists 方法。此方法返回 true 在指定路径找到项目，否则返回 false（默认）。

以下是此提供程序的 System.Management.Automation.Provider.ItemCmdletProvider.ItemExists 方法的实现。请注意，此方法调用 PathIsDrive、ChunkPath 和 GetTable 辅助方法，并使用提供程序定义的 DatabaseTableInfo 对象。

protected override bool ItemExists(string path)
{
    // check if the path represented is a drive
    if (PathIsDrive(path))
    {
        return true;
    }

    // Obtain type, table name and row number from path
    string tableName;
    int rowNumber;

    PathType type = GetNamesFromPath(path, out tableName, out rowNumber);

    DatabaseTableInfo table = GetTable(tableName);

    if (type == PathType.Table)
    {
        // if specified path represents a table then DatabaseTableInfo
        // object for the same should exist
        if (table != null)
        {
            return true;
        }
    }
    else if (type == PathType.Row)
    {
        // if specified path represents a row then DatabaseTableInfo should
        // exist for the table and then specified row number must be within
        // the maximum row count in the table
        if (table != null && rowNumber < table.RowCount)
        {
            return true;
        }
    }

    return false;

} // ItemExists

关于实现 ItemExists 需要记住的事情

以下条件可能适用于 System.Management.Automation.Provider.ItemCmdletProvider.ItemExists 的实现：

• 定义提供程序类时，Windows PowerShell 项提供程序可能会声明 ExpandWildcards、Filter、Include 或 Exclude 提供程序功能code>，来自 System.Management.Automation.Provider.ProviderCapability 枚举。在这些情况下，System.Management.Automation.Provider.ItemCmdletProvider.ItemExists 方法的实现必须确保传递给该方法的路径满足指定功能的要求。为此，该方法应访问适当的属性，例如 System.Management.Automation.Provider.CmdletProvider.Exclude 和 System.Management.Automation.Provider.CmdletProvider.Include 属性。
• 此方法的实现应该处理对项目的任何形式的访问，这可能会使项目对用户可见。例如，如果用户通过 FileSystem 提供程序（由 Windows PowerShell 提供）拥有对文件的写入权限，但没有读取权限，则该文件仍然存在，并且 System.Management.Automation.Provider.ItemCmdletProvider.ItemExists 返回 true。您的实现可能需要检查父项以查看是否可以枚举子项。

将动态参数附加到 Test-Path cmdlet

有时，调用 System.Management.Automation.Provider.ItemCmdletProvider.ItemExists 的 Test-Path cmdlet 需要在运行时动态指定的其他参数。要提供这些动态参数，Windows PowerShell 项提供程序必须实现 System.Management.Automation.Provider.ItemCmdletProvider.ItemExistsDynamicParameters 方法。此方法检索指定路径处项目的动态参数，并返回一个对象，该对象具有与 cmdlet 类或 System.Management.Automation.RuntimeDefinedParameterDictionary 对象类似的解析属性的属性和字段。 Windows PowerShell 运行时使用返回的对象将参数添加到 Test-Path cmdlet。

此 Windows PowerShell 项提供程序不实现此方法。但是，以下代码是此方法的默认实现。

检索项目

要检索项目，Windows PowerShell 项目提供程序必须重写 System.Management.Automation.Provider.ItemCmdletProvider.GetItem 方法以支持来自 Get-Item cmdlet 的调用。此方法使用 System.Management.Automation.Provider.CmdletProvider.WriteItemObject 方法写入项目。

以下是此提供程序的 System.Management.Automation.Provider.ItemCmdletProvider.GetItem 方法的实现。请注意，此方法使用 GetTable 和 GetRow 辅助方法来检索 Access 数据库中的表或数据表中的行项目。

protected override void GetItem(string path)
{
    // check if the path represented is a drive
    if (PathIsDrive(path))
    {
        WriteItemObject(this.PSDriveInfo, path, true);
        return;
    }// if (PathIsDrive...

     // Get table name and row information from the path and do 
     // necessary actions
     string tableName;
     int rowNumber;

     PathType type = GetNamesFromPath(path, out tableName, out rowNumber);

     if (type == PathType.Table)
     {
         DatabaseTableInfo table = GetTable(tableName);
         WriteItemObject(table, path, true);
     }
     else if (type == PathType.Row)
     {
         DatabaseRowInfo row = GetRow(tableName, rowNumber);
         WriteItemObject(row, path, false);
     }
     else
     {
         ThrowTerminatingInvalidPathException(path);
     }

 } // GetItem

关于实现 GetItem 的注意事项

以下条件可能适用于 System.Management.Automation.Provider.ItemCmdletProvider.GetItem 的实现：

• 定义提供程序类时，Windows PowerShell 项提供程序可能会声明 ExpandWildcards、Filter、Include 或 Exclude 提供程序功能code>，来自 System.Management.Automation.Provider.ProviderCapability 枚举。在这些情况下，System.Management.Automation.Provider.ItemCmdletProvider.GetItem 的实现必须确保传递给该方法的路径满足这些要求。为此，该方法应访问适当的属性，例如 System.Management.Automation.Provider.CmdletProvider.Exclude 和 System.Management.Automation.Provider.CmdletProvider.Include 属性。

• 默认情况下，除非 System.Management.Automation.Provider.CmdletProvider.Force 属性设置为 true，否则此方法的重写不应检索通常对用户隐藏的对象。例如，FileSystem 提供程序的 System.Management.Automation.Provider.ItemCmdletProvider.GetItem 方法在尝试调用 System.Management.Automation.Provider.CmdletProvider.WriteItemObject 之前检查 System.Management.Automation.Provider.CmdletProvider.Force 属性用于隐藏或系统文件。

将动态参数附加到 Get-Item cmdlet

有时，Get-Item cmdlet 需要在运行时动态指定的其他参数。要提供这些动态参数，Windows PowerShell 项提供程序必须实现 System.Management.Automation.Provider.ItemCmdletProvider.GetItemDynamicParameters 方法。此方法检索指定路径处项目的动态参数，并返回一个对象，该对象具有与 cmdlet 类或 System.Management.Automation.RuntimeDefinedParameterDictionary 对象类似的解析属性的属性和字段。 Windows PowerShell 运行时使用返回的对象将参数添加到 Get-Item cmdlet。

该提供者未实现此方法。但是，以下代码是此方法的默认实现。

设置项目

要设置项目，Windows PowerShell 项目提供程序必须重写 System.Management.Automation.Provider.ItemCmdletProvider.SetItem 方法以支持来自 Set-Item cmdlet 的调用。此方法设置指定路径中项目的值。

此提供程序不提供 System.Management.Automation.Provider.ItemCmdletProvider.SetItem 方法的重写。但是，以下是此方法的默认实现。

实现 SetItem 时需要记住的事情

以下条件可能适用于 System.Management.Automation.Provider.ItemCmdletProvider.SetItem 的实现：

• 定义提供程序类时，Windows PowerShell 项提供程序可能会声明 ExpandWildcards、Filter、Include 或 Exclude 提供程序功能code>，来自 System.Management.Automation.Provider.ProviderCapability 枚举。在这些情况下，System.Management.Automation.Provider.ItemCmdletProvider.SetItem 的实现必须确保传递给该方法的路径满足这些要求。为此，该方法应访问适当的属性，例如 System.Management.Automation.Provider.CmdletProvider.Exclude 和 System.Management.Automation.Provider.CmdletProvider.Include 属性。

• 默认情况下，除非 System.Management.Automation.Provider.CmdletProvider.Force 属性设置为 true，否则此方法的重写不应设置或写入对用户隐藏的对象。如果路径表示隐藏项并且 System.Management.Automation.Provider.CmdletProvider.Force 设置为 false，则应将错误发送到 System.Management.Automation.Provider.CmdletProvider.WriteError 方法。

• System.Management.Automation.Provider.ItemCmdletProvider.SetItem 方法的实现应调用 System.Management.Automation.Provider.CmdletProvider.ShouldProcess 并在对数据存储进行任何更改之前验证其返回值。该方法用于在数据存储发生更改（例如删除文件）时确认操作的执行。 System.Management.Automation.Provider.CmdletProvider.ShouldProcess 方法将要更改的资源名称发送给用户，Windows PowerShell 运行时会考虑任何命令行设置或首选项变量来确定应显示的内容。

  在调用 System.Management.Automation.Provider.CmdletProvider.ShouldProcess 返回 true 后，System.Management.Automation.Provider.ItemCmdletProvider.SetItem 方法应调用 System.Management.Automation.Provider.CmdletProvider .ShouldContinue 方法。此方法向用户发送一条消息以允许反馈以验证是否应继续操作。对 System.Management.Automation.Provider.CmdletProvider.ShouldContinue 的调用允许对潜在危险的系统修改进行额外检查。

检索 SetItem 的动态参数

有时，Set-Item cmdlet 需要在运行时动态指定的其他参数。要提供这些动态参数，Windows PowerShell 项提供程序必须实现 System.Management.Automation.Provider.ItemCmdletProvider.SetItemDynamicParameters 方法。此方法检索指定路径处项目的动态参数，并返回一个对象，该对象具有类似于 cmdlet 类或 System.Management.Automation.RuntimeDefinedParameterDictionary 对象的解析属性的属性和字段。 Windows PowerShell 运行时使用返回的对象将参数添加到 Set-Item cmdlet。

该提供者未实现此方法。但是，以下代码是此方法的默认实现。

清除一个项目

为了清除项目，Windows PowerShell 项目提供程序实现 System.Management.Automation.Provider.ItemCmdletProvider.ClearItem 方法以支持来自 Clear-Item cmdlet 的调用。该方法删除指定路径的数据项。

该提供者未实现此方法。但是，以下代码是此方法的默认实现。

实施 ClearItem 时需要记住的事项

以下条件可能适用于 System.Management.Automation.Provider.ItemCmdletProvider.ClearItem 的实现：

• 定义提供程序类时，Windows PowerShell 项提供程序可能会声明 ExpandWildcards、Filter、Include 或 Exclude 提供程序功能code>，来自 System.Management.Automation.Provider.ProviderCapability 枚举。在这些情况下，System.Management.Automation.Provider.ItemCmdletProvider.ClearItem 的实现必须确保传递给该方法的路径满足这些要求。为此，该方法应访问适当的属性，例如 System.Management.Automation.Provider.CmdletProvider.Exclude 和 System.Management.Automation.Provider.CmdletProvider.Include 属性。

• 默认情况下，除非 System.Management.Automation.Provider.CmdletProvider.Force 属性设置为 true，否则此方法的重写不应设置或写入对用户隐藏的对象。如果路径表示对用户隐藏的项目并且 System.Management.Automation.Provider.CmdletProvider.Force 设置为 false，则应将错误发送到 System.Management.Automation.Provider.CmdletProvider.WriteError 方法。

• System.Management.Automation.Provider.ItemCmdletProvider.SetItem 方法的实现应调用 System.Management.Automation.Provider.CmdletProvider.ShouldProcess 并在对数据存储进行任何更改之前验证其返回值。该方法用于在数据存储发生更改（例如删除文件）时确认操作的执行。 System.Management.Automation.Provider.CmdletProvider.ShouldProcess 方法将要更改的资源名称发送给用户，使用 Windows PowerShell 运行时并处理任何命令行设置或首选项变量来确定应显示的内容。

  在调用 System.Management.Automation.Provider.CmdletProvider.ShouldProcess 返回 true 后，System.Management.Automation.Provider.ItemCmdletProvider.SetItem 方法应调用 System.Management.Automation.Provider.CmdletProvider .ShouldContinue 方法。此方法向用户发送一条消息以允许反馈以验证是否应继续操作。对 System.Management.Automation.Provider.CmdletProvider.ShouldContinue 的调用允许对潜在危险的系统修改进行额外检查。

检索 ClearItem 的动态参数

有时，Clear-Item cmdlet 需要在运行时动态指定的其他参数。要提供这些动态参数，Windows PowerShell 项提供程序必须实现 System.Management.Automation.Provider.ItemCmdletProvider.ClearItemDynamicParameters 方法。此方法检索指定路径处项目的动态参数，并返回一个对象，该对象具有类似于 cmdlet 类或 System.Management.Automation.RuntimeDefinedParameterDictionary 对象的解析属性的属性和字段。 Windows PowerShell 运行时使用返回的对象将参数添加到 Clear-Item cmdlet。

该项目提供者未实现此方法。但是，以下代码是此方法的默认实现。

执行项目的默认操作

Windows PowerShell 项提供程序可以实现 System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction 方法来支持来自 Invoke-Item cmdlet 的调用，这允许提供程序在以下位置对项执行默认操作：指定的路径。例如，文件系统提供程序可能使用此方法为特定项调用 ShellExecute。

该提供者没有实现该方法。但是，以下代码是此方法的默认实现。

实施 InvokeDefaultAction 需要记住的事项

以下条件可能适用于 System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction 的实现：

• 定义提供程序类时，Windows PowerShell 项提供程序可能会声明 ExpandWildcards、Filter、Include 或 Exclude 提供程序功能code>，来自 System.Management.Automation.Provider.ProviderCapability 枚举。在这些情况下，System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction 的实现必须确保传递给该方法的路径满足这些要求。为此，该方法应访问适当的属性，例如 System.Management.Automation.Provider.CmdletProvider.Exclude 和 System.Management.Automation.Provider.CmdletProvider.Include 属性。

• 默认情况下，除非 System.Management.Automation.Provider.CmdletProvider.Force 属性设置为 true，否则此方法的重写不应设置或写入对用户隐藏的对象。如果路径表示对用户隐藏的项目并且 System.Management.Automation.Provider.CmdletProvider.Force 设置为 false，则应将错误发送到 System.Management.Automation.Provider.CmdletProvider.WriteError 方法。

检索 InvokeDefaultAction 的动态参数

有时，Invoke-Item cmdlet 需要在运行时动态指定的其他参数。要提供这些动态参数，Windows PowerShell 项提供程序必须实现 System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultActionDynamicParameters 方法。此方法检索指定路径处项目的动态参数，并返回一个对象，该对象具有与 cmdlet 类或 System.Management.Automation.RuntimeDefinedParameterDictionary 对象类似的解析属性的属性和字段。 Windows PowerShell 运行时使用返回的对象将动态参数添加到 Invoke-Item cmdlet。

该项目提供者未实现此方法。但是，以下代码是此方法的默认实现。

实现辅助方法和类

此项目提供程序实现了 Windows PowerShell 定义的公共重写方法所使用的多个帮助器方法和类。这些辅助方法和类的代码显示在代码示例部分。

归一化路径方法

此项目提供程序实现 NormalizePath 辅助方法以确保路径具有一致的格式。指定的格式使用反斜杠 (\) 作为分隔符。

PathIsDrive 方法

该项目提供程序实现了一个 PathIsDrive 辅助方法来确定指定的路径是否实际上是驱动器名称。

块路径方法

该项目提供程序实现了一个 ChunkPath 辅助方法，该方法可分解指定的路径，以便提供程序可以识别其各个元素。它返回一个由路径元素组成的数组。

获取表方法

此项目提供程序实现 GetTables 辅助方法，该方法返回一个 DatabaseTableInfo 对象，该对象表示有关调用中指定的表的信息。

获取行方法

此项目提供程序的 System.Management.Automation.Provider.ItemCmdletProvider.GetItem 方法调用 GetRows 帮助器方法。此帮助器方法检索一个 DatabaseRowInfo 对象，该对象表示有关表中指定行的信息。

数据库表信息类

该项目提供程序定义了一个 DatabaseTableInfo 类，该类表示数据库中数据表中的信息集合。此类类似于 System.IO.Directoryinfo 类。

示例项提供程序定义了一个 DatabaseTableInfo.GetTables 方法，该方法返回定义数据库中的表的表信息对象的集合。此方法包括一个 try/catch 块，以确保任何数据库错误都显示为具有零条目的行。

数据库行信息类

该项目提供程序定义了 DatabaseRowInfo 帮助程序类，该类表示数据库表中的一行。此类类似于 System.IO.FileInfo 类。

示例提供程序定义了一个DatabaseRowInfo.GetRows 方法来返回指定表的行信息对象的集合。此方法包含一个 try/catch 块来捕获异常。任何错误都将导致没有行信息。

代码示例

有关完整的示例代码，请参阅 AccessDbProviderSample03 代码示例。

定义对象类型和格式

编写提供程序时，可能需要向现有对象添加成员或定义新对象。完成后，创建 Windows PowerShell 可用于标识对象成员的类型文件和定义对象显示方式的格式文件。有关详细信息，请参阅扩展对象类型和格式。

构建 Windows PowerShell 提供程序

请参阅如何注册 Cmdlet、提供程序和主机应用程序。

测试 Windows PowerShell 提供程序

当此 Windows PowerShell 项提供程序注册到 Windows PowerShell 时，您只能测试该提供程序的基本功能和驱动功能。要测试项目的操作，您还必须实现实现容器 Windows PowerShell 提供程序中描述的容器功能。

参见

• Windows PowerShell SDK
• Windows PowerShell 程序员指南
• 创建 Windows PowerShell 提供程序
• 设计您的 Windows PowerShell 提供程序
• 扩展对象类型和格式
• Windows PowerShell 的工作原理
• 创建容器 Windows PowerShell 提供程序
• 创建 Drive Windows PowerShell 提供程序
• 如何注册 Cmdlet、提供程序和主机应用程序