Add-Type

Menambahkan kelas Microsoft .NET ke sesi PowerShell.

Sintaks

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

Deskripsi

Add-Type Cmdlet memungkinkan Anda menentukan kelas Microsoft .NET Core di sesi PowerShell Anda. Anda kemudian dapat membuat instans objek, dengan menggunakan New-Object cmdlet , dan menggunakan objek sama seperti Anda akan menggunakan objek .NET Core apa pun. Jika Anda menambahkan Add-Type perintah ke profil PowerShell, kelas tersedia di semua sesi PowerShell.

Anda dapat menentukan jenis dengan menentukan file kode rakitan atau sumber yang ada, atau Anda dapat menentukan kode sumber sebaris atau disimpan dalam variabel. Anda bahkan hanya dapat menentukan metode dan Add-Type menentukan dan menghasilkan kelas . Di Windows, Anda dapat menggunakan fitur ini untuk melakukan panggilan Platform Invoke (P/Invoke) ke fungsi yang tidak terkelola di PowerShell. Jika Anda menentukan kode sumber, Add-Type kompilasi kode sumber yang ditentukan dan menghasilkan rakitan dalam memori yang berisi jenis .NET Core baru.

Anda dapat menggunakan parameter Add-Type untuk menentukan bahasa dan pengkompilasi alternatif, C# adalah default, opsi pengkompilasi, dependensi perakitan, namespace kelas, nama jenis, dan rakitan yang dihasilkan.

Dimulai di PowerShell 7, Add-Type tidak mengkompilasi jenis jika tipe dengan nama yang sama sudah ada. Selain itu, Add-Type cari rakitan dalam folder di ref bawah folder yang berisi pwsh.dll.

Contoh

Contoh 1: Menambahkan jenis .NET ke sesi

Contoh ini menambahkan kelas BasicTest ke sesi dengan menentukan kode sumber yang disimpan dalam variabel. Kelas BasicTest digunakan untuk menambahkan bilangan bulat, membuat objek, dan mengalikan bilangan bulat.

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

Variabel $Source menyimpan kode sumber untuk kelas . Jenis ini memiliki metode statis yang disebut Add dan metode non-statis yang disebut Multiply.

Add-Type Cmdlet menambahkan kelas ke sesi. Karena menggunakan kode sumber sebaris, perintah menggunakan parameter TypeDefinition untuk menentukan kode dalam $Source variabel.

Metode Add statis kelas BasicTest menggunakan karakter titik dua (::) untuk menentukan anggota statis kelas. Bilangan bulat ditambahkan dan jumlah ditampilkan.

New-Object Cmdlet membuat instans kelas BasicTest. Ini menyimpan objek baru dalam $BasicTestObject variabel .

$BasicTestObjectMultiply menggunakan metode . Bilangan bulat dikalikan dan produk ditampilkan.

Contoh 2: Memeriksa jenis yang ditambahkan

Contoh ini menggunakan Get-Member cmdlet untuk memeriksa objek yang Add-Type dibuat cmdlet dan New-Object dalam Contoh 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()

Get-Member Cmdlet mendapatkan jenis dan anggota kelas BasicTest yang Add-Type ditambahkan ke sesi. Perintah mengungkapkan Get-Member bahwa itu adalah objek System.RuntimeType , yang berasal dari kelas System.Object .

Parameter Get-MemberStatis mendapatkan properti statis dan metode kelas BasicTest . Output menunjukkan bahwa Add metode disertakan.

Get-Member Cmdlet mendapatkan anggota objek yang disimpan dalam $BasicTestObject variabel. $BasicTestObject dibuat dengan menggunakan New-Object cmdlet dengan kelas BasicTest . Output mengungkapkan bahwa nilai $BasicTestObject variabel adalah instans kelas BasicTest dan bahwa itu termasuk anggota yang disebut Multiply.

Contoh 3: Menambahkan jenis dari rakitan

Contoh ini menambahkan kelas dari assembly NJsonSchema.dll ke sesi saat ini.

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

Set-Location menggunakan parameter Jalur untuk menentukan $PSHOME variabel. Variabel mereferensikan direktori penginstalan PowerShell tempat file DLL berada.

Variabel $AccType menyimpan objek yang dibuat dengan Add-Type cmdlet . Add-Type menggunakan parameter AssemblyName untuk menentukan nama assembly. Karakter kartubebas tanda bintang (*) memungkinkan Anda mendapatkan rakitan yang benar bahkan ketika Anda tidak yakin dengan nama atau ejaannya. Parameter PassThru menghasilkan objek yang mewakili kelas yang ditambahkan ke sesi.

Contoh 4: Memanggil WINDOWS API asli

Contoh ini menunjukkan cara memanggil WINDOWS API asli di PowerShell. Add-Type menggunakan mekanisme Platform Invoke (P/Invoke) untuk memanggil fungsi User32.dll dari PowerShell. Contoh ini hanya berfungsi pada komputer yang menjalankan sistem operasi 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)

