Add-Type

Référence

Module:: Microsoft.PowerShell.Utility

Ajoute une classe Microsoft .NET à une session PowerShell.

Syntaxe

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

Description

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

Vous pouvez spécifier le type en spécifiant un assembly ou des fichiers de code source existants, ou 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éfinit et génère 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 Core.

Vous pouvez utiliser les paramètres de Add-Type pour 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.

À compter de PowerShell 7, Add-Type ne compile pas de type si un type portant le même nom existe déjà. En outre, Add-Type recherche des assemblys dans un dossier ref sous le dossier qui contient pwsh.dll.

Exemples

Exemple 1 : Ajouter un type .NET à une session

Cet exemple ajoute 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 variable $Source 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 de commande Add-Type 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 variable $Source.

La méthode statique Add 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 de commande New-Object instancie une instance de la classe BasicTest. Il enregistre le nouvel objet dans la variable $BasicTestObject.

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

Exemple 2 : Examiner un type ajouté

Cet exemple utilise l’applet de commande Get-Member pour examiner les objets que les applets de commande Add-Type et New-Object créées dans Exemple 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()

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

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

L’applet de commande Get-Member obtient les membres de l’objet stocké dans la variable $BasicTestObject. $BasicTestObject a été créé à l’aide de l’applet de commande New-Object avec la classe BasicTest. La sortie indique que la valeur de la variable $BasicTestObject 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 JsonSchema.NET.dll à la session active.

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

Set-Location utilise le paramètre Path pour spécifier la variable $PSHOME. La variable fait référence au répertoire d’installation PowerShell où se trouve le fichier DLL.

La variable $AccType stocke un objet créé avec l’applet de commande Add-Type. 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 dans 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 variable $Signature stocke la signature C# de la fonction ShowWindowAsync. Pour vous assurer que la méthode résultante est visible dans une session PowerShell, le mot clé public a été ajouté à la signature standard. Pour plus d’informations, consultez fonction ShowWindowAsync.

La variable $ShowWindowAsync stocke l’objet créé par le paramètrepassThru Add-Type. L’applet de commande Add-Type ajoute la fonction ShowWindowAsync à 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 variable $Signature. 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 méthode statique ShowWindowAsync 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 utilise l’applet de commande Get-Process avec la variable automatique $PID 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 valeur SW_MINIMIZE.

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

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

Paramètres

-AssemblyName

Spécifie le nom d’un assembly qui inclut les types. Add-Type accepte 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 d’application, Add-Type peut charger un assembly à partir de $PSHOME au lieu de la version dans le dossier actif. Pour plus d’informations, consultez '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 à l’origine de 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

-CompilerOptions

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.

Type:	String[]
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 de gérer les 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. La valeur acceptable pour ce paramètre est CSharp.

Type:	Language
Valeurs acceptées:	CSharp
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 qui contiennent les types. Contrairement à Path, la valeur du paramètre LiteralPath est utilisée exactement comme il est typé. Aucun caractère n’est interprété comme des caractères génériques. Si le chemin inclut des caractères d’échappement, placez-le entre 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, LP
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 de nouvelles propriétés ou méthodes pour 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 requis lors de 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

Par défaut, cette commande crée le type dans l’espace de noms Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes. Lorsque vous utilisez ce paramètre, le type est créé dans l’espace de noms spécifié. Si la valeur est une chaîne vide, le type est créé dans l’espace de noms 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 avec le nom spécifié à l’emplacement. 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. Si vous extrayez l’assembly dans un fichier, vous devez inclure le paramètre PassThru pour retourner le type à partir de l’assembly nouvellement créé.

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 lorsqu’un assembly de sortie est spécifié dans la commande. Pour plus d’informations sur les valeurs, consultez 'énumération OutputAssemblyType.

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

ConsoleApplication
Library
WindowsApplication

Important

À partir de PowerShell 7.1, les ConsoleApplication et les WindowsApplication ne sont pas pris en charge et PowerShell lève une erreur de fin si l’une ou l’autre est spécifiée comme valeurs pour le paramètre OutputType.

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

Renvoie un objet System.Runtime qui représente les types ajoutés. Par défaut, cette applet de commande ne génère aucune sortie. Utilisez ce paramètre si vous avez utilisé OutputAssembly pour créer un fichier DLL et que vous souhaitez retourner le type à partir de l’assembly nouvellement créé.

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 qui contiennent 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.

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

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 sur lesquels dépend le type. Par défaut, Add-Type référence System.dll et System.Management.Automation.dll. À compter de PowerShell 6, ReferencedAssemblies n’inclut pas les assemblys .NET par défaut. Vous devez inclure une référence spécifique à celles-ci dans la valeur passée à ce paramètre.

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 ici, 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 peut avoir le même nom qu’un autre type ou le raccourci d’un autre type, ce qui entraîne un remplacement involontaire. Par exemple, si vous définissez un type appelé Exception, les scripts qui utilisent exception comme raccourci pour System.Exception é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

-UsingNamespace

Spécifie d’autres espaces de noms requis 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.

Dans Windows PowerShell (version 5.1 et ci-dessous), vous devez utiliser Add-Type pour tout ce qui n’est pas déjà chargé. Le plus souvent, cela s’applique aux assemblys trouvés dans le Global Assembly Cache (GAC). Dans PowerShell 6 et versions ultérieures, il n’existe aucun GAC. PowerShell installe donc ses propres assemblys dans $PSHOME. Ces assemblys sont automatiquement chargés à la demande. Il n’est donc pas nécessaire d’utiliser Add-Type pour les charger. Toutefois, l’utilisation de Add-Type est toujours autorisée à autoriser les scripts à être implicitement compatibles avec n’importe quelle version de PowerShell.

Les assemblys du GAC peuvent être chargés par nom de type, plutôt que par chemin d’accès. Le chargement d’assemblys à partir d’un chemin arbitraire nécessite Add-Type, car ces assemblys ne peuvent pas être chargés automatiquement.

Partager via

Add-Type

Syntaxe

Description

Exemples

Exemple 1 : Ajouter un type .NET à une session

Exemple 2 : Examiner un type ajouté

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

Exemple 4 : Appeler des API Windows natives

Paramètres

-AssemblyName

-CompilerOptions

-IgnoreWarnings

-Language

-LiteralPath

-MemberDefinition

-Name

-Namespace

-OutputAssembly

-OutputType

-PassThru

-Path

-ReferencedAssemblies

-TypeDefinition

-UsingNamespace

Entrées

Sorties

Notes

Ressources supplémentaires

Partager via

Add-Type

Syntaxe

Description

Exemples

Exemple 1 : Ajouter un type .NET à une session

Exemple 2 : Examiner un type ajouté

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

Exemple 4 : Appeler des API Windows natives

Paramètres

-AssemblyName

-CompilerOptions

-IgnoreWarnings

-Language

-LiteralPath

-MemberDefinition

-Name

-Namespace

-OutputAssembly

-OutputType

-PassThru

-Path

-ReferencedAssemblies

-TypeDefinition

-UsingNamespace

Entrées

Sorties

Notes

Liens associés

Ressources supplémentaires