about_Types.ps1xml

Artykuł
04/13/2023

Krótki opis

Wyjaśnia, jak używać Types.ps1xml plików do rozszerzania typów obiektów używanych w programie PowerShell.

Długi opis

Rozszerzone dane typu definiują dodatkowe właściwości i metody ("elementy członkowskie") typów obiektów w programie PowerShell. Istnieją dwie techniki dodawania danych typu rozszerzonego do sesji programu PowerShell.

Types.ps1xml plik: plik XML, który definiuje dane typu rozszerzonego.
Update-TypeData: polecenie cmdlet, które ponownie ładuje Types.ps1xml pliki i definiuje rozszerzone dane dla typów w bieżącej sesji.

W tym temacie opisano Types.ps1xml pliki. Aby uzyskać więcej informacji na temat używania Update-TypeData polecenia cmdlet do dodawania dynamicznych danych typu rozszerzonego do bieżącej sesji, zobacz Update-TypeData.

Informacje o danych typu rozszerzonego

Rozszerzone dane typu definiują dodatkowe właściwości i metody ("elementy członkowskie") typów obiektów w programie PowerShell. Można rozszerzyć dowolny typ obsługiwany przez program PowerShell i użyć dodanych właściwości i metod w taki sam sposób, jak właściwości zdefiniowane w typach obiektów.

Na przykład program PowerShell dodaje właściwość DateTime do wszystkich System.DateTime obiektów, takich jak zwracane przez Get-Date polecenie cmdlet.

(Get-Date).DateTime

Sunday, January 29, 2012 9:43:57 AM

Nie znajdziesz właściwości DateTime w opisie struktury System.DateTime , ponieważ program PowerShell dodaje właściwość i jest widoczny tylko w programie PowerShell.

Program PowerShell wewnętrznie definiuje domyślny zestaw typów rozszerzonych. Te informacje o typie są ładowane w każdej sesji programu PowerShell podczas uruchamiania. Właściwość DateTime jest częścią tego zestawu domyślnego. Przed programem PowerShell 6 definicje typów były przechowywane Types.ps1xml w katalogu instalacyjnym programu PowerShell ($PSHOME).

Dodawanie danych typu rozszerzonego do programu PowerShell

W sesjach programu PowerShell istnieją trzy źródła danych typu rozszerzonego.

Rozszerzone dane typu są definiowane przez program PowerShell i ładowane automatycznie do każdej sesji programu PowerShell. Począwszy od programu PowerShell 6, te informacje są kompilowane w programie PowerShell i nie są już dostarczane w Types.ps1xml pliku.
Pliki Types.ps1xml eksportowane przez moduły są ładowane po zaimportowaniu modułu do bieżącej sesji.
Rozszerzone dane typu zdefiniowane przy użyciu Update-TypeData polecenia cmdlet są dodawane tylko do bieżącej sesji. Nie jest on zapisywany w pliku.

W sesji dane typu rozszerzonego z trzech źródeł są stosowane do obiektów w taki sam sposób i są dostępne we wszystkich obiektach określonych typów.

Polecenia cmdlet TypeData

Następujące polecenia cmdlet znajdują się w module Microsoft.PowerShell.Utility w programie PowerShell 3.0 lub nowszym.

Get-TypeData: pobiera dane typu rozszerzonego w bieżącej sesji.
Update-TypeData: Ponownie ładuje Types.ps1xml pliki. Dodaje dane typu rozszerzonego do bieżącej sesji.
Remove-TypeData: usuwa dane typu rozszerzonego z bieżącej sesji.

Aby uzyskać więcej informacji na temat tych poleceń cmdlet, zobacz temat pomocy dla każdego polecenia cmdlet.

Wbudowane pliki Types.ps1xml

Pliki Types.ps1xml w $PSHOME katalogu są dodawane automatycznie do każdej sesji.

