Udostępnij za pośrednictwem

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

Typ można określić, określając istniejący zestaw lub pliki kodu źródłowego albo określić kod źródłowy w tekście lub zapisany w zmiennej. Można nawet określić tylko metodę i Add-Type zdefiniować i wygenerować 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żna użyć parametrów Add-Type , aby określić język alternatywny i kompilator, C# jest domyślnym, opcjami kompilatora, zależnościami zestawów, przestrzenią nazw klas, nazwami typu i wynikowym zestawem.

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

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 Add-Type cmdlet dodaje klasę do sesji. Ponieważ używa wbudowanego kodu źródłowego, polecenie używa parametru TypeDefinition do określenia kodu w zmiennej $Source .

Statyczna Add metoda 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 New-Object cmdlet tworzy wystąpienie klasy BasicTest . Zapisuje nowy obiekt w zmiennej $BasicTestObject .

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

Przykład 2. Badanie dodanego typu

W tym przykładzie Get-Member użyto polecenia cmdlet do zbadania obiektów utworzonych Add-Type w przykładzie 1 przez polecenia cmdlet i New-Object .

[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 Get-Member cmdlet pobiera typ i elementy członkowskie klasy BasicTest dodanej Add-Type do sesji. Polecenie Get-Member ujawnia, ż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 Add jest uwzględniona metoda.

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

Przykład 3. Dodawanie typów z zestawu

Ten przykład dodaje klasy z zestawu do bieżącej NJsonSchema.dll 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ą Add-Type polecenia cmdlet . Add-Type używa parametru AssemblyName , aby określić nazwę zestawu. Symbol wieloznaczny gwiazdki (*) umożliwia uzyskanie poprawnego zestawu nawet wtedy, gdy nie masz pewności co do nazwy ani pisowni. Parametr PassThru generuje obiekty reprezentujące klasy dodane 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) w celu wywołania funkcji w User32.dll programie 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);
"@

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

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

Zmienna $ShowWindowAsync przechowuje obiekt utworzony przez Add-Type parametr PassThru. Polecenie Add-Type cmdlet dodaje ShowWindowAsync funkcję do sesji programu PowerShell jako metodę statyczną. Polecenie używa parametru MemberDefinition , aby określić definicję metody zapisaną w zmiennej $Signature . Polecenie używa parametrów Nazwa i Przestrzeń nazw , aby określić nazwę i przestrzeń nazw dla klasy. Parametr PassThru generuje obiekt reprezentujący typy.

Nowa ShowWindowAsync metoda statyczna 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, użyj Get-Process polecenia cmdlet z zmienną automatyczną$PID, ShowWindowAsync 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 , 2która reprezentuje SW_MINIMIZE wartość.

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

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

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, aby załadować zestaw.

Ten parametr nie akceptuje ścieżki ani nazwy pliku. Aby wprowadzić ścieżkę do pliku biblioteki dll (dynamic-link biblioteki zestawu), użyj parametru Path .

Type:String[]
Aliases:AN
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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 /unsafe opcja.

Nie można użyć parametrów CompilerOptions i ReferencedAssemblies w tym samym poleceniu.

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

-IgnoreWarnings

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

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

-Language

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

  • CSharp
Type:Language
Accepted values:CSharp
Position:Named
Default value:CSharp
Required:False
Accept pipeline input:False
Accept wildcard characters: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 ścieżki wartość 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 znaki pojedynczego cudzysłowu. Znaki pojedynczego cudzysłowu informują program PowerShell, aby nie interpretował żadnych znaków jako sekwencji ucieczki.

Type:String[]
Aliases:PSPath, LP
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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ć metodę Platform Invoke (P/Invoke) do funkcji niezarządzanych w programie PowerShell.

Type:String[]
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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 zakończy się niepowodzeniem.

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

-Namespace

Określa przestrzeń nazw dla typu.

Jeśli ten parametr nie jest uwzględniony w poleceniu, typ zostanie utworzony w przestrzeni nazw Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes . Jeśli parametr jest uwzględniony w poleceniu z pustą wartością ciągu lub wartością $Null, typ jest generowany w globalnej przestrzeni nazw.

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

-OutputAssembly

Generuje plik DLL 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.

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

-OutputType

Określa typ danych wyjściowych zestawu wyjściowego. Domyślnie nie określono typu danych wyjściowych. Ten parametr jest prawidłowy tylko wtedy, gdy zestaw wyjściowy jest określony w poleceniu. 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żne

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

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

Zwraca obiekt System.Runtime reprezentujący dodane typy. Domyślnie to polecenie cmdlet nie generuje żadnych danych wyjściowych.

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

-Path

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

Jeśli przesyłasz pliki 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.

Jeśli przesyłasz plik zestawu, Add-Type pobiera typy z zestawu. Aby określić zestaw w pamięci lub globalną pamięć podręczną zestawów, użyj parametru AssemblyName .

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

-ReferencedAssemblies

Określa zestawy, od których zależy typ. Domyślnie Add-Type odwołania System.dll i System.Management.Automation.dll. Zestawy, które określisz przy użyciu tego parametru, oprócz zestawów domyślnych, są przywołyne.

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.

Nie można użyć parametrów CompilerOptions i ReferencedAssemblies w tym samym poleceniu.

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

-TypeDefinition

Określa kod źródłowy zawierający definicje typów. Wprowadź kod źródłowy w ciągu lub w tym miejscu 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ątku jako skrótu system.Exception zakończy się niepowodzeniem.

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

-UsingNamespace

Określa inne przestrzenie nazw, które są wymagane dla klasy. Jest to podobne do słowa kluczowego C#, Using.

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

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

Dane wejściowe

None

Nie można wysyłać obiektów w dół potoku do Add-Type.

Dane wyjściowe

None or System.Type

W przypadku użycia parametru Add-TypePassThru zwraca obiekt System.Type reprezentujący nowy typ. W przeciwnym razie to polecenie cmdlet nie generuje żadnych danych wyjściowych.

Uwagi

Dodane typy istnieją tylko w bieżącej sesji. Aby używać 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 Windows PowerShell (wersja 5.1 i poniżej) należy użyć Add-Type polecenia dla wszystkich elementów, które nie zostały jeszcze załadowane. Najczęściej dotyczy to zestawów znalezionych w globalnej pamięci podręcznej zestawów (GAC). W programie PowerShell 6 i nowszym nie ma funkcji GAC, więc program PowerShell instaluje własne zestawy w programie $PSHome. Te zestawy są ładowane automatycznie na żądanie, więc nie ma potrzeby Add-Type ich ładowania. Jednak użycie Add-Type jest nadal dozwolone, aby zezwolić skryptom na niejawne zgodność z dowolną wersją programu PowerShell.

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