Add-Type

Přidá třídu Microsoft .NET do relace PowerShellu.

Syntax

Add-Type
   [-TypeDefinition] <String>
   [-Language <Language>]
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]
Add-Type
   [-Name] <String>
   [-MemberDefinition] <String[]>
   [-Namespace <String>]
   [-UsingNamespace <String[]>]
   [-Language <Language>]
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]
Add-Type
   [-Path] <String[]>
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]
Add-Type
   -LiteralPath <String[]>
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [-CompilerOptions <String[]>]
   [<CommonParameters>]
Add-Type
   -AssemblyName <String[]>
   [-PassThru]
   [<CommonParameters>]

Description

Rutina Add-Type umožňuje definovat třídu Microsoft .NET Core v relaci PowerShellu. Pak můžete vytvořit instanci objektů pomocí New-Object rutiny a použít objekty stejně jako jakýkoli objekt .NET Core. Pokud do profilu PowerShellu Add-Type přidáte příkaz, třída je dostupná ve všech relacích PowerShellu.

Typ můžete zadat zadáním existujícího sestavení nebo souborů zdrojového kódu nebo můžete zadat vložený nebo uložený zdrojový kód v proměnné. Můžete dokonce zadat pouze metodu a Add-Type definuje a vygeneruje třídu. Ve Windows můžete pomocí této funkce v PowerShellu volat platformu (P/Invoke) volání nespravovaných funkcí. Pokud zadáte zdrojový kód, Add-Type zkompiluje zadaný zdrojový kód a vygeneruje sestavení v paměti, které obsahuje nové typy .NET Core.

Parametry Add-Type můžete použít k určení alternativního jazyka a kompilátoru, jazyk C# je výchozí, možnosti kompilátoru, závislosti sestavení, obor názvů třídy, názvy typu a výsledné sestavení.

Počínaje PowerShellem 7 nekompiluje typ, Add-Type pokud již existuje typ se stejným názvem. Add-Type Také hledá sestavení ve složce pod složkouref, která obsahuje pwsh.dll.

Příklady

Příklad 1: Přidání typu .NET do relace

Tento příklad přidá BasicTest třídy do relace zadáním zdrojového kódu, který je uložen v proměnné. BasicTest třída slouží k přidání celých čísel, vytvoření objektu a násobení celých čísel.

$Source = @"
public class BasicTest
{
  public static int Add(int a, int b)
    {
        return (a + b);
    }
  public int Multiply(int a, int b)
    {
    return (a * b);
    }
}
"@

Add-Type -TypeDefinition $Source
[BasicTest]::Add(4, 3)
$BasicTestObject = New-Object BasicTest
$BasicTestObject.Multiply(5, 2)

Proměnná $Source ukládá zdrojový kód pro třídu. Typ má volanou Add statickou metodu a ne statickou metodu s názvem Multiply.

Rutina Add-Type přidá třídu do relace. Vzhledem k tomu, že používá vložený zdrojový kód, použije příkaz parametr TypeDefinition k určení kódu v $Source proměnné.

Add Statická metoda BasicTest třídy používá dvojité dvojtečky (::) k určení statického členu třídy. Přidají se celá čísla a zobrazí se součet.

Rutina New-Object vytvoří instanci třídy BasicTest . Uloží nový objekt do $BasicTestObject proměnné.

$BasicTestObject používá metodu Multiply . Celá čísla se vynásobí a zobrazí se produkt.

Příklad 2: Prozkoumání přidaného typu

Tento příklad používá rutinu Get-Member k prozkoumání objektů, které Add-Type a New-Object rutiny vytvořené v příkladu 1.

[BasicTest] | Get-Member

TypeName: System.RuntimeType

