Add-Type

  • Riferimento
Modulo:
Microsoft.PowerShell.Utility

Aggiunge una classe Microsoft .NET a una sessione di PowerShell.

Sintassi

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

Descrizione

Il Add-Type cmdlet consente di definire una classe Microsoft .NET Core nella sessione di PowerShell. È quindi possibile creare un'istanza di oggetti usando il New-Object cmdlet e usare gli oggetti esattamente come si userebbe qualsiasi oggetto .NET Core. Se si aggiunge un Add-Type comando al profilo di PowerShell, la classe è disponibile in tutte le sessioni di PowerShell.

È possibile specificare il tipo specificando un assembly o file di codice sorgente esistenti o possibile specificare il codice sorgente inline o salvato in una variabile. È anche possibile specificare solo un metodo e Add-Type definire e generare la classe . In Windows è possibile usare questa funzionalità per effettuare chiamate Platform Invoke (P/Invoke) a funzioni non gestite in PowerShell. Se si specifica il codice sorgente, Add-Type compila il codice sorgente specificato e genera un assembly in memoria contenente i nuovi tipi .NET Core.

È possibile usare i parametri di Add-Type per specificare un linguaggio e un compilatore alternativi, C# è il valore predefinito, le opzioni del compilatore, le dipendenze dell'assembly, lo spazio dei nomi della classe, i nomi del tipo e l'assembly risultante.

A partire da PowerShell 7, Add-Type non compila un tipo se esiste già un tipo con lo stesso nome. Add-Type Cerca anche gli assembly in una ref cartella nella cartella che contiene pwsh.dll.

Esempio

Esempio 1: Aggiungere un tipo .NET a una sessione

In questo esempio viene aggiunta la classe BasicTest alla sessione specificando il codice sorgente archiviato in una variabile. La classe BasicTest viene usata per aggiungere numeri interi, creare un oggetto e moltiplicare i numeri interi.

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

La $Source variabile archivia il codice sorgente per la classe . Il tipo ha un metodo statico denominato Add e un metodo non statico denominato Multiply.

Il Add-Type cmdlet aggiunge la classe alla sessione. Poiché usa il codice sorgente inline, il comando usa il parametro TypeDefinition per specificare il codice nella $Source variabile.

Il Add metodo statico della classe BasicTest utilizza i caratteri a due punti (::) per specificare un membro statico della classe . I numeri interi vengono aggiunti e viene visualizzata la somma.

Il New-Object cmdlet crea un'istanza della classe BasicTest . Salva il nuovo oggetto nella $BasicTestObject variabile .

$BasicTestObject utilizza il Multiply metodo . I numeri interi vengono moltiplicati e il prodotto viene visualizzato.

Esempio 2: Esaminare un tipo aggiunto

In questo esempio viene usato il Get-Member cmdlet per esaminare gli oggetti creati dai cmdlet e New-Object nell'esempio Add-Type1.

[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()

Il Get-Member cmdlet ottiene il tipo e i membri della classe BasicTest che Add-Type ha aggiunto alla sessione. Il Get-Member comando rivela che si tratta di un oggetto System.RuntimeType derivato dalla classe System.Object .

Il Get-Memberparametro Static ottiene le proprietà statiche e i metodi della classe BasicTest . L'output mostra che il Add metodo è incluso.

Il Get-Member cmdlet ottiene i membri dell'oggetto archiviato nella $BasicTestObject variabile . $BasicTestObject è stato creato usando il New-Object cmdlet con la classe BasicTest . L'output rivela che il valore della variabile è un'istanza della $BasicTestObjectclasse BasicTest e che include un membro denominato Multiply.

Esempio 3: Aggiungere tipi da un assembly

In questo esempio vengono aggiunte le classi dall'assembly JsonSchema.NET.dll alla sessione corrente.

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

Set-Location usa il parametro Path per specificare la $PSHOME variabile. La variabile fa riferimento alla directory di installazione di PowerShell in cui si trova il file DLL.

La $AccType variabile archivia un oggetto creato con il Add-Type cmdlet . Add-Type utilizza il parametro AssemblyName per specificare il nome dell'assembly. Il carattere jolly asterisco (*) consente di ottenere l'assembly corretto anche quando non si è certi del nome o del relativo ortografia. Il parametro PassThru genera oggetti che rappresentano le classi aggiunte alla sessione.

Esempio 4: Chiamare API Di Windows native

In questo esempio viene illustrato come chiamare API Windows native in PowerShell. Add-Type usa il meccanismo Platform Invoke (P/Invoke) per chiamare una funzione in User32.dll da PowerShell. Questo esempio funziona solo nei computer che eseguono il sistema operativo 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)

La $Signature variabile archivia la firma C# della ShowWindowAsync funzione. Per assicurarsi che il metodo risultante sia visibile in una sessione di PowerShell, la public parola chiave è stata aggiunta alla firma standard. Per altre informazioni, vedere Funzione ShowWindowAsync .

