Partager via


Add-Type

Ajoute une classe Microsoft .NET à une session PowerShell.

Syntaxe

Add-Type
   [-CodeDomProvider <CodeDomProvider>]
   [-CompilerParameters <CompilerParameters>]
   [-TypeDefinition] <String>
   [-Language <Language>]
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [<CommonParameters>]
Add-Type
   [-CodeDomProvider <CodeDomProvider>]
   [-CompilerParameters <CompilerParameters>]
   [-Name] <String>
   [-MemberDefinition] <String[]>
   [-Namespace <String>]
   [-UsingNamespace <String[]>]
   [-Language <Language>]
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [<CommonParameters>]
Add-Type
   [-CompilerParameters <CompilerParameters>]
   [-Path] <String[]>
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [<CommonParameters>]
Add-Type
   [-CompilerParameters <CompilerParameters>]
   -LiteralPath <String[]>
   [-ReferencedAssemblies <String[]>]
   [-OutputAssembly <String>]
   [-OutputType <OutputAssemblyType>]
   [-PassThru]
   [-IgnoreWarnings]
   [<CommonParameters>]
Add-Type
   -AssemblyName <String[]>
   [-PassThru]
   [-IgnoreWarnings]
   [<CommonParameters>]

Description

L’applet Add-Type de commande vous permet de définir une classe Microsoft .NET Framework dans votre session PowerShell. Vous pouvez ensuite instancier des objets, à l’aide de l’applet New-Object de commande et utiliser les objets comme vous le feriez pour n’importe quel objet .NET Framework. Si vous ajoutez une Add-Type commande à votre profil PowerShell, la classe est disponible dans toutes les sessions PowerShell.

Vous pouvez spécifier le type en désignant un assembly existant ou des fichiers de code source. Par ailleurs, vous pouvez spécifier le code source inline ou enregistré dans une variable. Vous ne pouvez même spécifier qu’une méthode et Add-Type définir et générer la classe. Sur Windows, vous pouvez utiliser cette fonctionnalité pour passer des appels d’appel de plateforme (P/Invoke) à des fonctions non managées dans PowerShell. Si vous spécifiez du code source, Add-Type compile le code source spécifié et génère un assembly en mémoire qui contient les nouveaux types .NET Framework.

Vous pouvez utiliser les paramètres de Add-Type spécifier un autre langage et compilateur, C# est la valeur par défaut, les options du compilateur, les dépendances d’assembly, l’espace de noms de classe, les noms du type et l’assembly résultant.

Exemples

Exemple 1 : Ajouter un type .NET à une session

Cet exemple montre comment ajouter la classe BasicTest à la session en spécifiant le code source stocké dans une variable. La classe BasicTest est utilisée pour ajouter des entiers, créer un objet et multiplier des entiers.

$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 variable stocke le code source de la classe. Le type a une méthode statique appelée Add et une méthode non statique appelée Multiply.

L’applet Add-Type de commande ajoute la classe à la session. Étant donné qu’elle utilise le code source inline, la commande utilise le paramètre TypeDefinition pour spécifier le code dans la $Source variable.

La Add méthode statique de la classe BasicTest utilise les caractères deux-points (::) pour spécifier un membre statique de la classe. Les entiers sont ajoutés et la somme s’affiche.

L’applet New-Object de commande instancie une instance de la classe BasicTest . Il enregistre le nouvel objet dans la $BasicTestObject variable.

$BasicTestObject utilise la Multiply méthode. Les entiers sont multipliés et le produit s’affiche.

Exemple 2 : Examiner un type ajouté

Cet exemple utilise l’applet Get-Member de commande pour examiner les objets créés dans l’exemple 1 et New-Object les Add-Type applets de commande créées.

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

L’applet Get-Member de commande obtient le type et les membres de la classe BasicTest ajoutées Add-Type à la session. La Get-Member commande indique qu’il s’agit d’un objet System.RuntimeType , dérivé de la classe System.Object .

