Tworzenie dostawcy nawigacji programu Windows PowerShell

Artykuł
09/25/2021

W tym temacie opisano sposób tworzenia dostawcy Windows PowerShell nawigacyjnego, który może nawigować po magazynie danych. Ten typ dostawcy obsługuje polecenia cykliczne, zagnieżdżone kontenery i ścieżki względne.

Uwaga

Możesz pobrać plik źródłowy języka C# (AccessDBSampleProvider05.cs) dla tego dostawcy przy użyciu zestawu Microsoft Windows Software Development Kit dla systemu Windows Vista i składników środowiska uruchomieniowego programu .NET Framework 3.0. Aby uzyskać instrukcje dotyczące pobierania, zobacz How to Install Windows PowerShell and Download the Windows PowerShell SDK (Jak zainstalować zestaw SDK Windows PowerShell). Pobrane pliki źródłowe są dostępne w <PowerShell Samples> katalogu . Aby uzyskać więcej informacji na temat Windows PowerShell implementacji innych dostawców, zobacz Designing Your Windows PowerShell Provider.

Dostawca opisany w tym miejscu umożliwia użytkownikowi obsługę bazy danych programu Access jako dysku, dzięki czemu użytkownik może przejść do tabel danych w bazie danych. Podczas tworzenia własnego dostawcy nawigacji można zaimplementować metody, które mogą tworzyć ścieżki kwalifikowane pod względem dysku wymagane do nawigacji, normalizować ścieżki względne, przenosić elementy magazynu danych, a także metody, które uzyskają nazwy podrzędne, uzyskają ścieżkę nadrzędną elementu i przetestują, aby sprawdzić, czy element jest kontenerem.

Przestroga

Należy pamiętać, że w tym projekcie przyjęto założenie, że baza danych ma pole o identyfikatorze nazwy, a typ pola to LongInteger.

Definiowanie Windows PowerShell dostawcy

Dostawca Windows PowerShell nawigacyjny musi utworzyć klasę .NET pochodzącą od klasy bazowej System.Management.Automation.Provider.Navigationcmdletprovider. Oto definicja klasy dostawcy nawigacji opisana w tej sekcji.

[CmdletProvider("AccessDB", ProviderCapabilities.None)]
public class AccessDBProvider : NavigationCmdletProvider

Należy pamiętać, że w tym dostawcy atrybut System.Management.Automation.Provider.Cmdletproviderattribute zawiera dwa parametry. Pierwszy parametr określa przyjazną dla użytkownika nazwę dostawcy, która jest używana przez Windows PowerShell. Drugi parametr określa konkretne Windows PowerShell, które dostawca uwidacznia w środowisku uruchomieniowym Windows PowerShell podczas przetwarzania poleceń. W przypadku tego dostawcy nie ma żadnych Windows PowerShell określonych możliwości, które zostały dodane.

Definiowanie podstawowych funkcji

Zgodnie z opisem w tece Design Your PS Provider (Projektowanie dostawcy programu PS)klasa bazowa System.Management.Automation.Provider.Navigationcmdletprovider pochodzi z kilku innych klas, które zapewniały różne funkcje dostawcy. Dlatego Windows PowerShell nawigacyjny musi definiować wszystkie funkcje zapewniane przez te klasy.

Aby zaimplementować funkcje dodawania informacji inicjowania specyficznych dla sesji i zwalniania zasobów używanych przez dostawcę, zobacz Tworzenie podstawowego dostawcy programu PS. Jednak większość dostawców (w tym dostawca opisany tutaj) może używać domyślnej implementacji tej funkcji udostępnianej przez Windows PowerShell.

Aby uzyskać dostęp do magazynu danych za pośrednictwem dysku Windows PowerShell, należy zaimplementować metody klasy bazowej System.Management.Automation.Provider.Drivecmdletprovider. Aby uzyskać więcej informacji na temat implementowania tych metod, zobacz Creating a Windows PowerShell Drive Provider.

Aby manipulować elementami magazynu danych, takimi jak pobieranie, ustawianie i czyszczenie elementów, dostawca musi zaimplementować metody dostarczane przez klasę bazową System.Management.Automation.Provider.Itemcmdletprovider. Aby uzyskać więcej informacji na temat implementowania tych metod, zobacz Creating an Windows PowerShell Item Provider (Tworzenie dostawcy Windows PowerShell elementów).