Name                 MemberType Definition
----                 ---------- ----------
AsType               Method     type AsType()
Clone                Method     System.Object Clone(), System.Object ICloneable.Clone()
Equals               Method     bool Equals(System.Object obj), bool Equals(type o)
FindInterfaces       Method     type[] FindInterfaces(System.Reflection.TypeFilter filter...
...

[BasicTest] | Get-Member -Static

TypeName: BasicTest

Name            MemberType Definition
----            ---------- ----------
Add             Method     static int Add(int a, int b)
Equals          Method     static bool Equals(System.Object objA, System.Object objB)
new             Method     BasicTest new()
ReferenceEquals Method     static bool ReferenceEquals(System.Object objA, System.Object objB)

$BasicTestObject | Get-Member

TypeName: BasicTest

Name        MemberType Definition
----        ---------- ----------
Equals      Method     bool Equals(System.Object obj)
GetHashCode Method     int GetHashCode()
GetType     Method     type GetType()
Multiply    Method     int Multiply(int a, int b)
ToString    Method     string ToString()

Rutina Get-Member získá typ a členy Třídy BasicTest , která Add-Type byla přidána do relace. Příkaz Get-Member zjistí, že se jedná o objekt System.RuntimeType , který je odvozen z Třídy System.Object .

StatickýGet-Member parametr získá statické vlastnosti a metody BasicTest třídy. Výstup ukazuje, že Add metoda je zahrnuta.

Rutina Get-Member získá členy objektu uloženého $BasicTestObject v proměnné. $BasicTestObject byla vytvořena pomocí New-Object rutiny s BasicTest třídy. Výstup zjistí, že hodnota $BasicTestObject proměnné je instance BasicTest třídy a že obsahuje člen volal Multiply.

Příklad 3: Přidání typů ze sestavení

Tento příklad přidá třídy ze NJsonSchema.dll sestavení do aktuální relace.

Set-Location -Path $PSHOME
$AccType = Add-Type -AssemblyName *jsonschema* -PassThru

Set-Location pomocí parametru Path určuje proměnnou $PSHOME . Proměnná odkazuje na instalační adresář PowerShellu, ve kterém se nachází soubor DLL.

Proměnná $AccType ukládá objekt vytvořený pomocí rutiny Add-Type . Add-Type používá parametr AssemblyName k určení názvu sestavení. Zástupný znak hvězdičky* () umožňuje získat správné sestavení, i když si nejste jistí názvem nebo jeho pravopisem. Parametr PassThru generuje objekty, které představují třídy přidané do relace.

Příklad 4: Volání nativních rozhraní API systému Windows

Tento příklad ukazuje, jak volat nativní rozhraní API systému Windows v PowerShellu. Add-Type používá mechanismus Volání platformy (P/Invoke) k volání funkce z User32.dll PowerShellu. Tento příklad funguje jenom na počítačích s operačním systémem Windows.

$Signature = @"
[DllImport("user32.dll")]public static extern bool ShowWindowAsync(IntPtr hWnd, int nCmdShow);
"@

$ShowWindowAsync = Add-Type -MemberDefinition $Signature -Name "Win32ShowWindowAsync" -Namespace Win32Functions -PassThru

# Minimize the PowerShell console

$ShowWindowAsync::ShowWindowAsync((Get-Process -Id $pid).MainWindowHandle, 2)

# Restore the PowerShell console

$ShowWindowAsync::ShowWindowAsync((Get-Process -Id $Pid).MainWindowHandle, 4)

Proměnná $Signature ukládá podpis ShowWindowAsync funkce v jazyce C#. Aby se zajistilo, že výsledná metoda je viditelná v relaci PowerShellu, public bylo klíčové slovo přidáno do standardního podpisu. Další informace naleznete v tématu ShowWindowAsync funkce.

Proměnná $ShowWindowAsync ukládá objekt vytvořený parametrem Add-TypePassThru . Rutina Add-TypeShowWindowAsync přidá funkci do relace PowerShellu jako statickou metodu. Příkaz používá parametr MemberDefinition k určení definice metody uložené v $Signature proměnné. Příkaz používá parametry Name a Namespace k určení názvu a oboru názvů pro třídu. Parametr PassThru vygeneruje objekt, který představuje typy.

Nová ShowWindowAsync statická metoda se používá v příkazech k minimalizaci a obnovení konzoly PowerShellu. Metoda přebírá dva parametry: popisovač okna a celé číslo, které určuje, jak se okno zobrazí.

Pokud chcete minimalizovat konzolu Get-Process PowerShellu, ShowWindowAsync pomocí rutiny s automatickou $PID proměnnou získáte proces, který je hostitelem aktuální relace PowerShellu. Pak používá MainWindowHandle vlastnost aktuální proces a hodnotu 2, která představuje SW_MINIMIZE hodnotu.

Chcete-li okno obnovit, ShowWindowAsync používá hodnotu 4 pro pozici okna, která představuje SW_RESTORE hodnotu.

Chcete-li maximalizovat okno, použijte hodnotu 3 , která představuje SW_MAXIMIZE.

Parametry

-AssemblyName

Určuje název sestavení, které obsahuje typy. Add-Type přebírá typy ze zadaného sestavení. Tento parametr se vyžaduje při vytváření typů na základě názvu sestavení.

Zadejte úplný nebo jednoduchý název sestavení, označovaný také jako částečný název sestavení. V názvu sestavení jsou povoleny zástupné znaky. Pokud zadáte jednoduchý nebo částečný název, Add-Type přeloží ho na úplný název a pak použije úplný název k načtení sestavení.

Tento parametr nepřijímá cestu ani název souboru. Pokud chcete zadat cestu k souboru knihovny DLL (Assembly Dynamic-Link Library), použijte parametr Path .

Type:String[]
Aliases:AN
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True

-CompilerOptions

Určuje možnosti kompilátoru zdrojového kódu. Tyto možnosti se odesílají kompilátoru bez revize.

Tento parametr umožňuje kompilátoru směrovat na generování spustitelného souboru, prostředků pro vložení nebo nastavení možností příkazového řádku, jako je například tato /unsafe možnost.

Parametry CompilerOptions a ReferencedAssemblies nemůžete použít ve stejném příkazu.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-IgnoreWarnings

Ignoruje upozornění kompilátoru. Pomocí tohoto parametru zabráníte Add-Type zpracování upozornění kompilátoru jako chyb.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-Language

Určuje jazyk, který se používá ve zdrojovém kódu. Přijatelná hodnota tohoto parametru je

  • CSharp
Type:Language
Accepted values:CSharp
Position:Named
Default value:CSharp
Accept pipeline input:False
Accept wildcard characters:False

-LiteralPath

Určuje cestu k souborům zdrojového kódu nebo souborům DLL sestavení, které obsahují typy. Na rozdíl od cesty se hodnota parametru LiteralPath používá přesně tak, jak je zadaný. Žádné znaky nejsou interpretovány jako zástupné znaky. Pokud cesta obsahuje řídicí znaky, uzavřete ji do jednoduchých uvozovek. Jednoduché uvozovky říkají PowerShellu, aby neinterpretovat žádné znaky jako řídicí sekvence.

Type:String[]
Aliases:PSPath, LP
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-MemberDefinition

Určuje nové vlastnosti nebo metody třídy. Add-Type vygeneruje kód šablony, který je nutný k podpoře vlastností nebo metod.

Ve Windows můžete pomocí této funkce v PowerShellu volat platformu (P/Invoke) volání nespravovaných funkcí.

Type:String[]
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Name

Určuje název třídy, která se má vytvořit. Tento parametr se vyžaduje při generování typu z definice člena.

Název typu a obor názvů musí být v rámci relace jedinečný. Typ nelze uvolnit ani změnit. Pokud chcete změnit kód pro typ, musíte změnit název nebo spustit novou relaci PowerShellu. Jinak příkaz selže.

Type:String
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Namespace

Určuje obor názvů pro typ.

Pokud tento parametr není součástí příkazu, typ se vytvoří v oboru názvů Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes . Pokud je parametr součástí příkazu s prázdnou řetězcovou hodnotou nebo hodnotou $Null, typ se vygeneruje v globálním oboru názvů.

Type:String
Aliases:NS
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-OutputAssembly

Vygeneruje soubor DLL pro sestavení se zadaným názvem v umístění. Zadejte volitelnou cestu a název souboru. Jsou povoleny zástupné znaky. Ve výchozím nastavení Add-Type generuje sestavení pouze v paměti.

Type:String
Aliases:OA
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True

-OutputType

Určuje výstupní typ výstupního sestavení. Ve výchozím nastavení není zadán žádný výstupní typ. Tento parametr je platný pouze v případě, že je v příkazu zadáno výstupní sestavení. Další informace o hodnotách naleznete v tématu OutputAssemblyType – výčet.

Přijatelné hodnoty pro tento parametr jsou následující:

  • ConsoleApplication
  • Library
  • WindowsApplication

Důležité

Od PowerShellu 7.1 a WindowsApplication nejsou podporované a PowerShell vyvolá ukončovací chybu, ConsoleApplication pokud jsou některé z těchto hodnot zadány jako hodnoty pro parametr OutputType.

Type:OutputAssemblyType
Aliases:OT
Accepted values:ConsoleApplication, Library, WindowsApplication
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

Vrátí objekt System.Runtime , který představuje přidané typy. Ve výchozím nastavení tato rutina negeneruje žádný výstup.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-Path

Určuje cestu k souborům zdrojového kódu nebo souborům DLL sestavení, které obsahují typy.

Pokud odešlete soubory zdrojového kódu, Add-Type zkompiluje kód v souborech a vytvoří sestavení typů v paměti. Přípona souboru zadaná v hodnotě Path určuje kompilátor, který Add-Type používá.

Pokud odešlete soubor sestavení, Add-Type vezme typy ze sestavení. Chcete-li zadat sestavení v paměti nebo globální mezipaměť sestavení, použijte parametr AssemblyName .

Type:String[]
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ReferencedAssemblies

Určuje sestavení, na kterých typ závisí. Ve výchozím nastavení Add-Type odkazy System.dll a System.Management.Automation.dll. Sestavení, která zadáte pomocí tohoto parametru, se kromě výchozích sestavení odkazují.

Počínaje PowerShellem 6 neobsahuje referencedAssemblies výchozí sestavení .NET. Do hodnoty předané tomuto parametru musíte zahrnout konkrétní odkaz.

Parametry CompilerOptions a ReferencedAssemblies nemůžete použít ve stejném příkazu.

Type:String[]
Aliases:RA
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TypeDefinition

Určuje zdrojový kód, který obsahuje definice typu. Zadejte zdrojový kód do řetězce nebo řetězce sem nebo zadejte proměnnou, která obsahuje zdrojový kód. Další informace o řetězcích najdete v tématu about_Quoting_Rules.

Do definice typu zahrňte deklaraci oboru názvů. Pokud deklaraci oboru názvů vynecháte, váš typ může mít stejný název jako jiný typ nebo zástupce jiného typu, což způsobí neúmyslné přepsání. Pokud například definujete typ s názvem Výjimka, skripty, které jako zástupce pro System.Exception používají výjimku, selžou.

Type:String
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-UsingNamespace

Určuje další obory názvů, které jsou požadovány pro třídu. To se podobá klíčovému slovu UsingC# .

Ve výchozím nastavení Add-Type odkazuje na systémový obor názvů. Při použití Add-Typeparametru MemberDefinition odkazuje ve výchozím nastavení také na obor názvů System.Runtime.InteropServices. Obory názvů, které přidáte pomocí parametru UsingNamespace , se kromě výchozích oborů názvů odkazují.

Type:String[]
Aliases:Using
Position:Named
Default value:System namespace
Accept pipeline input:False
Accept wildcard characters:False

Vstupy

None

Do kanálu Add-Typenelze odesílat objekty.

Výstupy

None or System.Type

Když použijete parametr PassThru , Add-Type vrátí objekt System.Type , který představuje nový typ. Jinak tato rutina negeneruje žádný výstup.

Poznámky

Typy, které přidáte, existují pouze v aktuální relaci. Pokud chcete tyto typy používat ve všech relacích, přidejte je do profilu PowerShellu. Další informace o profilu najdete v tématu about_Profiles.

Názvy typů a obory názvů musí být v rámci relace jedinečné. Typ nelze uvolnit ani změnit. Pokud potřebujete změnit kód pro typ, musíte změnit název nebo spustit novou relaci PowerShellu. Jinak příkaz selže.

V Windows PowerShell (verze 5.1 a níže) je potřeba použít Add-Type cokoli, co ještě není načtené. Nejčastěji se to týká sestavení nalezených v globální mezipaměti sestavení (GAC). V PowerShellu 6 a novějším není k dispozici žádný GAC, takže PowerShell nainstaluje vlastní sestavení do $PSHome. Tato sestavení se automaticky načtou na žádost, takže není nutné je načíst Add-Type . Použití Add-Type ale stále umožňuje implicitně kompatibilní skripty s libovolnou verzí PowerShellu.

Sestavení v GAC lze načíst podle názvu typu, nikoli podle cesty. Načítání sestavení z libovolné cesty vyžaduje Add-Type, protože tato sestavení nelze načíst automaticky.