Le Get-Member paramètre static obtient les propriétés et méthodes statiques de la classe BasicTest . La sortie indique que la Add méthode est incluse.

L’applet Get-Member de commande obtient les membres de l’objet stocké dans la $BasicTestObject variable. $BasicTestObject a été créé à l’aide de l’applet New-Object de commande avec la classe BasicTest . La sortie indique que la valeur de la $BasicTestObject variable est une instance de la classe BasicTest et qu’elle inclut un membre appelé Multiply.

Exemple 3 : Ajouter des types à partir d’un assembly

Cet exemple montre comment ajouter les classes de l’assembly Accessibility.dll à la session active.

$AccType = Add-Type -AssemblyName "accessib*" -PassThru

La $AccType variable stocke un objet créé avec l’applet de Add-Type commande. Add-Type utilise le paramètre AssemblyName pour spécifier le nom de l’assembly. Le caractère générique astérisque (*) vous permet d’obtenir l’assembly correct même si vous n’êtes pas sûr du nom ou de son orthographe. Le paramètre PassThru génère des objets qui représentent les classes ajoutées à la session.

Exemple 4 : Appeler des API Windows natives

Cet exemple montre comment appeler des API Windows natives dans PowerShell. Add-Type utilise le mécanisme d’appel de plateforme (P/Invoke) pour appeler une fonction à User32.dll partir de PowerShell. Cet exemple fonctionne uniquement sur les ordinateurs exécutant le système d’exploitation 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 variable stocke la signature C# de la ShowWindowAsync fonction. Pour vous assurer que la méthode résultante est visible dans une session PowerShell, le public mot clé a été ajouté à la signature standard. Pour plus d’informations, consultez la fonction ShowWindowAsync .

La $ShowWindowAsync variable stocke l’objet créé par le Add-Type paramètre PassThru . L’applet Add-Type de commande ajoute la ShowWindowAsync fonction à la session PowerShell en tant que méthode statique. La commande utilise le paramètre MemberDefinition pour spécifier la définition de méthode enregistrée dans la $Signature variable. La commande utilise les paramètres Name et Namespace pour spécifier un nom et un espace de noms pour la classe. Le paramètre PassThru génère un objet qui représente les types.

La nouvelle ShowWindowAsync méthode statique est utilisée dans les commandes pour réduire et restaurer la console PowerShell. La méthode prend deux paramètres : le handle de fenêtre et un entier qui spécifie la façon dont la fenêtre est affichée.

Pour réduire la console PowerShell, ShowWindowAsync utilisez l’applet Get-Process de commande avec la $PID variable automatique pour obtenir le processus qui héberge la session PowerShell actuelle. Ensuite, il utilise la propriété MainWindowHandle du processus actuel et une valeur de 2, qui représente la SW_MINIMIZE valeur.

Pour restaurer la fenêtre, ShowWindowAsync utilise une valeur de la position de 4 la fenêtre, qui représente la SW_RESTORE valeur.

Pour optimiser la fenêtre, utilisez la valeur de 3 ce qui représente SW_MAXIMIZE.

Exemple 5 : Ajouter un type à partir d’un fichier Visual Basic

Cet exemple utilise l’applet Add-Type de commande pour ajouter la classe VBFromFile définie dans le Hello.vb fichier à la session active. Le texte du fichier est affiché dans la sortie de Hello.vb commande.

Add-Type -Path "C:\PS-Test\Hello.vb"
[VBFromFile]::SayHello(", World")

# From Hello.vb

Public Class VBFromFile
  Public Shared Function SayHello(sourceName As String) As String
    Dim myValue As String = "Hello"
    return myValue + sourceName
  End Function
End Class

Hello, World

Add-Typeutilise le paramètre Path pour spécifier le fichier source et Hello.vbajoute le type défini dans le fichier. La SayHello fonction est appelée comme méthode statique de la classe VBFromFile .

Exemple 6 : Ajouter une classe avec JScript.NET