Variabel $Signature menyimpan tanda tangan C# dari ShowWindowAsync fungsi. Untuk memastikan bahwa metode yang dihasilkan terlihat dalam sesi PowerShell, public kata kunci ditambahkan ke tanda tangan standar. Untuk informasi selengkapnya, lihat Fungsi ShowWindowAsync.

Variabel $ShowWindowAsync menyimpan objek yang dibuat oleh Add-Type parameter PassThru. Add-Type Cmdlet menambahkan ShowWindowAsync fungsi ke sesi PowerShell sebagai metode statis. Perintah menggunakan parameter MemberDefinition untuk menentukan definisi metode yang disimpan dalam $Signature variabel. Perintah menggunakan parameter Nama dan Namespace untuk menentukan nama dan namespace untuk kelas. Parameter PassThru menghasilkan objek yang mewakili jenis.

Metode statis baru ShowWindowAsync digunakan dalam perintah untuk meminimalkan dan memulihkan konsol PowerShell. Metode ini mengambil dua parameter: handel jendela, dan bilangan bulat yang menentukan bagaimana jendela ditampilkan.

Untuk meminimalkan konsol Get-Process PowerShell, ShowWindowAsync gunakan cmdlet dengan $PID variabel otomatis untuk mendapatkan proses yang menghosting sesi PowerShell saat ini. Kemudian menggunakan properti MainWindowHandle dari proses saat ini dan nilai 2, yang mewakili SW_MINIMIZE nilai .

Untuk memulihkan jendela, ShowWindowAsync gunakan nilai 4 untuk posisi jendela, yang mewakili SW_RESTORE nilai .

Untuk memaksimalkan jendela, gunakan nilai 3 yang mewakili SW_MAXIMIZE.

Parameter

-AssemblyName

Menentukan nama rakitan yang menyertakan jenis. Add-Type mengambil jenis dari rakitan yang ditentukan. Parameter ini diperlukan saat Anda membuat jenis berdasarkan nama rakitan.

Masukkan nama lengkap atau sederhana, juga dikenal sebagai nama parsial, dari assembly. Karakter kartubebas diizinkan dalam nama rakitan. Jika Anda memasukkan nama sederhana atau parsial, Add-Type selesaikan ke nama lengkap, lalu gunakan nama lengkap untuk memuat rakitan.

Parameter ini tidak menerima jalur atau nama file. Untuk memasukkan jalur ke file pustaka tautan dinamis (DLL) rakitan, gunakan parameter Jalur .

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

-CompilerOptions

Menentukan opsi untuk pengkompilasi kode sumber. Opsi ini dikirim ke pengkompilasi tanpa revisi.

Parameter ini memungkinkan Anda mengarahkan pengkompilasi untuk menghasilkan file yang dapat dieksekusi, menyematkan sumber daya, atau mengatur opsi baris perintah, seperti /unsafe opsi .

Anda tidak dapat menggunakan parameter CompilerOptions dan ReferencedAssemblies dalam perintah yang sama.

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

-IgnoreWarnings

Mengabaikan peringatan kompilator. Gunakan parameter ini untuk mencegah Add-Type penanganan peringatan pengkompilasi sebagai kesalahan.

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

-Language

Menentukan bahasa yang digunakan dalam kode sumber. Nilai yang dapat diterima untuk parameter ini adalah

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

-LiteralPath

Menentukan jalur ke file kode sumber atau file DLL rakitan yang berisi jenis. Tidak seperti Path, nilai parameter LiteralPath digunakan persis seperti yang ditik. Tidak ada karakter yang ditafsirkan sebagai kartubebas. Jika jalur menyertakan karakter escape, sertakan dalam tanda kutip tunggal. Tanda kutip tunggal memberi tahu PowerShell untuk tidak menginterpretasikan karakter apa pun sebagai urutan escape.

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

-MemberDefinition

Menentukan properti atau metode baru untuk kelas . Add-Type menghasilkan kode templat yang diperlukan untuk mendukung properti atau metode.

Di Windows, Anda dapat menggunakan fitur ini untuk melakukan panggilan Platform Invoke (P/Invoke) ke fungsi yang tidak dikelola di PowerShell.

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

-Name

Menentukan nama kelas yang akan dibuat. Parameter ini diperlukan saat menghasilkan jenis dari definisi anggota.

Nama jenis dan namespace harus unik dalam sesi. Anda tidak dapat membongkar jenis atau mengubahnya. Untuk mengubah kode untuk jenis, Anda harus mengubah nama atau memulai sesi PowerShell baru. Jika tidak, perintah gagal.

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

-Namespace

Menentukan namespace untuk jenis tersebut.

Jika parameter ini tidak disertakan dalam perintah, jenis dibuat di namespace Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes . Jika parameter disertakan dalam perintah dengan nilai string kosong atau nilai $Null, jenisnya dihasilkan di namespace layanan global.

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

-OutputAssembly

Menghasilkan file DLL untuk rakitan dengan nama yang ditentukan di lokasi. Masukkan jalur opsional dan nama file. Karakter kartubebas diizinkan. Secara default, Add-Type menghasilkan assembly hanya dalam memori.

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

