Add-Type

Odwołanie

Moduł:: Microsoft.PowerShell.Utility

Dodaje klasę Microsoft .NET do sesji programu PowerShell.

Składnia

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

Opis

Polecenie cmdlet Add-Type umożliwia zdefiniowanie klasy Microsoft .NET Core w sesji programu PowerShell. Następnie można utworzyć wystąpienia obiektów przy użyciu polecenia cmdlet New-Object i użyć obiektów tak samo, jak w przypadku dowolnego obiektu platformy .NET Core. Jeśli dodasz polecenie Add-Type do profilu programu PowerShell, klasa będzie dostępna we wszystkich sesjach programu PowerShell.

Typ można określić, określając istniejący zestaw lub pliki kodu źródłowego, lub możesz określić kod źródłowy w tekście lub zapisany w zmiennej. Można nawet określić tylko metodę i Add-Type definiuje i generuje klasę. W systemie Windows możesz użyć tej funkcji, aby wywołać wywołania Wywołania platformy (P/Invoke) do funkcji niezarządzanych w programie PowerShell. Jeśli określisz kod źródłowy, Add-Type skompiluje określony kod źródłowy i wygeneruje zestaw w pamięci zawierający nowe typy platformy .NET Core.

Możesz użyć parametrów Add-Type, aby określić język alternatywny i kompilator, C# jest domyślnym, opcjami kompilatora, zależnościami zestawu, przestrzenią nazw klas, nazwami typu i wynikowym zestawem.

Począwszy od programu PowerShell 7, Add-Type nie kompiluje typu, jeśli typ o tej samej nazwie już istnieje. Ponadto Add-Type szuka zestawów w folderze ref w folderze zawierającym pwsh.dll.

Przykłady

Przykład 1: Dodawanie typu platformy .NET do sesji

W tym przykładzie do sesji dodano klasę BasicTest, określając kod źródłowy przechowywany w zmiennej. Klasa BasicTest służy do dodawania liczb całkowitych, tworzenia obiektu i mnożenia liczb całkowitych.

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

Zmienna $Source przechowuje kod źródłowy dla klasy. Typ ma metodę statyczną o nazwie Add i metodę niestacyjną o nazwie Multiply.

Polecenie cmdlet Add-Type dodaje klasę do sesji. Ponieważ używa wbudowanego kodu źródłowego, polecenie używa parametru TypeDefinition, aby określić kod w zmiennej $Source.

Metoda statyczna Add klasy BasicTest używa znaków dwukropka (::), aby określić statyczną składową klasy. Liczby całkowite są dodawane, a suma jest wyświetlana.

Polecenie cmdlet New-Object tworzy wystąpienie klasy BasicTest. Zapisuje nowy obiekt w zmiennej $BasicTestObject.

$BasicTestObject używa metody Multiply. Liczby całkowite są mnożone i wyświetlany jest produkt.

Przykład 2. Badanie dodanego typu

W tym przykładzie użyto polecenia cmdlet Get-Member do zbadania obiektów, które Add-Type i New-Object polecenia cmdlet utworzone w Przykład 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()

Polecenie cmdlet Get-Member pobiera typ i elementy członkowskie klasy BasicTest, która Add-Type dodana do sesji. Polecenie Get-Member pokazuje, że jest to obiekt System.RuntimeType, który pochodzi z klasy System.Object.

Parametr Get-MemberStatic pobiera właściwości statyczne i metody klasy BasicTest. Dane wyjściowe pokazują, że dołączono metodę Add.

Polecenie cmdlet Get-Member pobiera elementy członkowskie obiektu przechowywanego w zmiennej $BasicTestObject. $BasicTestObject został utworzony przy użyciu polecenia cmdlet New-Object z klasą BasicTest. Dane wyjściowe pokazują, że wartość zmiennej $BasicTestObject jest wystąpieniem klasy BasicTest i że zawiera składową o nazwie Multiply.

Przykład 3. Dodawanie typów z zestawu

Ten przykład dodaje klasy z zestawu JsonSchema.NET.dll do bieżącej sesji.

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

Set-Location używa parametru path, aby określić zmienną $PSHOME. Zmienna odwołuje się do katalogu instalacyjnego programu PowerShell, w którym znajduje się plik DLL.

Zmienna $AccType przechowuje obiekt utworzony za pomocą polecenia cmdlet Add-Type. Add-Type używa parametru AssemblyName w celu określenia nazwy zestawu. Gwiazdka (*) symbol wieloznaczny umożliwia uzyskanie poprawnego zestawu nawet wtedy, gdy nie masz pewności co do nazwy ani jego pisowni. Parametr PassThru generuje obiekty reprezentujące klasy dodawane do sesji.

Przykład 4. Wywoływanie natywnych interfejsów API systemu Windows

