about_Types.ps1xml

Článek
10/04/2023

Krátký popis

Vysvětluje, jak pomocí Types.ps1xml souborů rozšířit typy objektů, které se používají v PowerShellu.

Dlouhý popis

Rozšířená data typu definují další vlastnosti a metody ("členy") typů objektů v PowerShellu. Existují dvě techniky přidání rozšířených dat typu do relace PowerShellu.

Types.ps1xml soubor: Soubor XML, který definuje data rozšířeného typu.
Update-TypeData: Rutina, která znovu načte Types.ps1xml soubory a definuje rozšířená data pro typy v aktuální relaci.

Toto téma popisuje Types.ps1xml soubory. Další informace o použití rutiny Update-TypeData k přidání dynamických rozšířených dat typu do aktuální relace naleznete v tématu Update-TypeData.

Informace o rozšířených datech typů

Rozšířená data typu definují další vlastnosti a metody ("členy") typů objektů v PowerShellu. Můžete rozšířit libovolný typ podporovaný prostředím PowerShell a použít přidané vlastnosti a metody stejným způsobem jako vlastnosti definované v typech objektů.

PowerShell například přidá vlastnost DateTime do všech System.DateTime objektů, jako jsou například ty, které rutina Get-Date vrátí.

(Get-Date).DateTime

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

Vlastnost DateTime nenajdete v popisu struktury System.DateTime, protože PowerShell tuto vlastnost přidá a zobrazí se jenom v PowerShellu.

PowerShell interně definuje výchozí sadu rozšířených typů. Tyto informace o typu se načtou v každé relaci PowerShellu při spuštění. Vlastnost DateTime je součástí této výchozí sady. Před PowerShellem 6 byly definice typu uloženy Types.ps1xml v instalačním adresáři PowerShellu ($PSHOME).

Přidání rozšířených dat typů do PowerShellu

V relacích PowerShellu existují tři zdroje rozšířených dat typu.

Rozšířená data typu jsou definována prostředím PowerShell a automaticky se načtou do každé relace PowerShellu. Počínaje PowerShellem 6 se tyto informace kompilují do PowerShellu Types.ps1xml a už se nedoručují do souboru.
Soubory Types.ps1xml , které moduly exportují, se načtou při importu modulu do aktuální relace.
Rozšířená data typu definovaná pomocí rutiny Update-TypeData se přidají pouze do aktuální relace. Neuloží se do souboru.

V relaci se rozšířená data typu ze tří zdrojů použijí na objekty stejným způsobem a jsou k dispozici pro všechny objekty zadaných typů.

Rutiny TypeData

Následující rutiny jsou součástí modulu Microsoft.PowerShell.Utility v PowerShellu 3.0 a novějším.

Get-TypeData: Získá rozšířená data typu v aktuální relaci.
Update-TypeData: Znovu načte Types.ps1xml soubory. Přidá do aktuální relace rozšířená data typu.
Remove-TypeData: Odebere rozšířená data typu z aktuální relace.

Další informace o těchto rutinách najdete v tématu nápovědy pro každou rutinu.

Předdefinované soubory Types.ps1xml

Soubory Types.ps1xml v $PSHOME adresáři se automaticky přidají do každé relace.

Soubor Types.ps1xml v instalačním adresáři PowerShellu ($PSHOME) je textový soubor založený na jazyce XML, který umožňuje přidat vlastnosti a metody do objektů, které se používají v PowerShellu. PowerShell obsahuje integrované Types.ps1xml soubory, které do typů .NET přidávají několik prvků, ale můžete vytvořit další Types.ps1xml soubory pro další rozšíření typů.

Například ve výchozím nastavení mají objekty pole (System.Array) vlastnost Length , která uvádí počet objektů v poli. Vzhledem k tomu, že název Length vlastnost jasně nepopisuje, PowerShell přidá vlastnost aliasu s názvem Count , která zobrazuje stejnou hodnotu. Následující kód XML přidá do System.Array typu vlastnost Count.

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

Pokud chcete získat nový AliasProperty, použijte Get-Member příkaz na libovolném poli, jak je znázorněno v následujícím příkladu.

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

Příkaz vrátí následující výsledky.

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)
# ...

V důsledku toho můžete v PowerShellu použít vlastnost Count nebo vlastnost Length polí. Příklad:

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

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

Vytváření nových souborů Types.ps1xml

Soubory .ps1xml nainstalované pomocí PowerShellu jsou digitálně podepsané, aby se zabránilo manipulaci, protože formátování může obsahovat bloky skriptů. Proto pokud chcete do typu .NET přidat vlastnost nebo metodu, vytvořte vlastní Types.ps1xml soubory a pak je přidejte do relace PowerShellu.