-OutputType

Menentukan jenis output dari rakitan output. Secara default, tidak ada jenis output yang ditentukan. Parameter ini hanya valid ketika rakitan output ditentukan dalam perintah . Untuk informasi selengkapnya tentang nilai, lihat OutputAssemblyType Enumeration.

Nilai yang dapat diterima untuk parameter ini adalah sebagai berikut:

  • ConsoleApplication
  • Library
  • WindowsApplication

Penting

Pada PowerShell 7.1, ConsoleApplication dan WindowsApplication tidak didukung dan PowerShell melemparkan kesalahan yang mengakhiri jika keduanya ditentukan sebagai nilai untuk parameter OutputType .

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

-PassThru

Mengembalikan objek System.Runtime yang mewakili jenis yang ditambahkan. Secara default, cmdlet ini tidak menghasilkan output apa pun.

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

-Path

Menentukan jalur ke file kode sumber atau file DLL rakitan yang berisi jenis.

Jika Anda mengirimkan file kode sumber, Add-Type kompilasi kode dalam file dan buat rakitan dalam memori jenis. Ekstensi file yang ditentukan dalam nilai Path menentukan pengkompilasi yang Add-Type menggunakan.

Jika Anda mengirimkan file assembly, Add-Type ambil jenis dari assembly. Untuk menentukan rakitan dalam memori atau cache rakitan global, gunakan parameter AssemblyName .

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

-ReferencedAssemblies

Menentukan rakitan yang jenisnya bergantung. Secara default, Add-Type referensi System.dll dan System.Management.Automation.dll. Rakitan yang Anda tentukan dengan menggunakan parameter ini direferensikan selain rakitan default.

Dimulai di PowerShell 6, ReferencedAssemblies tidak menyertakan rakitan .NET default. Anda harus menyertakan referensi tertentu ke referensi tersebut dalam nilai yang diteruskan ke parameter ini.

Anda tidak dapat menggunakan parameter CompilerOptions dan ReferencedAssemblies dalam perintah yang sama.

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

-TypeDefinition

Menentukan kode sumber yang berisi definisi jenis. Masukkan kode sumber dalam string atau here-string, atau masukkan variabel yang berisi kode sumber. Untuk informasi selengkapnya tentang here-strings, lihat about_Quoting_Rules.

Sertakan deklarasi namespace layanan dalam definisi jenis Anda. Jika Anda menghilangkan deklarasi namespace, jenis Anda mungkin memiliki nama yang sama dengan jenis lain atau pintasan untuk jenis lain, menyebabkan timpaan yang tidak disengaja. Misalnya, jika Anda menentukan jenis yang disebut Pengecualian, skrip yang menggunakan Pengecualian sebagai pintasan untuk System.Exception akan gagal.

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

-UsingNamespace

Menentukan namespace lain yang diperlukan untuk kelas . Ini mirip dengan kata kunci C#, Using.

Secara default, Add-Type mereferensikan namespace layanan Sistem . Saat parameter MemberDefinition digunakan, Add-Type juga mereferensikan namespace System.Runtime.InteropServices secara default. Namespace yang Anda tambahkan dengan menggunakan parameter UsingNamespace direferensikan selain namespace default.

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

Input

None

Anda tidak dapat mengirim objek ke bawah alur ke Add-Type.

Output

None or System.Type

Saat Anda menggunakan parameter PassThru , Add-Type mengembalikan objek System.Type yang mewakili jenis baru. Jika tidak, cmdlet ini tidak menghasilkan output apa pun.

Catatan

Jenis yang Anda tambahkan hanya ada di sesi saat ini. Untuk menggunakan jenis di semua sesi, tambahkan ke profil PowerShell Anda. Untuk informasi selengkapnya tentang profil, lihat about_Profiles.

Nama jenis dan namespace harus unik dalam sesi. Anda tidak dapat membongkar jenis atau mengubahnya. Jika Anda perlu mengubah kode untuk jenis, Anda harus mengubah nama atau memulai sesi PowerShell baru. Jika tidak, perintah gagal.

Dalam Windows PowerShell (versi 5.1 ke bawah), Anda perlu menggunakan Add-Type untuk apa pun yang belum dimuat. Paling umum, ini berlaku untuk rakitan yang ditemukan di Global Assembly Cache (GAC). Di PowerShell 6 dan yang lebih tinggi, tidak ada GAC, sehingga PowerShell menginstal rakitannya sendiri di $PSHome. Rakitan ini secara otomatis dimuat berdasarkan permintaan, sehingga tidak perlu digunakan Add-Type untuk memuatnya. Namun, penggunaan Add-Type masih diizinkan untuk memungkinkan skrip kompatibel secara implisit dengan versi PowerShell apa pun.

Rakitan dalam GAC dapat dimuat berdasarkan nama jenis, bukan berdasarkan jalur. Memuat rakitan dari jalur arbitrer memerlukan Add-Type, karena rakitan tersebut tidak dapat dimuat secara otomatis.