La $ShowWindowAsync variabile archivia l'oggetto creato dal Add-Typeparametro PassThru . Il Add-Type cmdlet aggiunge la ShowWindowAsync funzione alla sessione di PowerShell come metodo statico. Il comando usa il parametro MemberDefinition per specificare la definizione del metodo salvata nella $Signature variabile . Il comando usa i parametri Name e Namespace per specificare un nome e uno spazio dei nomi per la classe . Il parametro PassThru genera un oggetto che rappresenta i tipi.

Il nuovo ShowWindowAsync metodo statico viene usato nei comandi per ridurre al minimo e ripristinare la console di PowerShell. Il metodo accetta due parametri: l'handle della finestra e un numero intero che specifica la modalità di visualizzazione della finestra.

Per ridurre al minimo la console di PowerShell, ShowWindowAsync usa il Get-Process cmdlet con la $PID variabile automatica per ottenere il processo che ospita la sessione di PowerShell corrente. Usa quindi la proprietà MainWindowHandle del processo corrente e il valore 2, che rappresenta il SW_MINIMIZE valore .

Per ripristinare la finestra, ShowWindowAsync usa un valore di 4 per la posizione della finestra, che rappresenta il SW_RESTORE valore .

Per ingrandire la finestra, usare il valore di 3 che rappresenta SW_MAXIMIZE.

Parametri

-AssemblyName

Specifica il nome di un assembly che include i tipi. Add-Type accetta i tipi dall'assembly specificato. Questo parametro è obbligatorio quando si creano tipi in base a un nome di assembly.

Immettere il nome completo o semplice, noto anche come nome parziale, di un assembly. Nel nome dell'assembly sono consentiti i caratteri jolly. Se si immette un nome semplice o parziale, Add-Type lo risolve nel nome completo e quindi usa il nome completo per caricare l'assembly.

L'uso dei parametri Path o LiteralPath garantisce il caricamento dell'assembly da caricare. Quando si usa il parametro AssemblyName , PowerShell chiede a .NET di risolvere il nome dell'assembly usando il processo di risoluzione dell'assembly .NET standard. Poiché .NET cerca prima la cartella dell'applicazione, Add-Type potrebbe caricare un assembly da $PSHOME anziché dalla versione nella cartella corrente. Per altre informazioni, vedere Percorso assembly.

Se .NET non riesce a risolvere il nome, PowerShell cerca nel percorso corrente per trovare l'assembly. Quando si usano caratteri jolly nel parametro AssemblyName , il processo di risoluzione dell'assembly .NET non riesce causando l'individuazione di PowerShell nella posizione corrente.

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

-CompilerOptions

Specifica le opzioni per il compilatore del codice sorgente. Queste opzioni vengono inviate al compilatore senza revisione.

Questo parametro consente di indirizzare il compilatore a generare un file eseguibile, incorporare risorse o impostare le opzioni della riga di comando, ad esempio l'opzione /unsafe .

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

-IgnoreWarnings

Ignora gli avvisi del compilatore. Usare questo parametro per impedire Add-Type la gestione degli avvisi del compilatore come errori.

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

-Language

Specifica il linguaggio usato nel codice sorgente. Il valore accettabile per questo parametro è CSharp.

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

-LiteralPath

Specifica il percorso dei file del codice sorgente o dei file DLL dell'assembly che contengono i tipi. A differenza di Path, il valore del parametro LiteralPath viene usato esattamente come viene digitato. Nessun carattere viene interpretato come carattere jolly. Se il percorso include caratteri di escape, racchiuderlo tra virgolette singole. Le virgolette singole indicano a PowerShell di non interpretare alcun carattere come sequenze di escape.

L'uso dei parametri Path o LiteralPath garantisce il caricamento dell'assembly da caricare.

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

-MemberDefinition

Specifica nuovi metodi o proprietà per la classe. Add-Type genera il codice del modello necessario per supportare le proprietà o i metodi.

In Windows è possibile usare questa funzionalità per effettuare chiamate Platform Invoke (P/Invoke) a funzioni non gestite in PowerShell.

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

-Name

Specifica il nome della classe da creare. Questo parametro è obbligatorio durante la generazione di un tipo da una definizione del membro.

Il nome del tipo e lo spazio dei nomi devono essere univoci all'interno di una sessione. Non è possibile scaricare un tipo o modificarlo. Per modificare il codice per un tipo, è necessario modificare il nome o avviare una nuova sessione di PowerShell. In caso contrario, il comando non riesce.

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

-Namespace

Specifica uno spazio dei nomi per il tipo.

Se questo parametro non è incluso nel comando, il tipo viene creato nello spazio dei nomi Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes . Se il parametro è incluso nel comando con un valore stringa vuoto o un valore di $Null, il tipo viene generato nello spazio dei nomi globale.

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