W tym przykładzie pokazano, jak wywoływać natywne interfejsy API systemu Windows w programie PowerShell. Add-Type używa mechanizmu Wywołanie platformy (P/Invoke) do wywoływania funkcji w User32.dll z poziomu programu PowerShell. Ten przykład działa tylko na komputerach z systemem operacyjnym Windows.

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

$addTypeSplat = @{
    MemberDefinition = $Signature
    Name = "Win32ShowWindowAsync"
    Namespace = 'Win32Functions'
    PassThru = $true
}
$ShowWindowAsync = Add-Type @addTypeSplat

# Minimize the PowerShell console

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

# Restore the PowerShell console

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

Zmienna $Signature przechowuje sygnaturę języka C# funkcji ShowWindowAsync. Aby upewnić się, że wynikowa metoda jest widoczna w sesji programu PowerShell, słowo kluczowe public zostało dodane do sygnatury standardowej. Aby uzyskać więcej informacji, zobacz funkcja ShowWindowAsync.

Zmienna $ShowWindowAsync przechowuje obiekt utworzony przez parametr Add-TypePassThru. Polecenie cmdlet Add-Type dodaje funkcję ShowWindowAsync do sesji programu PowerShell jako metodę statyczną. Polecenie używa parametru MemberDefinition w celu określenia definicji metody zapisanej w zmiennej $Signature. Polecenie używa parametrów Name i Namespace w celu określenia nazwy i przestrzeni nazw dla klasy. Parametr PassThru generuje obiekt reprezentujący typy.

Nowa metoda statyczna ShowWindowAsync jest używana w poleceniach, aby zminimalizować i przywrócić konsolę programu PowerShell. Metoda przyjmuje dwa parametry: uchwyt okna i liczbę całkowitą określającą sposób wyświetlania okna.

Aby zminimalizować konsolę programu PowerShell, ShowWindowAsync używa polecenia cmdlet Get-Process z zmienną automatyczną $PID, aby uzyskać proces hostujący bieżącą sesję programu PowerShell. Następnie używa właściwości MainWindowHandle bieżącego procesu i wartości 2, która reprezentuje wartość SW_MINIMIZE.

Aby przywrócić okno, ShowWindowAsync używa wartości 4 dla pozycji okna, która reprezentuje wartość SW_RESTORE.

Aby zmaksymalizować okno, użyj wartości 3 reprezentującej SW_MAXIMIZE.

Parametry

-AssemblyName

Określa nazwę zestawu, który zawiera typy. Add-Type pobiera typy z określonego zestawu. Ten parametr jest wymagany podczas tworzenia typów na podstawie nazwy zestawu.

Wprowadź pełną lub prostą nazwę, znaną również jako nazwa częściowa zestawu. Symbole wieloznaczne są dozwolone w nazwie zestawu. Jeśli wprowadzisz prostą lub częściową nazwę, Add-Type rozpozna ją jako pełną nazwę, a następnie użyjesz pełnej nazwy do załadowania zestawu.

Użycie parametrów Path lub LiteralPath gwarantuje załadowanie zestawu, który ma być załadowany. Jeśli używasz parametru AssemblyName, program PowerShell prosi platformę .NET o rozpoznawanie nazwy zestawu przy użyciu standardowego procesu rozpoznawania zestawów .NET. Ponieważ platforma .NET najpierw wyszukuje folder aplikacji, Add-Type może załadować zestaw z $PSHOME zamiast wersji w bieżącym folderze. Aby uzyskać więcej informacji, zobacz lokalizacja zestawu.

Jeśli program .NET nie rozpozna nazwy, program PowerShell wyszuka w bieżącej lokalizacji, aby znaleźć zestaw. Jeśli używasz symboli wieloznacznych w parametrze AssemblyName, proces rozpoznawania zestawu platformy .NET kończy się niepowodzeniem, powodując, że program PowerShell będzie szukać w bieżącej lokalizacji.

Typ:	String[]
Aliasy:	AN
Position:	Named
Domyślna wartość:	None
Wymagane:	True
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	True

-CompilerOptions

Określa opcje kompilatora kodu źródłowego. Te opcje są wysyłane do kompilatora bez poprawki.

Ten parametr umożliwia kierowanie kompilatora do generowania pliku wykonywalnego, osadzania zasobów lub ustawiania opcji wiersza polecenia, takich jak opcja /unsafe.

Typ:	String[]
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-IgnoreWarnings

Ignoruje ostrzeżenia kompilatora. Użyj tego parametru, aby zapobiec Add-Type obsługi ostrzeżeń kompilatora jako błędów.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-Language

Określa język używany w kodzie źródłowym. Akceptowalną wartością tego parametru jest CSharp.

Typ:	Language
Dopuszczalne wartości:	CSharp
Position:	Named
Domyślna wartość:	CSharp
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-LiteralPath