Cet exemple utilise JScript.NET pour créer une classe, FRectangle, dans votre session PowerShell.

Add-Type @'
 class FRectangle {
   var Length : double;
   var Height : double;
   function Perimeter() : double {
       return (Length + Height) * 2; }
   function Area() : double {
       return Length * Height;  } }
'@ -Language JScript

$rect = [FRectangle]::new()
$rect

Length Height
------ ------
     0      0

Exemple 7 : Ajouter un compilateur F#

Cet exemple montre comment utiliser l’applet Add-Type de commande pour ajouter un compilateur de code F# à votre session PowerShell. Pour exécuter cet exemple dans PowerShell, vous devez avoir installé celui-ci FSharp.Compiler.CodeDom.dll avec la langue F#.

Add-Type -Path "FSharp.Compiler.CodeDom.dll"
$Provider = New-Object Microsoft.FSharp.Compiler.CodeDom.FSharpCodeProvider
$FSharpCode = @"
let rec loop n =if n <= 0 then () else beginprint_endline (string_of_int n);loop (n-1)end
"@
$FSharpType = Add-Type -TypeDefinition $FSharpCode -CodeDomProvider $Provider -PassThru |
   Where-Object { $_.IsPublic }
$FSharpType::loop(4)

4
3
2
1

Add-Type utilise le paramètre Path pour spécifier un assembly et obtient les types dans l’assembly. New-Object crée une instance du fournisseur de code F# et enregistre le résultat dans la $Provider variable. La $FSharpCode variable enregistre le code F# qui définit la méthode Loop .

La $FSharpType variable stocke les résultats de l’applet Add-Type de commande qui enregistre les types publics définis dans $FSharpCode. Le paramètre TypeDefinition spécifie le code source qui définit les types. Le paramètre CodeDomProvider spécifie le compilateur de code source. Le paramètre PassThru dirige Add-Type pour renvoyer un objet Runtime qui représente les types. Les objets sont envoyés au pipeline vers l’applet Where-Object de commande, qui retourne uniquement les types publics. L’applet Where-Object de commande est utilisée, car le fournisseur F# génère des types non publics pour prendre en charge le type public résultant.

La méthode loop est appelée en tant que méthode statique du type stocké dans la $FSharpType variable.

Paramètres

-AssemblyName

Spécifie le nom d'un assembly qui inclut les types. Add-Type prend les types de l’assembly spécifié. Ce paramètre est requis lorsque vous créez des types en fonction d’un nom d’assembly.

Entrez le nom complet ou simple, également appelé nom partiel, d’un assembly. Les caractères génériques sont autorisés dans le nom de l'assembly. Si vous entrez un nom simple ou partiel, Add-Type le résout en nom complet, puis utilise le nom complet pour charger l’assembly.

L’utilisation des paramètres Path ou LiteralPath garantit que vous chargez l’assembly que vous souhaitez charger. Lorsque vous utilisez le paramètre AssemblyName , PowerShell demande à .NET de résoudre le nom de l’assembly à l’aide du processus de résolution d’assembly .NET standard. Étant donné que .NET recherche d’abord le dossier de l’application, Add-Type peut charger un assembly à partir de $PSHOME la version dans le dossier actif. Pour plus d’informations, consultez l’emplacement de l’assembly.

Si .NET ne parvient pas à résoudre le nom, PowerShell recherche l’assembly à l’emplacement actuel. Lorsque vous utilisez des caractères génériques dans le paramètre AssemblyName , le processus de résolution d’assembly .NET échoue, ce qui entraîne l’apparence de PowerShell à l’emplacement actuel.

Type:String[]
Alias:AN
Position:Named
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:True

-CodeDomProvider

Spécifie un générateur de code ou un compilateur. Add-Type utilise le compilateur spécifié pour compiler le code source. La valeur par défaut est le compilateur C#. Utilisez ce paramètre si vous utilisez une langue qui ne peut pas être spécifiée à l’aide du paramètre Language . CodeDomProvider que vous spécifiez doit être en mesure de générer des assemblys à partir du code source.