-OutputAssembly

Genera un file DLL per l'assembly con il nome specificato nel percorso. Immettere un percorso e un nome file facoltativi. I caratteri jolly sono consentiti. Per impostazione predefinita, Add-Type genera l'assembly solo in memoria.

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

-OutputType

Specifica il tipo di output dell'assembly di output. Per impostazione predefinita, non è specificato alcun tipo di output. Questo parametro è valido solo quando viene specificato un assembly di output nel comando. Per altre informazioni sui valori, vedere Enumerazione OutputAssemblyType.

I valori accettabili per questo parametro sono i seguenti:

  • ConsoleApplication
  • Library
  • WindowsApplication

Importante

A partire da PowerShell 7.1 ConsoleApplication e non sono supportati e WindowsApplication PowerShell genera un errore irreversibile se uno dei due è specificato come valori per il parametro 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

Restituisce un oggetto System.Runtime che rappresenta i tipi aggiunti. Per impostazione predefinita, questo cmdlet non genera alcun output.

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

-Path

Specifica il percorso dei file del codice sorgente o dei file DLL dell'assembly che contengono i tipi.

Se si inviano file di codice sorgente, Add-Type compila il codice nei file e crea un assembly in memoria dei tipi. L'estensione di file specificata nel valore di Path determina il compilatore che Add-Type usa.

L'uso dei parametri Path o LiteralPath garantisce il caricamento dell'assembly da caricare.

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

-ReferencedAssemblies

Specifica gli assembly da cui dipende il tipo. Per impostazione predefinita, Add-Type fa System.dll riferimento a e System.Management.Automation.dll. Oltre agli assembly predefiniti, il comando fa riferimento anche agli assembly specificati mediante questo parametro.

A partire da PowerShell 6, ReferencedAssemblies non include gli assembly .NET predefiniti. È necessario includere un riferimento specifico al parametro nel valore passato a questo parametro.

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

-TypeDefinition

Specifica il codice sorgente che contiene le definizioni dei tipi. Immettere il codice sorgente in una stringa o una stringa di tipo here o immettere una variabile che contiene il codice sorgente. Per altre informazioni sulle stringhe qui, vedere about_Quoting_Rules.

Includere una dichiarazione dello spazio dei nomi nella definizione del tipo. Se si omette la dichiarazione dello spazio dei nomi, il tipo potrebbe avere lo stesso nome di un altro tipo o il collegamento per un altro tipo, causando una sovrascrittura accidentale. Ad esempio, se si definisce un tipo denominato Eccezione, gli script che usano Exception come collegamento per System.Exception avranno esito negativo.

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

-UsingNamespace

Specifica altri spazi dei nomi necessari per la classe. Questo è molto simile alla parola chiave C#, Using.

Per impostazione predefinita, Add-Type fa riferimento allo spazio dei nomi System . Quando viene usato il parametro MemberDefinition , Add-Type fa riferimento allo spazio dei nomi System.Runtime.InteropServices per impostazione predefinita. Gli spazi dei nomi aggiunti tramite il parametro UsingNamespace fanno riferimento oltre agli spazi dei nomi predefiniti.

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

Input

None

Non è possibile inviare tramite pipe oggetti a questo cmdlet.

Output

None

Per impostazione predefinita, questo cmdlet non restituisce alcun output.

Type

Quando si utilizza il parametro PassThru , questo cmdlet restituisce un oggetto System.Type che rappresenta il nuovo tipo.

Note

I tipi aggiunti esistono solo nella sessione corrente. Per usare i tipi in tutte le sessioni, aggiungerli al profilo di PowerShell. Per altre informazioni sul profilo, vedere about_Profiles.

I nomi dei tipi e gli spazi dei nomi devono essere univoci all'interno di una sessione. Non è possibile scaricare un tipo o modificarlo. Se è necessario modificare il codice per un tipo, è necessario modificare il nome o avviare una nuova sessione di PowerShell. In caso contrario, il comando non riesce.

In Windows PowerShell (versione 5.1 e successive), è necessario usare Add-Type per qualsiasi elemento non già caricato. In genere, questo vale per gli assembly presenti nella Global Assembly Cache (GAC). In PowerShell 6 e versioni successive non esiste alcuna gac, quindi PowerShell installa i propri assembly in $PSHOME. Questi assembly vengono caricati automaticamente su richiesta, quindi non è necessario usarli Add-Type per caricarli. Tuttavia, l'uso Add-Type di è ancora consentito per consentire la compatibilità implicita degli script con qualsiasi versione di PowerShell.

Gli assembly nella GAC possono essere caricati in base al nome del tipo, anziché in base al percorso. Il caricamento di assembly da un percorso arbitrario richiede Add-Type, perché tali assembly non possono essere caricati automaticamente.