Aby uzyskać dostęp do elementów podrzędnych lub ich nazw magazynu danych, a także metod tworzenia, kopiowania, zmieniania nazw i usuwania elementów, należy zaimplementować metody dostarczane przez klasę bazową System.Management.Automation.Provider.Containercmdletprovider. Aby uzyskać więcej informacji na temat implementowania tych metod, zobacz Creating a Windows PowerShell Container Provider (Tworzenie Windows PowerShell kontenera).

Tworzenie Windows PowerShell danych

Windows PowerShell nawigacji używają wewnętrznej ścieżki Windows PowerShell dostawcy do nawigowania po elementach magazynu danych. Aby utworzyć ścieżkę wewnętrzną dostawcy, dostawca musi zaimplementować metodę System.Management.Automation.Provider.Navigationcmdletprovider.Makepath*, która obsługuje wywołania z Combine-Path cmdlet. Ta metoda łączy ścieżkę nadrzędną i podrzędną w ścieżkę wewnętrzną dostawcy przy użyciu separatora ścieżki specyficznego dla dostawcy między ścieżkami nadrzędnymi i podrzędnym.

Domyślna implementacja przyjmuje ścieżki ze znakiem "/" lub " " jako separatorem ścieżki, normalizuje separator ścieżki do " ", łączy części ścieżki nadrzędnej i podrzędnej z separatorem między nimi, a następnie zwraca ciąg zawierający połączone \ \ ścieżki.

Ten dostawca nawigacji nie implementuje tej metody. Jednak poniższy kod jest domyślną implementacją metody System.Management.Automation.Provider.Navigationcmdletprovider.Makepath*.

Co należy zapamiętać na temat implementowania makepath

Następujące warunki mogą dotyczyć implementacji właściwości System.Management.Automation.Provider.Navigationcmdletprovider.Makepath*:

Implementacja metody System.Management.Automation.Provider.Navigationcmdletprovider.Makepath* nie powinna weryfikować ścieżki jako w pełni kwalifikowanej ścieżki prawnej w przestrzeni nazw dostawcy. Należy pamiętać, że każdy parametr może reprezentować tylko część ścieżki, a połączone części mogą nie generować w pełni kwalifikowanej ścieżki. Na przykład metoda System.Management.Automation.Provider.Navigationcmdletprovider.Makepath* dostawcy systemu plików może otrzymać wartość "windows\system32" w parametrze parent i wartość "abc.dll" w child parametrze. Metoda łączy te wartości z separatorem "" i zwraca wartość "windows\system32\abc.dll", która nie jest w pełni \ kwalifikowaną ścieżką systemu plików.

Ważne

Części ścieżki podane w wywołaniu elementu System.Management.Automation.Provider.Navigationcmdletprovider.Makepath* mogą zawierać znaki niedozwolone w przestrzeni nazw dostawcy. Te znaki są najprawdopodobniej używane do rozszerzania z symbolami wieloznacznych i implementacja tej metody nie powinna ich usuwać.

Pobieranie ścieżki nadrzędnej

Windows PowerShell nawigacji implementują metodę System.Management.Automation.Provider.Navigationcmdletprovider.Getparentpath*, aby pobrać część nadrzędną wskazanej pełnej lub częściowej ścieżki specyficznej dla dostawcy. Metoda usuwa podrzędną część ścieżki i zwraca część ścieżki nadrzędnej. Parametr root określa w pełni kwalifikowaną ścieżkę do katalogu głównego dysku. Ten parametr może mieć wartość null lub pusty, jeśli zainstalowany dysk nie jest w użyciu do operacji pobierania. Jeśli określono katalog główny, metoda musi zwrócić ścieżkę do kontenera w tym samym drzewie co katalog główny.

Przykładowy dostawca nawigacji nie zastępuje tej metody, ale używa implementacji domyślnej. Akceptuje ścieżki, które używają zarówno "/", jak i " \ " jako separatorów ścieżek. Najpierw normalizuje ścieżkę tak, aby zawierała tylko separatory " ", a następnie dzieli ścieżkę nadrzędną od ostatniej "" i \ \ zwraca ścieżkę nadrzędną.

Aby pamiętać o implementacji getParentPath

Implementacja metody System.Management.Automation.Provider.Navigationcmdletprovider.Getparentpath* powinna podzielić ścieżkę leksykalnie na separatorze ścieżki dla przestrzeni nazw dostawcy. Na przykład dostawca systemu plików używa tej metody do wyszukiwania ostatniego "" i zwraca wszystko \ po lewej stronie separatora.

Pobieranie nazwy ścieżki podrzędnej