Type:CodeDomProvider
Alias:Provider
Position:Named
Valeur par défaut:C# compiler
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-CompilerParameters

Spécifie les options du compilateur de code source. Ces options sont envoyées au compilateur sans révision.

Ce paramètre vous permet de diriger le compilateur pour générer un fichier exécutable, incorporer des ressources ou définir des options de ligne de commande, telles que l’option /unsafe . Ce paramètre implémente la classe CompilerParameters , System.CodeDom.Compiler.CompilerParameters.

Vous ne pouvez pas utiliser les paramètres CompilerParameters et ReferencedAssemblies dans la même commande.

Type:CompilerParameters
Alias:CP
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-IgnoreWarnings

Ignore les avertissements du compilateur. Utilisez ce paramètre pour empêcher Add-Type la gestion des avertissements du compilateur en tant qu’erreurs.

Type:SwitchParameter
Position:Named
Valeur par défaut:False
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Language

Spécifie la langue utilisée dans le code source. L’applet Add-Type de commande utilise la valeur de ce paramètre pour sélectionner le CodeDomProvider approprié. CSharp est la valeur par défaut. Les valeurs acceptables pour ce paramètre sont les suivantes :

  • CSharp
  • CSharpVersion2
  • CSharpVersion3
  • JScript
  • VisualBasic
Type:Language
Valeurs acceptées:CSharp, CSharpVersion2, CSharpVersion3, JScript, VisualBasic
Position:Named
Valeur par défaut:CSharp
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-LiteralPath

Spécifie le chemin d'accès aux fichiers de code source ou aux fichiers DLL d'assembly contenant les types. Contrairement à Path, la valeur du paramètre LiteralPath est utilisée exactement comme elle est typée. Aucun caractère n’est interprété en tant que caractère générique. Si le chemin d’accès inclut des caractères d’échappement, mettez-le entre des guillemets simples. Les guillemets simples indiquent à PowerShell de ne pas interpréter de caractères comme séquences d’échappement.

L’utilisation des paramètres Path ou LiteralPath garantit que vous chargez l’assembly que vous souhaitez charger.

Type:String[]
Alias:PSPath
Position:Named
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-MemberDefinition

Spécifie les nouvelles propriétés ou méthodes de la classe. Add-Type génère le code de modèle requis pour prendre en charge les propriétés ou méthodes.

Sur Windows, vous pouvez utiliser cette fonctionnalité pour passer des appels d’appel de plateforme (P/Invoke) à des fonctions non managées dans PowerShell.

Type:String[]
Position:1
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Name

Spécifie le nom de la classe à créer. Ce paramètre est obligatoire durant la génération d'un type à partir d'une définition de membre.

Le nom de type et l'espace de noms doivent être uniques au sein d'une session. Vous ne pouvez pas décharger un type ou le modifier. Pour modifier le code d’un type, vous devez modifier le nom ou démarrer une nouvelle session PowerShell. Sinon, la commande échoue.

Type:String
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Namespace

Spécifie un espace de noms pour le type.

Si ce paramètre n’est pas inclus dans la commande, le type est créé dans l’espace de noms Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes . Si le paramètre est inclus dans la commande avec une valeur de chaîne vide ou une valeur de , le type est généré dans l’espace de $Nullnoms global.

Type:String
Alias:NS
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-OutputAssembly

Génère un fichier DLL pour l'assembly ayant le nom spécifié à l'emplacement approprié. Entrez un chemin d’accès et un nom de fichier facultatifs. Les caractères génériques sont autorisés. Par défaut, Add-Type génère l’assembly uniquement en mémoire.

Type:String
Alias:OA
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:True

-OutputType