Types.ps1xml Plik w katalogu instalacyjnym programu PowerShell ($PSHOME) to plik tekstowy oparty na formacie XML, który umożliwia dodawanie właściwości i metod do obiektów używanych w programie PowerShell. Program PowerShell ma wbudowane Types.ps1xml pliki, które dodają kilka elementów do typów platformy .NET, ale można utworzyć dodatkowe Types.ps1xml pliki w celu dalszego rozszerzania typów.

Na przykład domyślnie obiekty tablicowe (System.Array) mają właściwość Length , która wyświetla liczbę obiektów w tablicy. Jednak ponieważ nazwa Length nie opisuje wyraźnie właściwości, program PowerShell dodaje właściwość aliasu o nazwie Count , która wyświetla tę samą wartość. Poniższy kod XML dodaje właściwość Count do System.Array typu.

<Type>
  <Name>System.Array</Name>
  <Members>
    <AliasProperty>
      <Name>Count</Name>
      <ReferencedMemberName>
        Length
      </ReferencedMemberName>
    </AliasProperty>
  </Members>
</Type>

Aby uzyskać nowy aliasProperty, użyj Get-Member polecenia w dowolnej tablicy, jak pokazano w poniższym przykładzie.

Get-Member -InputObject (1,2,3,4)

Polecenie zwraca następujące wyniki.

Name       MemberType    Definition
----       ----------    ----------
Count      AliasProperty Count = Length
Address    Method        System.Object& Address(Int32)
Clone      Method        System.Object Clone()
CopyTo     Method        System.Void CopyTo(Array array, Int32 index):
Equals     Method        System.Boolean Equals(Object obj)
Get        Method        System.Object Get(Int32)
# ...

W związku z tym można użyć właściwości Count lub właściwości Length tablic w programie PowerShell. Na przykład:

(1, 2, 3, 4).count
4

(1, 2, 3, 4).length
4

Tworzenie nowych plików Types.ps1xml

Pliki .ps1xml zainstalowane za pomocą programu PowerShell są podpisane cyfrowo, aby zapobiec manipulacji, ponieważ formatowanie może zawierać bloki skryptów. W związku z tym, aby dodać właściwość lub metodę do typu platformy .NET, utwórz własne Types.ps1xml pliki, a następnie dodaj je do sesji programu PowerShell.

Aby utworzyć nowy plik, zacznij od skopiowania istniejącego Types.ps1xml pliku. Nowy plik może mieć dowolną .ps1xml nazwę, ale musi mieć rozszerzenie nazwy pliku. Nowy plik można umieścić w dowolnym katalogu dostępnym dla programu PowerShell, ale warto umieścić pliki w katalogu instalacyjnym programu PowerShell ($PSHOME) lub w podkatalogu katalogu instalacyjnego.

Po zapisaniu nowego pliku użyj Update-TypeData polecenia cmdlet , aby dodać nowy plik do sesji programu PowerShell. Jeśli chcesz, aby typy miały pierwszeństwo przed zdefiniowanymi typami wbudowanymi, użyj parametru Update-TypeData PrependData polecenia cmdlet. Update-TypeData dotyczy tylko bieżącej sesji. Aby wprowadzić zmiany we wszystkich przyszłych sesjach, wyeksportuj konsolę lub dodaj Update-TypeData polecenie do profilu programu PowerShell.

Types.ps1xml i Add-Member

Pliki Types.ps1xml dodają właściwości i metody do wszystkich wystąpień obiektów określonego typu .NET w sesji programu PowerShell, której dotyczy problem. Jeśli jednak musisz dodać właściwości lub metody tylko do jednego wystąpienia obiektu, użyj Add-Member polecenia cmdlet .

Aby uzyskać więcej informacji, zobacz Dodawanie elementu członkowskiego.

Przykład: dodawanie elementu członkowskiego age do obiektów FileInfo

W tym przykładzie pokazano, jak dodać właściwość Age do obiektów System.IO.FileInfo . Wiek pliku to różnica między czasem tworzenia a bieżącą godziną w dniach.