Dostawca nawigacji implementuje metodę System.Management.Automation.Provider.Navigationcmdletprovider.Getchildname*, aby pobrać nazwę (element liścia) elementu podrzędnego elementu znajdującego się we wskazanej pełnej lub częściowej ścieżce specyficznej dla dostawcy.

Przykładowy dostawca nawigacji nie zastępuje tej metody. Poniżej przedstawiono implementację domyślną. Akceptuje ścieżki, które używają zarówno "/", jak i " \ " jako separatorów ścieżek. Najpierw normalizuje ścieżkę tak, aby zawierała tylko separatory " ", a następnie dzieli ścieżkę nadrzędną od ostatniego " " i zwraca nazwę części \ \ ścieżki podrzędnej.

Co należy zapamiętać w przypadku implementowania getChildName

Implementacja metody System.Management.Automation.Provider.Navigationcmdletprovider.Getchildname* powinna podzielić ścieżkę leksykalnie na separatorze ścieżki. Jeśli dostarczona ścieżka nie zawiera separatorów ścieżek, metoda powinna zwrócić ścieżkę w niezmienionej.

Ważne

Ścieżka w wywołaniu tej metody może zawierać znaki, które są niedozwolone w przestrzeni nazw dostawcy. Te znaki są najprawdopodobniej używane do rozszerzania symboli wieloznacznych lub dopasowywania wyrażeń regularnych, a implementacja tej metody nie powinna ich usuwać.

Określanie, czy element jest kontenerem

Dostawca nawigacji może zaimplementować metodę System.Management.Automation.Provider.Navigationcmdletprovider.Isitemcontainer*, aby określić, czy określona ścieżka wskazuje kontener. Zwraca wartość true, jeśli ścieżka reprezentuje kontener, a w przeciwnym razie wartość false. Użytkownik potrzebuje tej metody, aby móc użyć Test-Path polecenia cmdlet dla podanej ścieżki.

Poniższy kod przedstawia implementację System.Management.Automation.Provider.Navigationcmdletprovider.Isitemcontainer* w naszym przykładowym dostawcy nawigacji. Metoda sprawdza, czy określona ścieżka jest prawidłowa i czy tabela istnieje, i zwraca wartość true, jeśli ścieżka wskazuje kontener.

protected override bool IsItemContainer(string path)
{
   if (PathIsDrive(path)) 
   { 
       return true; 
   }
   
   string[] pathChunks = ChunkPath(path);
   string tableName;
   int rowNumber;

   PathType type = GetNamesFromPath(path, out tableName, out rowNumber);
   
   if (type == PathType.Table)
   {
      foreach (DatabaseTableInfo ti in GetTables())
      {
          if (string.Equals(ti.Name, tableName, StringComparison.OrdinalIgnoreCase))
          {
              return true;
          }
      } // foreach (DatabaseTableInfo...
   } // if (pathChunks...

   return false;
} // IsItemContainer

Co należy zapamiętać w przypadku implementowania isItemContainer

Klasa .NET dostawcy nawigacji może deklarować możliwości dostawcy ExpandWildcards, Filter, Include lub Exclude z wyliczenia System.Management.Automation.Provider.Providercapabilities. W tym przypadku implementacja interfejsu System.Management.Automation.Provider.Navigationcmdletprovider.Isitemcontainer* musi zapewnić, że przekazana ścieżka spełnia wymagania. W tym celu metoda powinna uzyskać dostęp do odpowiedniej właściwości, na przykład właściwości System.Management.Automation.Provider.Cmdletprovider.Exclude*.

Przenoszenie elementu

W celu obsługi polecenia cmdlet dostawca nawigacji implementuje metodę Move-Item System.Management.Automation.Provider.Navigationcmdletprovider.Moveitem*. Ta metoda przenosi element określony przez path parametr do kontenera w ścieżce podanej w destination parametrze .

Przykładowy dostawca nawigacji nie zastępuje metody System.Management.Automation.Provider.Navigationcmdletprovider.Moveitem*. Poniżej przedstawiono implementację domyślną.

Co należy zapamiętać w przypadku implementowania moveItem

Klasa .NET dostawcy nawigacji może deklarować możliwości dostawcy ExpandWildcards, Filter, Include lub Exclude z wyliczenia System.Management.Automation.Provider.Providercapabilities. W takim przypadku implementacja rozwiązania System.Management.Automation.Provider.Navigationcmdletprovider.Moveitem* musi zapewnić, że przekazana ścieżka spełnia wymagania. W tym celu metoda powinna uzyskać dostęp do odpowiedniej właściwości, na przykład właściwości CmdletProvider.Exclude.