Pokud chcete vytvořit nový soubor, začněte zkopírováním existujícího Types.ps1xml souboru. Nový soubor může mít libovolný název, ale musí mít příponu .ps1xml názvu souboru. Nový soubor můžete umístit do libovolného adresáře, který je přístupný pro PowerShell, ale je užitečné umístit soubory do instalačního adresáře PowerShellu ($PSHOME) nebo do podadresáře instalačního adresáře.

Po uložení nového souboru použijte rutinu Update-TypeData k přidání nového souboru do relace PowerShellu. Pokud chcete, aby vaše typy měli přednost před předdefinovanými typy, použijte parametr PrependData rutiny Update-TypeData . Update-TypeData ovlivňuje pouze aktuální relaci. Pokud chcete provést změnu všech budoucích relací, vyexportujte konzolu Update-TypeData nebo přidejte příkaz do profilu PowerShellu.

Types.ps1xml a Add-Member

Soubory Types.ps1xml přidávají vlastnosti a metody do všech instancí objektů zadaného typu .NET v ovlivněné relaci PowerShellu. Pokud ale potřebujete přidat vlastnosti nebo metody pouze do jedné instance objektu, použijte rutinu Add-Member .

Další informace naleznete v tématu Přidání člena.

Příklad: Přidání člena věku do objektů FileInfo

Tento příklad ukazuje, jak přidat Age vlastnost System.IO.FileInfo objekty. Stáří souboru je rozdíl mezi časem jeho vytvoření a aktuálním časem ve dnech.

Vzhledem k tomu, že vlastnost Age se počítá pomocí bloku skriptu, najděte <ScriptProperty> značku, která se má použít jako model pro novou vlastnost Age .

Uložte následující kód XML do souboru $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>

Spuštěním příkazu Update-TypeData přidejte nový Types.ps1xml soubor do aktuální relace. Příkaz používá parametr PrependData k umístění nového souboru do pořadí přednosti vyšší než původní definice.

Další informace o Update-TypeDatanástroji Update-TypeData naleznete v tématu Update-TypeData.

Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml

Pokud chcete změnu otestovat, spuštěním Get-ChildItem příkazu získejte soubor PowerShell.exe v $PSHOME adresáři a potom soubor předejte rutině Format-List , aby se vypsaly všechny vlastnosti souboru. V důsledku změny se v seznamu zobrazí vlastnost Age .

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

XML v souborech Types.ps1xml

Úplnou definici schématu najdete v type.xsd v úložišti zdrojového kódu PowerShellu na GitHubu.

Značka <Types> uzavře všechny typy, které jsou definovány v souboru. Měla by existovat jenom jedna <Types> značka.

Každý typ .NET uvedený v souboru by měl být reprezentován značkou <Type> .

Značky typu musí obsahovat následující značky:

<Name>: Uzavře název ovlivněného typu .NET.

<Members>: Uzavře značky pro nové vlastnosti a metody definované pro typ .NET.

Uvnitř značky může být <Members> libovolná z následujících značek členů.

AliasProperty

Definuje nový název existující vlastnosti.

Značka <AliasProperty> musí mít <Name> značku, která určuje název nové vlastnosti a <ReferencedMemberName> značku, která určuje existující vlastnost.

Například vlastnost Alias Count je alias pro length vlastnost array objekty.

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

CodeMethod

Odkazuje na statickou metodu třídy .NET.

Značka <CodeMethod> musí mít <Name> značku, která určuje název nové metody a <CodeReference> značku, která určuje kód, ve kterém je metoda definována.

Například ToString metoda je název definice kódu 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

Odkazuje na statickou metodu třídy .NET.

Značka <CodeProperty> musí mít <Name> značku, která určuje název nové vlastnosti a <GetCodeReference> značku, která určuje kód, ve kterém je vlastnost definována.

Například Vlastnost Mode objektů je vlastnost System.IO.DirectoryInfo kódu definovaná ve zprostředkovateli systému souborů PowerShellu.

<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>

Memberset

Definuje kolekci členů (vlastností a metod).

Značky <MemberSet> se zobrazí v primárních <Members> značkách. Značky musí ohraničovat <Name> značku obklopící název sady členů a sekundární <Members> značku, která obklopuje členy (vlastnosti a metody) v sadě. Každá ze značek, která vytváří vlastnost (například <NoteProperty> nebo <ScriptProperty>) nebo metodu (například <Method> nebo <ScriptMethod>) může být členy sady.