Ponieważ właściwość Age jest obliczana przy użyciu bloku skryptu, znajdź tag, który <ScriptProperty> ma być używany jako model dla nowej właściwości Age.

Zapisz poniższy kod XML w pliku $PSHOME\MyTypes.ps1xml.

<?xml version="1.0" encoding="utf-8" ?>
<Types>
  <Type>
    <Name>System.IO.FileInfo</Name>
    <Members>
      <ScriptProperty>
        <Name>Age</Name>
        <GetScriptBlock>
          ((Get-Date) - ($this.CreationTime)).Days
        </GetScriptBlock>
      </ScriptProperty>
    </Members>
  </Type>
</Types>

Uruchom polecenie Update-TypeData , aby dodać nowy Types.ps1xml plik do bieżącej sesji. Polecenie używa parametru PrependData , aby umieścić nowy plik w kolejności pierwszeństwa wyższej niż oryginalne definicje.

Aby uzyskać więcej informacji na temat Update-TypeDataprogramu , zobacz Update-TypeData.

Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml

Aby przetestować zmianę Get-ChildItem , uruchom polecenie , aby pobrać plik PowerShell.exe w $PSHOME katalogu, a następnie przekazać plik do Format-List polecenia cmdlet, aby wyświetlić listę wszystkich właściwości pliku. W wyniku zmiany właściwość Age zostanie wyświetlona na liście.

Get-ChildItem $PSHOME\pwsh.exe | Select-Object Age

Plik XML w plikach Types.ps1xml

Pełną definicję schematu można znaleźć w pliku Types.xsd w repozytorium kodu źródłowego programu PowerShell w witrynie GitHub.

Tag <Types> zawiera wszystkie typy zdefiniowane w pliku. Powinien istnieć tylko jeden <Types> tag.

Każdy typ platformy .NET wymieniony w pliku powinien być reprezentowany przez <Type> tag.

Tagi typu muszą zawierać następujące tagi:

<Name>: zawiera nazwę objętego typu .NET.

<Members>: otacza tagi dla nowych właściwości i metod zdefiniowanych dla typu .NET.

Każdy z następujących tagów składowych może znajdować się wewnątrz tagu <Members> .

AliasProperty

Definiuje nową nazwę istniejącej właściwości.

Tag <AliasProperty> musi mieć <Name> tag określający nazwę nowej właściwości i tag określający istniejącą <ReferencedMemberName> właściwość.

Na przykład właściwość Alias Count jest aliasem właściwości Length obiektów tablicy.

<Type>
  <Name>System.Array</Name>
  <Members>
    <AliasProperty>
      <Name>Count</Name>
      <ReferencedMemberName>Length</ReferencedMemberName>
    </AliasProperty>
  </Members>
</Type>

CodeMethod

Odwołuje się do statycznej metody klasy .NET.

Tag <CodeMethod> musi mieć <Name> tag określający nazwę nowej metody i <CodeReference> tag określający kod, w którym zdefiniowano metodę.

Na przykład metoda ToString jest nazwą definicji kodu Microsoft.PowerShell.ToStringCodeMethods .

  <Type>
    <Name>System.Xml.XmlNode</Name>
    <Members>
      <CodeMethod>
        <Name>ToString</Name>
        <CodeReference>
          <TypeName>Microsoft.PowerShell.ToStringCodeMethods</TypeName>
          <MethodName>XmlNode</MethodName>
        </CodeReference>
      </CodeMethod>
    </Members>
  </Type>

CodeProperty

Odwołuje się do statycznej metody klasy .NET.

Tag <CodeProperty> musi mieć <Name> tag określający nazwę nowej właściwości i <GetCodeReference> tag określający kod, w którym zdefiniowano właściwość.

Na przykład właściwość System.IO.DirectoryInfo Mode obiektów jest właściwością kodu zdefiniowaną w dostawcy systemu plików programu PowerShell.

