Add-Type
Fügt einer PowerShell-Sitzung eine Microsoft .NET-Klasse hinzu.
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>]
Beschreibung
Mit Add-Type
dem Cmdlet können Sie eine Microsoft .NET Core-Klasse in Ihrer PowerShell-Sitzung definieren. Anschließend können Sie Objekte mithilfe des New-Object
Cmdlets instanziieren und die -Objekte wie jedes .NET Core-Objekt verwenden. Wenn Sie Ihrem PowerShell-Profil einen Add-Type
Befehl hinzufügen, ist die -Klasse in allen PowerShell-Sitzungen verfügbar.
Sie können den Typ angeben, indem Sie eine vorhandene Assembly oder Quellcodedateien angeben, oder Sie können den Quellcode inline oder in einer Variablen gespeichert angeben. Sie können sogar nur eine Methode angeben und Add-Type
die -Klasse definieren und generieren. Unter Windows können Sie dieses Feature verwenden, um Plattformaufrufe (P/Invoke) für nicht verwaltete Funktionen in PowerShell auszuführen. Wenn Sie Quellcode angeben, Add-Type
kompiliert sie den angegebenen Quellcode und generiert eine Speicherassembly, die die neuen .NET Core-Typen enthält.
Sie können die Parameter von Add-Type
verwenden, um eine alternative Sprache und einen Compiler anzugeben. C# ist die Standardeinstellung, Compileroptionen, Assemblyabhängigkeiten, der Klassennamespace, die Namen des Typs und die resultierende Assembly.
Ab PowerShell 7 wird kein Typ kompiliert, Add-Type
wenn bereits ein Typ mit demselben Namen vorhanden ist. Add-Type
Sucht auch nach Assemblys in einem ref
Ordner unter dem Ordner, der enthältpwsh.dll
.
Beispiele
Beispiel 1: Hinzufügen eines .NET-Typs zu einer Sitzung
In diesem Beispiel wird der Sitzung die BasicTest-Klasse hinzugefügt, indem Quellcode angegeben wird, der in einer Variablen gespeichert ist. Die BasicTest-Klasse wird verwendet, um ganze Zahlen hinzuzufügen, ein Objekt zu erstellen und ganze Zahlen zu multiplizieren.
$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)
Die $Source
Variable speichert den Quellcode für die -Klasse. Der Typ verfügt über eine statische Methode namens Add
und eine nicht statische Methode namens Multiply
.
Das Add-Type
Cmdlet fügt die -Klasse der Sitzung hinzu. Da er Inline-Quellcode verwendet, verwendet der Befehl den TypeDefinition-Parameter , um den Code in der $Source
Variablen anzugeben.
Die Add
statische Methode der BasicTest-Klasse verwendet die Doppelkolonzeichen (::
), um ein statisches Element der Klasse anzugeben. Die ganzen Zahlen werden hinzugefügt, und die Summe wird angezeigt.
Das New-Object
Cmdlet instanziiert eine instance der BasicTest-Klasse. Das neue Objekt wird in der $BasicTestObject
Variablen gespeichert.
$BasicTestObject
verwendet die Multiply
-Methode. Die ganzen Zahlen werden multipliziert, und das Produkt wird angezeigt.
Beispiel 2: Untersuchen eines hinzugefügten Typs
In diesem Beispiel wird das Get-Member
Cmdlet verwendet, um die Objekte zu untersuchen, die die Add-Type
Cmdlets und New-Object
in Beispiel 1 erstellt haben.
[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()
Das Get-Member
Cmdlet ruft den Typ und die Member der BasicTest-Klasse ab, die Add-Type
der Sitzung hinzugefügt wurden. Der Get-Member
Befehl zeigt an, dass es sich um ein System.RuntimeType-Objekt handelt, das von der System.Object-Klasse abgeleitet ist.
Der Get-Member
Static-Parameter ruft die statischen Eigenschaften und Methoden der BasicTest-Klasse ab. Die Ausgabe zeigt, dass die Add
-Methode enthalten ist.
Das Get-Member
Cmdlet ruft die Elemente des Objekts ab, die in der $BasicTestObject
Variablen gespeichert sind.
$BasicTestObject
wurde mithilfe des Cmdlets New-Object
mit der BasicTest-Klasse erstellt. Die Ausgabe zeigt, dass der Wert der $BasicTestObject
Variablen ein instance der BasicTest-Klasse ist und ein Member namens enthältMultiply
.
Beispiel 3: Hinzufügen von Typen aus einer Assembly
In diesem Beispiel werden die Klassen aus der NJsonSchema.dll
Assembly der aktuellen Sitzung hinzugefügt.
Set-Location -Path $PSHOME
$AccType = Add-Type -AssemblyName *jsonschema* -PassThru
Set-Location
verwendet den Path-Parameter , um die $PSHOME
Variable anzugeben. Die Variable verweist auf das PowerShell-Installationsverzeichnis, in dem sich die DLL-Datei befindet.
Die $AccType
Variable speichert ein Objekt, das mit dem Add-Type
Cmdlet erstellt wurde. Add-Type
verwendet den AssemblyName-Parameter , um den Namen der Assembly anzugeben. Mit dem Platzhalterzeichen Sternchen (*
) können Sie die richtige Assembly abrufen, auch wenn Sie sich nicht sicher sind, ob der Name oder die Schreibweise vorhanden ist. Der PassThru-Parameter generiert Objekte, die die Klassen darstellen, die der Sitzung hinzugefügt werden.
Beispiel 4: Aufrufen nativer Windows-APIs
In diesem Beispiel wird veranschaulicht, wie Sie native Windows-APIs in PowerShell aufrufen. Add-Type
verwendet den P/Invoke-Mechanismus (Platform Invoke), um eine Funktion aus User32.dll
PowerShell aufzurufen. Dieses Beispiel funktioniert nur auf Computern, auf denen das Windows-Betriebssystem ausgeführt wird.
$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)
Die $Signature
Variable speichert die C#-Signatur der ShowWindowAsync
Funktion. Um sicherzustellen, dass die resultierende Methode in einer PowerShell-Sitzung sichtbar ist, wurde die public
Schlüsselwort (keyword) der Standardsignatur hinzugefügt. Weitere Informationen finden Sie unter ShowWindowAsync-Funktion.
Die $ShowWindowAsync
Variable speichert das Objekt, das mit dem Add-Type
PassThru-Parameter erstellt wurde.
Das Add-Type
Cmdlet fügt die ShowWindowAsync
Funktion der PowerShell-Sitzung als statische Methode hinzu. Der Befehl verwendet den MemberDefinition-Parameter , um die in der $Signature
Variablen gespeicherte Methodendefinition anzugeben. Der Befehl verwendet die Parameter Name und Namespace, um einen Namen und einen Namespace für die Klasse anzugeben. Der PassThru-Parameter generiert ein -Objekt, das die Typen darstellt.
Die neue ShowWindowAsync
statische Methode wird in den Befehlen verwendet, um die PowerShell-Konsole zu minimieren und wiederherzustellen. Die -Methode verwendet zwei Parameter: das Fensterhandle und eine ganze Zahl, die angibt, wie das Fenster angezeigt wird.
Um die PowerShell-Konsole zu minimieren, ShowWindowAsync
verwenden Sie das Get-Process
Cmdlet mit der $PID
automatischen Variablen, um den Prozess abzurufen, der die aktuelle PowerShell-Sitzung hostt. Anschließend wird die MainWindowHandle-Eigenschaft des aktuellen Prozesses und ein Wert von 2
verwendet, der den SW_MINIMIZE
Wert darstellt.
Zum Wiederherstellen des Fensters ShowWindowAsync
wird der Wert von 4
für die Fensterposition verwendet, der den SW_RESTORE
Wert darstellt.
Um das Fenster zu maximieren, verwenden Sie den Wert von, der 3
darstellt SW_MAXIMIZE
.
Parameter
-AssemblyName
Gibt den Namen einer Assembly an, die die Typen enthält. Add-Type
übernimmt die Typen aus der angegebenen Assembly. Dieser Parameter ist erforderlich, wenn Sie Typen basierend auf einem Assemblynamen erstellen.
Geben Sie den vollständigen oder einfachen Namen einer Assembly ein, der auch als Teilname bezeichnet wird. Der Assemblyname darf Platzhalterzeichen enthalten. Wenn Sie einen einfachen oder teilweisen Namen eingeben, Add-Type
löst ihn in den vollständigen Namen auf und verwendet dann den vollständigen Namen, um die Assembly zu laden.
Dieser Parameter akzeptiert keinen Pfad oder Dateinamen. Verwenden Sie den Path-Parameter , um den Pfad zur DLL-Datei (Dynamic Link Library) der Assembly einzugeben.
Type: | String[] |
Aliases: | AN |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-CompilerOptions
Gibt die Optionen für den Quellcodecompiler an. Diese Optionen werden ohne Revision an den Compiler gesendet.
Mit diesem Parameter können Sie den Compiler anweisen, eine ausführbare Datei zu generieren, Ressourcen einzubetten oder Befehlszeilenoptionen wie die /unsafe
Option festzulegen.
Sie können die Parameter CompilerOptions und ReferencedAssemblies nicht im gleichen Befehl verwenden.
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-IgnoreWarnings
Ignoriert Compilerwarnungen. Verwenden Sie diesen Parameter, um zu verhindern, dass Add-Type
Compilerwarnungen als Fehler behandelt werden.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Language
Gibt die Sprache an, die im Quellcode verwendet wird. Der zulässige Wert für diesen Parameter ist
CSharp
Type: | Language |
Accepted values: | CSharp |
Position: | Named |
Default value: | CSharp |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-LiteralPath
Gibt den Pfad zu Quellcodedateien oder Assembly-DLL-Dateien an, die die Typen enthalten. Im Gegensatz zu Path wird der Wert des LiteralPath-Parameters genau so verwendet, wie er eingegeben wird. Es werden keine Zeichen als Platzhalter interpretiert. Wenn der Pfad Escapezeichen enthält, müssen Sie ihn in einfache Anführungszeichen einschließen. Einfache Anführungszeichen weisen PowerShell an, keine Zeichen als Escapesequenzen zu interpretieren.
Type: | String[] |
Aliases: | PSPath, LP |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MemberDefinition
Gibt neue Eigenschaften oder Methoden für die Klasse an. Add-Type
generiert den Vorlagencode, der zur Unterstützung der Eigenschaften oder Methoden erforderlich ist.
Unter Windows können Sie dieses Feature verwenden, um Plattformaufrufe (P/Invoke) für nicht verwaltete Funktionen in PowerShell auszuführen.
Type: | String[] |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Name
Gibt den Namen der zu erstellenden Klasse an. Dieser Parameter ist beim Generieren eines Typs aus einer Memberdefinition erforderlich.
Der Typname und der Namespace müssen innerhalb einer Sitzung eindeutig sein. Sie können einen Typ nicht entladen oder ändern. Um den Code für einen Typ zu ändern, müssen Sie den Namen ändern oder eine neue PowerShell-Sitzung starten. Andernfalls führt der Befehl zu einem Fehler.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Namespace
Gibt einen Namespace für den Typ an.
Wenn dieser Parameter nicht im Befehl enthalten ist, wird der Typ im Namespace Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes erstellt. Wenn der Parameter im Befehl mit einem leeren Zeichenfolgenwert oder einem Wert von $Null
enthalten ist, wird der Typ im globalen Namespace generiert.
Type: | String |
Aliases: | NS |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutputAssembly
Generiert eine DLL-Datei für die Assembly mit dem angegebenen Namen an dem Speicherort. Geben Sie einen optionalen Pfad und Dateinamen ein. Platzhalterzeichen sind zulässig. Standardmäßig Add-Type
generiert die Assembly nur im Arbeitsspeicher.
Type: | String |
Aliases: | OA |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-OutputType
Gibt den Ausgabetyp der Ausgabeassembly an. Standardmäßig wird kein Ausgabetyp angegeben. Dieser Parameter gilt nur, wenn eine Ausgabeassembly im Befehl angegeben wird. Weitere Informationen zu den Werten finden Sie unter OutputAssemblyType-Enumeration.
Die zulässigen Werte für diesen Parameter sind wie folgt:
ConsoleApplication
Library
WindowsApplication
Wichtig
Ab PowerShell 7.1 werden und WindowsApplication
nicht unterstützt, ConsoleApplication
und PowerShell löst einen Abbruchfehler aus, wenn beide als Werte für den OutputType-Parameter angegeben sind.
Type: | OutputAssemblyType |
Aliases: | OT |
Accepted values: | ConsoleApplication, Library, WindowsApplication |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Gibt ein System.Runtime-Objekt zurück, das die Typen darstellt, die hinzugefügt wurden. Standardmäßig generiert dieses Cmdlet keine Ausgabe.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
Gibt den Pfad zu Quellcodedateien oder Assembly-DLL-Dateien an, die die Typen enthalten.
Wenn Sie Quellcodedateien übermitteln, Add-Type
kompiliert den Code in den Dateien und erstellt eine In-Memory-Assembly der Typen. Die im Wert von Path angegebene Dateierweiterung bestimmt den Compiler, Add-Type
der verwendet.
Wenn Sie eine Assemblydatei übermitteln, Add-Type
übernimmt die Typen aus der Assembly. Um eine speicherinterne Assembly oder den globalen Assemblycache anzugeben, verwenden Sie den AssemblyName-Parameter.
Type: | String[] |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ReferencedAssemblies
Gibt die Assemblys an, von denen der Typ abhängig ist. Standardmäßig Add-Type
verweist auf System.dll
und System.Management.Automation.dll
. Auf die Assemblys, die Sie mithilfe dieses Parameters angeben, wird zusätzlich zu den Standardassemblys verwiesen.
Ab PowerShell 6 enthält ReferencedAssemblies keine .NET-Standardassemblys. Sie müssen einen bestimmten Verweis auf sie in den An diesen Parameter übergebenen Wert einschließen.
Sie können die Parameter CompilerOptions und ReferencedAssemblies nicht im gleichen Befehl verwenden.
Type: | String[] |
Aliases: | RA |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TypeDefinition
Gibt den Quellcode an, der die Typdefinitionen enthält. Geben Sie den Quellcode in einer Zeichenfolge oder einer here-Zeichenfolge ein, oder geben Sie eine Variable ein, die den Quellcode enthält. Weitere Informationen zu hier-Zeichenfolgen finden Sie unter about_Quoting_Rules.
Schließen Sie eine Namespacedeklaration in die Typdefinition ein. Wenn Sie die Namespacedeklaration weglassen, kann der Typ denselben Namen wie ein anderer Typ oder die Verknüpfung für einen anderen Typ aufweisen, was zu einer unbeabsichtigten Überschreibung führen kann. Wenn Sie beispielsweise einen Typ namens Exception definieren, schlagen Skripts, die Ausnahme als Verknüpfung für System.Exception verwenden, fehl.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UsingNamespace
Gibt andere Namespaces an, die für die Klasse erforderlich sind. Dies ähnelt dem C#-Schlüsselwort (keyword). Using
Standardmäßig Add-Type
verweist auf den Systemnamespace . Wenn der MemberDefinition-Parameter verwendet wird, Add-Type
verweist standardmäßig auch auf den System.Runtime.InteropServices-Namespace . Auf die Namespaces, die Sie mithilfe der UsingNamespace-Parameter hinzufügen, wird zusätzlich zu den standardmäßigen Namespaces verwiesen.
Type: | String[] |
Aliases: | Using |
Position: | Named |
Default value: | System namespace |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Eingaben
None
Sie können keine Objekte über die Pipeline an Add-Type
senden.
Ausgaben
None or System.Type
Wenn Sie den PassThru-Parameter verwenden, Add-Type
gibt ein System.Type-Objekt zurück, das den neuen Typ darstellt. Andernfalls generiert dieses Cmdlet keine Ausgabe.
Hinweise
Die Typen, die Sie hinzufügen, sind nur in der aktuellen Sitzung vorhanden. Um die Typen in allen Sitzungen zu verwenden, fügen Sie sie Ihrem PowerShell-Profil hinzu. Weitere Informationen zum Profil finden Sie unter about_Profiles.
Typnamen und Namespaces müssen innerhalb einer Sitzung eindeutig sein. Sie können einen Typ nicht entladen oder ändern. Wenn Sie den Code für einen Typ ändern müssen, müssen Sie den Namen ändern oder eine neue PowerShell-Sitzung starten. Andernfalls führt der Befehl zu einem Fehler.
In Windows PowerShell (Version 5.1 und niedriger) müssen Sie für alles verwendenAdd-Type
, was noch nicht geladen ist. Dies gilt am häufigsten für Assemblys, die sich im globalen Assemblycache (GAC) befinden.
In PowerShell 6 und höher gibt es kein GAC, sodass PowerShell seine eigenen Assemblys in $PSHome
installiert.
Diese Assemblys werden bei Anforderung automatisch geladen, sodass sie nicht zum Laden verwendet Add-Type
werden müssen. Die Verwendung Add-Type
ist jedoch weiterhin zulässig, damit Skripts implizit mit jeder Version von PowerShell kompatibel sind.
Assemblys im GAC können nach Typname und nicht nach Pfad geladen werden. Das Laden von Assemblys aus einem beliebigen Pfad erfordert Add-Type
, da diese Assemblys nicht automatisch geladen werden können.