V Types.ps1xml souborech <MemberSet> se značka používá k definování výchozích zobrazení objektů .NET v PowerShellu. V tomto případě je název sady členů (hodnota v rámci <Name> značek) vždy PsStandardMembers a názvy vlastností (hodnota <Name> značky) jsou jedním z následujících:

DefaultDisplayProperty: Jedna vlastnost objektu.
DefaultDisplayPropertySet: Jedna nebo více vlastností objektu.
DefaultKeyPropertySet: Jedna nebo více klíčových vlastností objektu. Vlastnost klíče identifikuje instance hodnot vlastností, jako je počet ID položek v historii relace.

Například následující XML definuje výchozí zobrazení služeb (System.ServiceProcess.ServiceController objektů), které vrací rutina Get-Service . Definuje členovou sadu s názvem PsStandardMembers, která se skládá z výchozí sady vlastností Status, Name a DisplayName vlastnosti.

<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>: Odkazuje na nativní metodu základního objektu.

<Methods>: Kolekce metod objektu.

PoznámkaProperty

Definuje vlastnost se statickou hodnotou.

Značka <NoteProperty> musí mít <Name> značku, která určuje název nové vlastnosti a <Value> značku, která určuje hodnotu vlastnosti.

Například následující XML vytvoří vlastnost Status pro Objekty System.IO.DirectoryInfo . Hodnota vlastnosti Status je vždy Úspěch.

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

PropertySet

Vlastnosti, které přebírají argumenty a vrací hodnotu.

<Properties>: Kolekce vlastností objektu.

<Property>: Vlastnost základního objektu.

<PropertySet>: Definuje kolekci vlastností objektu.

Značka <PropertySet> musí mít <Name> značku, která určuje název sady vlastností a <ReferencedProperty> značku, která určuje vlastnosti. Názvy vlastností jsou uzavřeny do <Name> značky.

V Types.ps1xml, <PropertySet> značky slouží k definování sad vlastností pro výchozí zobrazení objektu. Výchozí hodnoty PsStandardMembers můžete identifikovat ve <Name> značce <MemberSet> značky.

Například následující XML vytvoří PropertySet s názvem DefaultDisplayPropertySet se třemi 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>

SkriptMethod

Definuje metodu, jejíž hodnota je výstupem skriptu.

Značka <ScriptMethod> musí mít <Name> značku, která určuje název nové metody a <Script> značku, která uzavře blok skriptu, který vrací výsledek metody.

Například ConvertToDateTime a ConvertFromDateTime metody objektů správy (System.System.Management.ManagementObject) jsou metody skriptu, které používají ToDateTime a ToDmtfDateTime statické metody System.Management.ManagementDateTimeConverter třídy.

<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

Definuje vlastnost, jejíž hodnota je výstupem skriptu.

Značka <ScriptProperty> musí mít <Name> značku, která určuje název nové vlastnosti a <GetScriptBlock> značku, která uzavře blok skriptu, který vrací hodnotu vlastnosti.

Například VersionInfo Vlastnost System.IO.FileInfo objektu je vlastnost skriptu, která je výsledkem použití FullName Vlastnost GetVersionInfo static metoda System.Diagnostics.FileVersionInfo objekty.

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

Další informace najdete v sadě Windows PowerShell Software Development Kit (SDK).

Update-TypeData

Pokud chcete načíst Types.ps1xml soubory do relace PowerShellu, spusťte rutinu Update-TypeData . Pokud chcete, aby typy v souboru přednost před typy v předdefinovaném Types.ps1xml souboru, přidejte parametr PrependData .Update-TypeData Update-TypeData ovlivňuje pouze aktuální relaci. Pokud chcete provést změnu všech budoucích relací, exportujte relaci nebo přidejte Update-TypeData příkaz do profilu PowerShellu.

Výjimky, ke kterým dochází ve vlastnostech nebo při přidávání vlastností do Update-TypeData příkazu, neoznamují chyby .StdErr To je potlačení výjimek, které by se vyskytly v mnoha běžných typech při formátování a výstupu. Pokud získáváte vlastnosti rozhraní .NET, můžete místo toho obejít potlačení výjimek pomocí syntaxe metody, jak je znázorněno v následujícím příkladu:

"hello".get_Length()

Všimněte si, že syntaxi metody lze použít pouze s vlastnostmi .NET. Vlastnosti přidané spuštěním rutiny nemůžou Update-TypeData používat syntaxi metody.

Podepsání souboru Types.ps1xml

Pokud chcete chránit uživatele souboru Types.ps1xml , můžete ho podepsat pomocí digitálního podpisu. Další informace najdete v tématu about_Signing.