<Type>
  <Name>System.IO.DirectoryInfo</Name>
  <Members>
    <CodeProperty>
      <Name>Mode</Name>
      <GetCodeReference>
        <TypeName>
          Microsoft.PowerShell.Commands.FileSystemProvider
        </TypeName>
        <MethodName>Mode</MethodName>
      </GetCodeReference>
    </CodeProperty>
  </Members>
</Type>

Zestaw elementów członkowskich

Definiuje kolekcję elementów członkowskich (właściwości i metody).

Tagi <MemberSet> są wyświetlane w tagach podstawowych <Members> . Tagi muszą ująć <Name> tag otaczający nazwę zestawu elementów członkowskich i tag pomocniczy <Members> , który otacza elementy członkowskie (właściwości i metody) w zestawie. Każdy z tagów tworzących właściwość (na przykład <NoteProperty> lub <ScriptProperty>) lub metodę (np <Method> . lub <ScriptMethod>) może być elementami członkowskimi zestawu.

W Types.ps1xml plikach <MemberSet> tag służy do definiowania domyślnych widoków obiektów platformy .NET w programie PowerShell. W takim przypadku nazwa zestawu składowego (wartość w tagach<Name>) jest zawsze psStandardMembers, a nazwy właściwości (wartość tagu<Name>) są jednym z następujących elementów:

DefaultDisplayProperty: pojedyncza właściwość obiektu.
DefaultDisplayPropertySet: co najmniej jedna właściwości obiektu.
DefaultKeyPropertySet: co najmniej jedna kluczowa właściwości obiektu. Właściwość klucza identyfikuje wystąpienia wartości właściwości, takie jak liczba elementów w historii sesji.

Na przykład poniższy kod XML definiuje domyślny sposób wyświetlania usług (System.ServiceProcess.ServiceController obiektów), które są zwracane przez Get-Service polecenie cmdlet. Definiuje zestaw elementów członkowskich o nazwie PsStandardMembers , który składa się z domyślnego zestawu właściwości z właściwościami Status, Name i DisplayName .

<Type>
  <Name>System.ServiceProcess.ServiceController</Name>
  <Members>
    <MemberSet>
      <Name>PSStandardMembers</Name>
      <Members>
        <PropertySet>
          <Name>DefaultDisplayPropertySet</Name>
          <ReferencedProperties>
            <Name>Status</Name>
            <Name>Name</Name>
            <Name>DisplayName</Name>
          </ReferencedProperties>
        </PropertySet>
      </Members>
    </MemberSet>
  </Members>
</Type>

<Method>: odwołuje się do natywnej metody obiektu bazowego.

<Methods>: kolekcja metod obiektu.

UwagaWłaściwość

Definiuje właściwość z wartością statyczną.

Tag <NoteProperty> musi mieć <Name> tag określający nazwę nowej właściwości i <Value> tag określający wartość właściwości.

Na przykład poniższy kod XML tworzy właściwość Status dla obiektów System.IO.DirectoryInfo . Wartość właściwości Status to zawsze Powodzenie.

<Type>
  <Name>System.IO.DirectoryInfo</Name>
  <Members>
    <NoteProperty>
      <Name>Status</Name>
      <Value>Success</Value>
    </NoteProperty>
  </Members>
</Type>

WłaściwośćSet

Właściwości, które przyjmują argumenty i zwracają wartość.

<Properties>: kolekcja właściwości obiektu.

<Property>: właściwość obiektu podstawowego.

<PropertySet>: definiuje kolekcję właściwości obiektu.

Tag <PropertySet> musi mieć <Name> tag określający nazwę zestawu właściwości i <ReferencedProperty> tag określający właściwości. Nazwy właściwości są ujęte w <Name> tag.

W Types.ps1xmlsystemie <PropertySet> tagi służą do definiowania zestawów właściwości domyślnego wyświetlania obiektu. Możesz zidentyfikować domyślne wyświetlane wartości PsStandardMembers w <Name> tagu tagu <MemberSet> .

Na przykład poniższy kod XML tworzy właściwośćSet o nazwie DefaultDisplayPropertySet z trzema właściwościami ReferencedProperties.