Domyślnie przesłonięcia tej metody nie powinny przenosić obiektów na istniejące obiekty, chyba że właściwość System.Management.Automation.Provider.Cmdletprovider.Force* jest ustawiona na true wartość . Na przykład dostawca systemu plików nie skopiuje pliku c:\temp\abc.txt istniejącego pliku c:\bar.txt, chyba że właściwość System.Management.Automation.Provider.Cmdletprovider.Force* jest ustawiona na true wartość . Jeśli ścieżka określona w parametrze istnieje i jest kontenerem, właściwość destination System.Management.Automation.Provider.Cmdletprovider.Force* nie jest wymagana. W takim przypadku system.Management.Automation.Provider.Navigationcmdletprovider.Moveitem* powinien przenieść element wskazany przez parametr do kontenera wskazanego przez parametr jako path element destination podrzędny.

Implementacja metody System.Management.Automation.Provider.Navigationcmdletprovider.Moveitem* powinna wywołać metodę System.Management.Automation.Provider.Cmdletprovider.ShouldProcess i sprawdzić jej wartość zwracaną przed wprowadzeniem jakichkolwiek zmian w magazynie danych. Ta metoda służy do potwierdzania wykonania operacji w przypadku zmiany stanu systemu, na przykład usunięcia plików. System.Management.Automation.Provider.Cmdletprovider.ShouldProcess wysyła nazwę zasobu, który ma zostać zmieniony, do użytkownika, przy czym środowisko uruchomieniowe programu Windows PowerShell uwzględnia wszystkie ustawienia wiersza polecenia lub zmienne preferencji podczas określania tego, co powinno być wyświetlane użytkownikowi.

Po wywołaniu metody System.Management.Automation.Provider.Cmdletprovider.ShouldProcess zwraca wartość , metoda true System.Management.Automation.Provider.Navigationcmdletprovider.Moveitem* powinna wywołać metodę System.Management.Automation.Provider.Cmdletprovider.ShouldContinue. Ta metoda wysyła do użytkownika komunikat z opinią o tym, czy operacja powinna być kontynuowana. Twój dostawca powinien wywołać element System.Management.Automation.Provider.Cmdletprovider.ShouldContinue jako dodatkowe sprawdzenie potencjalnie niebezpiecznych modyfikacji systemu.

Dołączanie parametrów dynamicznych do Move-Item cmdlet

Czasami polecenie Move-Item cmdlet wymaga dodatkowych parametrów, które są udostępniane dynamicznie w czasie wykonywania. Aby podać te parametry dynamiczne, dostawca nawigacji musi zaimplementować metodę System.Management.Automation.Provider.Navigationcmdletprovider.Moveitemdynamicparameters*, aby uzyskać wymagane wartości parametrów z elementu we wskazanej ścieżce i zwrócić obiekt, który ma właściwości i pola z atrybutami analizy podobnymi do klasy polecenia cmdlet lub obiektu System.Management.Automation.Runtimedefinedparameterdictionary.

Ten dostawca nawigacji nie implementuje tej metody. Jednak poniższy kod jest domyślną implementacją system.Management.Automation.Provider.Navigationcmdletprovider.Moveitemdynamicparameters*.

Normalizowanie ścieżki względnej

Dostawca nawigacji implementuje metodę System.Management.Automation.Provider.Navigationcmdletprovider.Normalizerelativepath*, aby znormalizować w pełni kwalifikowaną ścieżkę wskazaną w parametrze jako względną do ścieżki określonej przez path basePath parametr. Metoda zwraca reprezentację ciągu znormalizowanej ścieżki. Zapisuje błąd, jeśli path parametr określa nieistniejącej ścieżki.

Przykładowy dostawca nawigacji nie zastępuje tej metody. Poniżej przedstawiono implementację domyślną.

Co należy zapamiętać na temat implementowania normalizeRelativePath

Implementacja funkcji System.Management.Automation.Provider.Navigationcmdletprovider.Normalizerelativepath* powinna analizujeć parametr, ale nie musi używać wyłącznie path składniowej analizy. Zachęcamy do zaprojektowania tej metody, aby użyć ścieżki do wyszukiwania informacji o ścieżce w magazynie danych i utworzenia ścieżki, która będzie odpowiadać składni ścieżki wielkości i standardowej.

