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 dikelola di PowerShell. Jika Anda menentukan kode sumber, Add-Type kompilasi kode sumber yang ditentukan dan hasilkan rakitan dalam memori yang berisi jenis .NET Core baru.

Anda dapat menggunakan parameter Add-Type untuk menentukan bahasa dan kompilator alternatif, C# adalah default, opsi pengkompilasi, dependensi rakitan, 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 ref folder di 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 tambahan

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 NJsonSchema.dll rakitan ke sesi saat ini.

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

Set-Locationmenggunakan 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-Typemenggunakan parameter AssemblyName untuk menentukan nama rakitan. Karakter kartubebas tanda bintang (*) memungkinkan Anda untuk 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 API Windows 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);
"@

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

Variabel $Signature menyimpan tanda tangan C# fungsi ShowWindowAsync . 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-Typeparameter PassThru . Add-Type Cmdlet menambahkan ShowWindowAsync fungsi ke sesi PowerShell sebagai metode statis. Perintah menggunakan parameter MemberDefinition untuk menentukan definisi metode yang $Signature disimpan dalam 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 menggunakan 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 rakitan. Karakter kartubebas diizinkan dalam nama rakitan. Jika Anda memasukkan nama sederhana atau parsial, Add-Type menyelesaikannya ke nama lengkap, lalu menggunakan nama lengkap untuk memuat rakitan.

Menggunakan parameter Path atau LiteralPath menjamin bahwa Anda memuat assembly yang ingin Anda muat. Saat Anda menggunakan parameter AssemblyName , PowerShell meminta .NET untuk menyelesaikan nama rakitan menggunakan proses resolusi rakitan .NET standar. Karena .NET mencari folder aplikasi terlebih dahulu, Add-Type mungkin memuat assembly dari $PSHOME bukan versi di folder saat ini. Untuk informasi selengkapnya, lihat Lokasi perakitan.

Jika .NET gagal mengatasi nama, PowerShell kemudian mencari di lokasi saat ini untuk menemukan rakitan. Saat Anda menggunakan kartubebas dalam parameter AssemblyName , proses resolusi rakitan .NET gagal menyebabkan PowerShell terlihat di lokasi saat ini.

Type:String[]
Aliases:AN
Position:Named
Default value:None
Required:True
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 .

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

-IgnoreWarnings

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

Type:SwitchParameter
Position:Named
Default value:False
Required: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
Required:False
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.

Menggunakan parameter Path atau LiteralPath menjamin bahwa Anda memuat assembly yang ingin Anda muat.

Type:String[]
Aliases:PSPath, LP
Position:Named
Default value:None
Required:True
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
Required:True
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
Required:True
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 global.

Type:String
Aliases:NS
Position:Named
Default value:None
Required:False
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 rakitan hanya dalam memori.

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

-OutputType

Menentukan jenis output 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 penghentian jika ditentukan sebagai nilai untuk parameter 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

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
Required: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 membuat rakitan dalam memori jenis. Ekstensi file yang ditentukan dalam nilai Jalur menentukan pengkompilasi yang Add-Type menggunakan.

Menggunakan parameter Path atau LiteralPath menjamin bahwa Anda memuat assembly yang ingin Anda muat.

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

-ReferencedAssemblies

Menentukan rakitan tempat jenis bergantung. Secara default, Add-Type referensi System.dll dan System.Management.Automation.dll. Rakitan yang Anda tentukan dengan menggunakan parameter ini dirujuk 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.

Type:String[]
Aliases:RA
Position:Named
Default value:None
Required:False
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-string, lihat about_Quoting_Rules.

Sertakan deklarasi namespace 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
Required:True
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 Layanan System.Runtime.InteropServices secara default. Namespace yang Anda tambahkan dengan menggunakan parameter UsingNamespace dirujuk selain namespace default.

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

Input

None

Anda tidak dapat menyalurkan objek ke cmdlet ini.

Output

None

Secara default, cmdlet ini tidak mengembalikan output.

Type

Saat Anda menggunakan parameter PassThru , cmdlet ini mengembalikan objek System.Type yang mewakili jenis baru.

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.

Di 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.