<Type>
  <Name>System.ServiceProcess.ServiceController</Name>
  <Members>
    <MemberSet>
      <Name>PSStandardMembers</Name>
      <Members>
        <PropertySet>
          <Name>DefaultDisplayPropertySet</Name>
          <ReferencedProperties>
            <Name>Status</Name>
            <Name>Name</Name>
            <Name>DisplayName</Name>
          </ReferencedProperties>
        </PropertySet>
      </Members>
    </MemberSet>
  </Members>
</Type>

ScriptMethod

Definiuje metodę, której wartość jest wynikiem skryptu.

Tag <ScriptMethod> musi mieć <Name> tag określający nazwę nowej metody i <Script> tag, który otacza blok skryptu, który zwraca wynik metody.

Na przykład ConvertToDateTime metody i ConvertFromDateTime obiektów zarządzania (System.System.Management.ManagementObject) to metody skryptów używające ToDateTime metod i ToDmtfDateTime statycznych System.Management.ManagementDateTimeConverter klasy .

<Type>
 <Name>System.Management.ManagementObject</Name>
 <Members>
 <ScriptMethod>
   <Name>ConvertToDateTime</Name>
   <Script>
   [System.Management.ManagementDateTimeConverter]::ToDateTime($args[0])
   </Script>
 </ScriptMethod>
 <ScriptMethod>
   <Name>ConvertFromDateTime</Name>
   <Script>
   [System.Management.ManagementDateTimeConverter]::ToDmtfDateTime($args[0])
   </Script>
 </ScriptMethod>
 </Members>
</Type>

ScriptProperty

Definiuje właściwość, której wartość jest wynikiem skryptu.

Tag <ScriptProperty> musi mieć <Name> tag określający nazwę nowej właściwości i <GetScriptBlock> tag, który otacza blok skryptu, który zwraca wartość właściwości.

Na przykład właściwość VersionInfo obiektu System.IO.FileInfo jest właściwością skryptu, która wynika z użycia właściwości FullName metody statycznej System.Diagnostics.FileVersionInfo.

<Type>
  <Name>System.IO.FileInfo</Name>
  <Members>
    <ScriptProperty>
      <Name>VersionInfo</Name>
      <GetScriptBlock>
      [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName)
      </GetScriptBlock>
    </ScriptProperty>
  </Members>
</Type>

Aby uzyskać więcej informacji, zobacz Zestaw Windows PowerShell Software Development Kit (SDK).

Update-TypeData

Aby załadować Types.ps1xml pliki do sesji programu PowerShell, uruchom Update-TypeData polecenie cmdlet . Jeśli chcesz, aby typy w pliku miały pierwszeństwo przed typami we wbudowanym Types.ps1xml pliku, dodaj parametr PrependData klasy Update-TypeData. Update-TypeData dotyczy tylko bieżącej sesji. Aby wprowadzić zmianę we wszystkich przyszłych sesjach, wyeksportuj sesję lub dodaj Update-TypeData polecenie do profilu programu PowerShell.

Wyjątki występujące we właściwościach lub od dodawania właściwości do Update-TypeData polecenia nie zgłaszają błędów do StdErrpolecenia . Jest to pomijanie wyjątków, które wystąpiłyby w wielu typach typowych podczas formatowania i wyprowadzania. Jeśli uzyskujesz właściwości platformy .NET, możesz obejść pomijanie wyjątków przy użyciu składni metody, jak pokazano w poniższym przykładzie:

"hello".get_Length()

Należy pamiętać, że składnia metody może być używana tylko z właściwościami platformy .NET. Właściwości dodane przez uruchomienie Update-TypeData polecenia cmdlet nie mogą używać składni metody.

Podpisywanie pliku Types.ps1xml

Aby chronić użytkowników Types.ps1xml pliku, możesz podpisać plik przy użyciu podpisu cyfrowego. Aby uzyskać więcej informacji, zobacz about_Signing.