Określa ścieżkę do plików kodu źródłowego lub plików DLL zestawu, które zawierają typy. W przeciwieństwie do Pathwartość parametru LiteralPath jest używana dokładnie tak, jak jest typowana. Znaki nie są interpretowane jako symbole wieloznaczne. Jeśli ścieżka zawiera znaki ucieczki, należy ująć ją w pojedynczy cudzysłów. Pojedyncze znaki cudzysłowu informują program PowerShell, aby nie interpretował żadnych znaków jako sekwencji ucieczki.

Użycie parametrów Path lub LiteralPath gwarantuje załadowanie zestawu, który ma być załadowany.

Typ:	String[]
Aliasy:	PSPath, LP
Position:	Named
Domyślna wartość:	None
Wymagane:	True
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-MemberDefinition

Określa nowe właściwości lub metody dla klasy. Add-Type generuje kod szablonu wymagany do obsługi właściwości lub metod.

W systemie Windows możesz użyć tej funkcji, aby wywołać wywołania Wywołania platformy (P/Invoke) do funkcji niezarządzanych w programie PowerShell.

Typ:	String[]
Position:	1
Domyślna wartość:	None
Wymagane:	True
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-Name

Określa nazwę klasy do utworzenia. Ten parametr jest wymagany podczas generowania typu z definicji elementu członkowskiego.

Nazwa typu i przestrzeń nazw muszą być unikatowe w ramach sesji. Nie można zwolnić typu ani go zmienić. Aby zmienić kod typu, musisz zmienić nazwę lub uruchomić nową sesję programu PowerShell. W przeciwnym razie polecenie kończy się niepowodzeniem.

Typ:	String
Position:	0
Domyślna wartość:	None
Wymagane:	True
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-Namespace

Domyślnie to polecenie tworzy typ w Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes przestrzeni nazw. W przypadku użycia tego parametru typ jest tworzony w określonej przestrzeni nazw. Jeśli wartość jest pustym ciągiem, typ jest tworzony w globalnej przestrzeni nazw.

Typ:	String
Aliasy:	NS
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-OutputAssembly

Generuje plik DLL dla zestawu o określonej nazwie w lokalizacji. Wprowadź opcjonalną ścieżkę i nazwę pliku. Dozwolone są symbole wieloznaczne. Domyślnie Add-Type generuje zestaw tylko w pamięci. Jeśli zestaw zostanie zwrócony do pliku, należy dołączyć parametr PassThru, aby zwrócić typ z nowo utworzonego zestawu.

Typ:	String
Aliasy:	OA
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	True

-OutputType

Określa typ danych wyjściowych zestawu wyjściowego. Domyślnie nie określono żadnego typu danych wyjściowych. Ten parametr jest prawidłowy tylko wtedy, gdy w poleceniu określono zestaw wyjściowy. Aby uzyskać więcej informacji na temat wartości, zobacz OutputAssemblyType, wyliczenie.

Dopuszczalne wartości tego parametru są następujące:

ConsoleApplication
Library
WindowsApplication

Ważny

Od programu PowerShell 7.1 ConsoleApplication i WindowsApplication nie są obsługiwane, a program PowerShell zgłasza błąd zakończenia, jeśli zostanie określony jako wartości parametru OutputType.

Typ:	OutputAssemblyType
Aliasy:	OT
Dopuszczalne wartości:	ConsoleApplication, Library, WindowsApplication
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-PassThru

Zwraca obiekt System.Runtime reprezentujący dodane typy. Domyślnie to polecenie cmdlet nie generuje żadnych danych wyjściowych. Użyj tego parametru, jeśli użyto OutputAssembly do utworzenia pliku DLL i chcesz zwrócić typ z nowo utworzonego zestawu.

Typ:	SwitchParameter
Position:	Named
Domyślna wartość:	False
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-Path

Określa ścieżkę do plików kodu źródłowego lub plików DLL zestawu, które zawierają typy.

W przypadku przesyłania plików kodu źródłowego Add-Type kompiluje kod w plikach i tworzy zestaw typów w pamięci. Rozszerzenie pliku określone w wartości Path określa kompilator, który Add-Type używa.

Użycie parametrów Path lub LiteralPath gwarantuje załadowanie zestawu, który ma być załadowany.

Typ:	String[]
Position:	0
Domyślna wartość:	None
Wymagane:	True
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-ReferencedAssemblies

Określa zestawy, od których zależy typ. Domyślnie Add-Type odwołuje się do System.dll i System.Management.Automation.dll. Począwszy od programu PowerShell 6, ReferencedAssemblies nie zawiera domyślnych zestawów platformy .NET. Musisz dołączyć do nich określone odwołanie do wartości przekazanej do tego parametru.