Spécifie le type de sortie de l'assembly de sortie. Par défaut, aucun type de sortie n'est spécifié. Ce paramètre est valide uniquement quand un assembly de sortie est spécifié dans la commande. Pour plus d’informations sur les valeurs, consultez l’énumération OutputAssemblyType.

Les valeurs acceptables pour ce paramètre sont les suivantes :

  • ConsoleApplication
  • Library
  • WindowsApplication
Type:OutputAssemblyType
Alias:OT
Valeurs acceptées:ConsoleApplication, Library, WindowsApplication
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-PassThru

Retourne un objet System.Runtime qui représente les types ajoutés. Par défaut, cette applet de commande ne génère aucune sortie.

Type:SwitchParameter
Position:Named
Valeur par défaut:False
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Path

Spécifie le chemin d'accès aux fichiers de code source ou aux fichiers DLL d'assembly contenant les types.

Si vous envoyez des fichiers de code source, Add-Type compile le code dans les fichiers et crée un assembly en mémoire des types. L’extension de fichier spécifiée dans la valeur de Path détermine le compilateur qui Add-Type utilise.

Si vous envoyez un fichier d’assembly, Add-Type prend les types de l’assembly. Pour spécifier un assembly en mémoire ou le global assembly cache, utilisez le paramètre AssemblyName .

Type:String[]
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ReferencedAssemblies

Spécifie les assemblys dont dépend le type. Par défaut, Add-Type références System.dll et System.Management.Automation.dll. Les assemblys que vous spécifiez à l'aide de ce paramètre sont référencés en plus des assemblys par défaut.

Vous ne pouvez pas utiliser les paramètres CompilerParameters et ReferencedAssemblies dans la même commande.

Type:String[]
Alias:RA
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-TypeDefinition

Spécifie le code source qui contient les définitions de type. Entrez le code source dans une chaîne ou une chaîne here-string, ou entrez une variable qui contient le code source. Pour plus d’informations sur les chaînes ici, consultez about_Quoting_Rules.

Incluez une déclaration d'espace de noms dans votre définition de type. Si vous omettez la déclaration d'espace de noms, votre type risque d'avoir le même nom qu'un autre type ou que le raccourci d'un autre type, ce qui entraînera un remplacement involontaire. Par exemple, si vous définissez un type appelé Exception, les scripts qui utilisent Exception comme raccourci pour System.Exception échouent.

Type:String
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-UsingNamespace

Spécifie les autres espaces de noms nécessaires pour la classe. C’est beaucoup comme le mot clé C#, Using.

Par défaut, Add-Type fait référence à l’espace de noms System . Lorsque le paramètre MemberDefinition est utilisé, Add-Type fait également référence à l’espace de noms System.Runtime.InteropServices par défaut. Les espaces de noms que vous ajoutez à l’aide du paramètre UsingNamespace sont référencés en plus des espaces de noms par défaut.

Type:String[]
Alias:Using
Position:Named
Valeur par défaut:System namespace
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

Entrées

None

Vous ne pouvez pas diriger les objets vers cette applet de commande.

Sorties

None

Par défaut, cette applet de commande ne retourne aucune sortie.

Type

Lorsque vous utilisez le paramètre PassThru , cette applet de commande retourne un objet System.Type représentant le nouveau type.

Notes

Les types que vous ajoutez existent uniquement dans la session active. Pour utiliser les types dans toutes les sessions, ajoutez-les à votre profil PowerShell. Pour plus d’informations sur le profil, consultez about_Profiles.

Les noms de type et les espaces de noms doivent être uniques au sein d’une session. Vous ne pouvez pas décharger un type ou le modifier. Si vous devez modifier le code d’un type, vous devez modifier le nom ou démarrer une nouvelle session PowerShell. Sinon, la commande échoue.

La classe CodeDomProvider pour certaines langues, telles que IronPython et J#, ne génère pas de sortie. Par conséquent, les types écrits dans ces langues ne peuvent pas être utilisés avec Add-Type.

Cette applet de commande est basée sur la classe Microsoft .NET Framework CodeDomProvider.