about_Experimental_Features

Article
12/04/2023

La prise en charge des Fonctionnalités expérimentales dans PowerShell fournit un mécanisme permettant aux fonctionnalités expérimentales de coexister avec les fonctionnalités stables existantes dans PowerShell ou les modules PowerShell.

Une fonctionnalité expérimentale est une fonctionnalité dans laquelle la conception n’est pas finalisée. Les utilisateurs peuvent tester la fonctionnalité et fournir des commentaires. Lorsqu’une fonctionnalité expérimentale est finalisée, les modifications apportées à la conception deviennent des changements cassants. Les fonctionnalités expérimentales ne sont pas destinées à être utilisées en production, car les changements peuvent être cassants.

Les fonctionnalités expérimentales sont désactivées par défaut et doivent être explicitement activées par l’utilisateur ou l’administrateur du système.

Les fonctionnalités expérimentales activées sont répertoriées dans le powershell.config.json fichier $PSHOME pour tous les utilisateurs ou le fichier de configuration spécifique à l’utilisateur pour un utilisateur spécifique.

Remarque

Les fonctionnalités expérimentales activées dans le fichier de configuration utilisateur sont prioritaires sur les fonctionnalités expérimentales répertoriées dans le fichier de configuration système.

Attribut expérimental

Utilisez l’attribut Experimental pour déclarer du code comme expérimental.

Utilisez la syntaxe suivante pour déclarer l’attribut Experimental fournissant le nom de la fonctionnalité expérimentale et l’action à entreprendre si la fonctionnalité expérimentale est activée :

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

Pour les modules, le NameOfExperimentalFeature doit suivre la forme de <modulename>.<experimentname>. Le ExperimentAction paramètre doit être spécifié et les seules valeurs valides sont les suivantes :

Show signifie afficher cette fonctionnalité expérimentale si la fonctionnalité est activée
Hide signifie masquer cette fonctionnalité expérimentale si la fonctionnalité est activée

Déclaration des fonctionnalités expérimentales dans les modules écrits en C#

Les auteurs de modules qui souhaitent utiliser les indicateurs de fonctionnalité expérimentale peuvent déclarer une applet de commande comme expérimentale à l’aide de l’attribut Experimental .

[Experimental("MyWebCmdlets.PSWebCmdletV2", ExperimentAction.Show)]
[Cmdlet(Verbs.Invoke, "WebRequest")]
public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... }

Déclaration des fonctionnalités expérimentales dans les modules écrits dans PowerShell

Le module écrit dans PowerShell peut également utiliser l’attribut Experimental pour déclarer des applets de commande expérimentales :

function Enable-SSHRemoting {
    [Experimental("MyRemoting.PSSSHRemoting", "Show")]
    [CmdletBinding()]
    param()
    ...
}

Les métadonnées relatives à une fonctionnalité expérimentale sont conservées dans le manifeste du module. Utilisez la PrivateData.PSData.ExperimentalFeatures propriété d’un manifeste de module pour exposer les fonctionnalités expérimentales du module. La ExperimentalFeatures propriété est un tableau de tables de hachage contenant le nom et la description de la fonctionnalité.

Par exemple :

PrivateData = @{
  PSData = @{
    ExperimentalFeatures = @(
      @{
          Name = "PSWebCmdletV2"
          Description = "Rewrite the web cmdlets for better performance"
      },
      @{
          Name = "PSRestCmdletV2"
          Description = "Rewrite the REST API cmdlets for better performance"
      }
    )
  }
}

Fonctionnalités expérimentales mutuellement exclusives

Il existe des cas où une fonctionnalité expérimentale ne peut pas coexister côte à côte avec une fonctionnalité existante ou une autre fonctionnalité expérimentale.

Par exemple, vous pouvez avoir une applet de commande expérimentale qui remplace une applet de commande existante. Les deux versions ne peuvent pas coexister côte à côte. Le ExperimentAction.Hide paramètre autorise uniquement l’activation de l’une des deux applets de commande à la fois.

Dans cet exemple, nous créons une applet de commande expérimentale Invoke-WebRequest . InvokeWebRequestCommand contient l’implémentation non expérimentale. InvokeWebRequestCommandV2 contient la version expérimentale de l’applet de commande.

L’utilisation de ExperimentAction.Hide ne permet qu’à l’activation de l’une des deux fonctionnalités à la fois :

[Experimental("MyWebCmdlets.PSWebCmdletV2", ExperimentAction.Show)]
[Cmdlet(Verbs.Invoke, "WebRequest")]
public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... }

[Experimental("MyWebCmdlets.PSWebCmdletV2", ExperimentAction.Hide)]
[Cmdlet(Verbs.Invoke, "WebRequest")]
public class InvokeWebRequestCommand : WebCmdletBase { ... }

Lorsque la MyWebCmdlets.PSWebCmdletV2 fonctionnalité expérimentale est activée, l’implémentation existante InvokeWebRequestCommand est masquée et InvokeWebRequestCommandV2 fournit l’implémentation de Invoke-WebRequest.

Cela permet aux utilisateurs d’essayer la nouvelle applet de commande et de fournir des commentaires, puis de revenir à la version non expérimentale si nécessaire.

Paramètres expérimentaux dans les applets de commande

L’attribut Experimental peut également être appliqué à des paramètres individuels. Cela vous permet de créer un ensemble expérimental de paramètres pour une applet de commande existante plutôt qu’une nouvelle applet de commande.

Voici un exemple en C# :

[Experimental("MyModule.PSNewAddTypeCompilation", ExperimentAction.Show)]
[Parameter(ParameterSet = "NewCompilation")]
public CompilationParameters CompileParameters { ... }

[Experimental("MyModule.PSNewAddTypeCompilation", ExperimentAction.Hide)]
[Parameter()]
public CodeDom CodeDom { ... }

Voici un exemple différent dans le script PowerShell :

param(
    [Experimental("MyModule.PSNewFeature", "Show")]
    [string] $NewName,

    [Experimental("MyModule.PSNewFeature", "Hide")]
    [string] $OldName
)

Vérification si une fonctionnalité expérimentale est activée

Dans votre code, vous devez vérifier si votre fonctionnalité expérimentale est activée avant d’entreprendre une action appropriée. Vous pouvez déterminer si une fonctionnalité expérimentale est activée à l’aide de la méthode statique IsEnabled() sur la System.Management.Automation.ExperimentalFeature classe.

Voici un exemple en C# :

if (ExperimentalFeature.IsEnabled("MyModule.MyExperimentalFeature"))
{
   // code specific to the experimental feature
}

Voici un exemple dans le script PowerShell :

if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature"))
{
  # code specific to the experimental feature
}

Partager via