Typ:	String[]
Aliasy:	RA
Position:	Named
Domyślna wartość:	None
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-TypeDefinition

Określa kod źródłowy zawierający definicje typów. Wprowadź kod źródłowy w ciągu lub tutaj-ciągu lub wprowadź zmienną zawierającą kod źródłowy. Aby uzyskać więcej informacji na temat ciągów tutaj, zobacz about_Quoting_Rules.

Dołącz deklarację przestrzeni nazw do definicji typu. Jeśli pominięto deklarację przestrzeni nazw, typ może mieć taką samą nazwę jak inny typ lub skrót dla innego typu, powodując niezamierzone zastąpienie. Jeśli na przykład zdefiniujesz typ o nazwie Wyjątek, skrypty używające Wyjątki jako skrót dla System.Exception zakończy się niepowodzeniem.

Typ:	String
Position:	0
Domyślna wartość:	None
Wymagane:	True
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-UsingNamespace

Określa inne przestrzenie nazw, które są wymagane dla klasy. Jest to podobnie jak słowo kluczowe języka C#, Using.

Domyślnie Add-Type odwołuje się do przestrzeni nazw System. Gdy jest używany parametr MemberDefinition, Add-Type również odwołuje się do przestrzeni nazw System.Runtime.InteropServices. Przestrzenie nazw dodawane przy użyciu parametru UsingNamespace są przywoływane oprócz domyślnych przestrzeni nazw.

Typ:	String[]
Aliasy:	Using
Position:	Named
Domyślna wartość:	System namespace
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

Dane wejściowe

None

Nie można potokować obiektów do tego polecenia cmdlet.

Dane wyjściowe

None

Domyślnie to polecenie cmdlet nie zwraca żadnych danych wyjściowych.

Type

Jeśli używasz parametru PassThru, to polecenie cmdlet zwraca obiekt System.Type reprezentujący nowy typ.

Uwagi

Dodane typy istnieją tylko w bieżącej sesji. Aby użyć typów we wszystkich sesjach, dodaj je do profilu programu PowerShell. Aby uzyskać więcej informacji na temat profilu, zobacz about_Profiles.

Nazwy typów i przestrzenie nazw muszą być unikatowe w ramach sesji. Nie można zwolnić typu ani go zmienić. Jeśli musisz zmienić kod typu, musisz zmienić nazwę lub uruchomić nową sesję programu PowerShell. W przeciwnym razie polecenie kończy się niepowodzeniem.

W programie Windows PowerShell (wersja 5.1 i poniżej) należy użyć Add-Type dla wszystkich elementów, które nie zostały jeszcze załadowane. Najczęściej dotyczy to zestawów znajdujących się w globalnej pamięci podręcznej zestawów (GAC). W programie PowerShell 6 lub nowszym nie ma kontroli GAC, więc program PowerShell instaluje własne zestawy w $PSHOME. Te zestawy są ładowane automatycznie na żądanie, więc nie ma potrzeby ich ładowania przy użyciu Add-Type. Jednak używanie Add-Type jest nadal dozwolone, aby zezwolić skryptom na niejawne zgodność z dowolną wersją programu PowerShell.

Zestawy w GAC mogą być ładowane według nazwy typu, a nie ścieżki. Ładowanie zestawów z dowolnej ścieżki wymaga Add-Type, ponieważ tych zestawów nie można załadować automatycznie.

Udostępnij za pośrednictwem

Add-Type

Składnia

Opis

Przykłady

Przykład 1: Dodawanie typu platformy .NET do sesji

Przykład 2. Badanie dodanego typu

Przykład 3. Dodawanie typów z zestawu

Przykład 4. Wywoływanie natywnych interfejsów API systemu Windows

Parametry

-AssemblyName

-CompilerOptions

-IgnoreWarnings

-Language

-LiteralPath

-MemberDefinition

-Name

-Namespace

-OutputAssembly

-OutputType

-PassThru

-Path

-ReferencedAssemblies

-TypeDefinition

-UsingNamespace

Dane wejściowe

Dane wyjściowe

Uwagi

Dodatkowe zasoby

Udostępnij za pośrednictwem

Add-Type

Składnia

Opis

Przykłady

Przykład 1: Dodawanie typu platformy .NET do sesji

Przykład 2. Badanie dodanego typu

Przykład 3. Dodawanie typów z zestawu

Przykład 4. Wywoływanie natywnych interfejsów API systemu Windows

Parametry

-AssemblyName

-CompilerOptions

-IgnoreWarnings

-Language

-LiteralPath

-MemberDefinition

-Name

-Namespace

-OutputAssembly

-OutputType

-PassThru

-Path

-ReferencedAssemblies

-TypeDefinition

-UsingNamespace

Dane wejściowe

Dane wyjściowe

Uwagi

Linki powiązane

Dodatkowe zasoby