Przykład kodu

Aby uzyskać kompletny przykładowy kod, zobacz AccessDbProviderSample05 Code Sample (Przykładowy kod AccessDbProviderSample05).

Definiowanie typów obiektów i formatowania

Dostawca może dodawać elementy członkowskie do istniejących obiektów lub definiować nowe obiekty. Aby uzyskać więcej informacji, zobaczRozszerzanie typów obiektów i formatowanie.

Tworzenie dostawcy Windows PowerShell aplikacji

Aby uzyskać więcej informacji, zobacz How to Register Cmdlets, Providers, and Host Applications(Jak rejestrować polecenia cmdlet, dostawcy i aplikacje hosta).

Testowanie dostawcy Windows PowerShell usługi

Po zarejestrowaniu Windows PowerShell usługi Windows PowerShell można go przetestować, uruchamiając obsługiwane polecenia cmdlet w wierszu polecenia, w tym polecenia cmdlet udostępniane przez wyprowadzanie. W tym przykładzie zostanie przetestowany przykładowy dostawca nawigacji.

Uruchom nową powłokę i użyj Set-Location polecenia cmdlet , aby ustawić ścieżkę do wskazywania bazy danych programu Access.
```
Set-Location mydb:
```

Teraz uruchom polecenie cmdlet , aby pobrać listę elementów bazy Get-Childitem danych, które są dostępnymi tabelami bazy danych. Dla każdej tabeli to polecenie cmdlet pobiera również liczbę wierszy tabeli.

Get-ChildItem | Format-Table rowcount,name -AutoSize

RowCount   Name
--------   ----
     180   MSysAccessObjects
       0   MSysACEs
       1   MSysCmdbars
       0   MSysIMEXColumns
       0   MSysIMEXSpecs
       0   MSysObjects
       0   MSysQueries
       7   MSysRelationships
       8   Categories
      91   Customers
       9   Employees
    2155   Order Details
     830   Orders
      77   Products
       3   Shippers
      29   Suppliers

Użyj ponownie Set-Location polecenia cmdlet , aby ustawić lokalizację tabeli danych Employees.
```
Set-Location Employees
```
Użyjmy teraz polecenia Get-Location cmdlet , aby pobrać ścieżkę do tabeli Employees.
```
Get-Location
```
```
Path
----
mydb:\Employees
```

Teraz użyj Get-Childitem polecenia cmdlet potokowego do Format-Table polecenia cmdlet . Ten zestaw polecenia cmdlet pobiera elementy tabeli danych Employees, które są wierszami tabeli. Są one sformatowane w sposób określony przez Format-Table polecenie cmdlet .

Get-ChildItem | Format-Table rownumber,psiscontainer,data -AutoSize

RowNumber   PSIsContainer   Data
---------   --------------   ----
0           False            System.Data.DataRow
1           False            System.Data.DataRow
2           False            System.Data.DataRow
3           False            System.Data.DataRow
4           False            System.Data.DataRow
5           False            System.Data.DataRow
6           False            System.Data.DataRow
7           False            System.Data.DataRow
8           False            System.Data.DataRow

Teraz możesz uruchomić polecenie cmdlet , aby pobrać elementy z wiersza Get-Item 0 tabeli danych Employees.

Get-Item 0

PSPath        : AccessDB::C:\PS\Northwind.mdb\Employees\0
PSParentPath  : AccessDB::C:\PS\Northwind.mdb\Employees
PSChildName   : 0
PSDrive       : mydb
PSProvider    : System.Management.Automation.ProviderInfo
PSIsContainer : False
Data           : System.Data.DataRow
RowNumber      : 0

Użyj ponownie Get-Item polecenia cmdlet , aby pobrać dane pracowników dla elementów w wierszu 0.

(Get-Item 0).data

EmployeeID      : 1
LastName        : Davis
FirstName       : Sara
Title           : Sales Representative
TitleOfCourtesy : Ms.
BirthDate       : 12/8/1968 12:00:00 AM
HireDate        : 5/1/1992 12:00:00 AM
Address         : 4567 Main Street
                  Apt. 2A
City            : Buffalo
Region          : NY
PostalCode      : 98052
Country         : USA
HomePhone       : (206) 555-9857
Extension       : 5467
Photo           : EmpID1.bmp
Notes           : Education includes a BA in psychology from
                  Colorado State University. She also completed "The
                  Art of the Cold Call."  Nancy is a member of
                  Toastmasters International.
ReportsTo       : 2