about_Experimental_Features

Artikel
12/04/2023

Die Unterstützung experimenteller Features in PowerShell stellt einen Mechanismus bereit, über den experimentelle Features und vorhandene stabile Features in PowerShell oder PowerShell-Modulen parallel genutzt werden können.

Ein experimentelles Feature ist ein Feature, dessen Design noch nicht finalisiert wurde. Das Feature wird bereitgestellt, damit die Benutzer es testen und Feedback dazu senden können. Sobald ein experimentelles Feature finalisiert wurde, werden die Designänderungen zu Breaking Changes. Experimentelle Features sind nicht für den Einsatz in der Produktion vorgesehen, da Auswirkungen auf die Lauffähigkeit möglich sind.

Experimentelle Features sind standardmäßig deaktiviert und müssen vom Benutzer oder Administrator des Systems explizit aktiviert werden.

Aktivierte experimentelle Features werden in der powershell.config.json Datei $PSHOME für alle Benutzer oder die benutzerspezifische Konfigurationsdatei für einen bestimmten Benutzer aufgeführt.

Hinweis

Experimentelle Features, die in der Benutzerkonfigurationsdatei aktiviert sind, haben Vorrang vor experimentellen Features, die in der Systemkonfigurationsdatei aufgeführt sind.

Das experimentelle Attribut

Verwenden Sie das Experimental Attribut, um Code als experimentell zu deklarieren.

Verwenden Sie die folgende Syntax, um das Attribut zu deklarieren, das Experimental den Namen des experimentellen Features und die Auszuführende Aktion angibt, wenn das experimentelle Feature aktiviert ist:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

Für Module muss die NameOfExperimentalFeature Form von <modulename>.<experimentname>. Der ExperimentAction Parameter muss angegeben werden, und die einzigen gültigen Werte sind:

Show bedeutet, dass dieses experimentelle Feature angezeigt wird, wenn das Feature aktiviert ist
Hide bedeutet, dieses experimentelle Feature auszublenden, wenn das Feature aktiviert ist

Deklarieren experimenteller Features in Modulen, die in C geschrieben wurden#

Modulautoren, die die Flags "Experimentelles Feature" verwenden möchten, können ein Cmdlet mithilfe des Experimental Attributs als experimentell deklarieren.

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

Deklarieren experimenteller Features in Modulen, die in PowerShell geschrieben wurden

In PowerShell geschriebenes Modul kann auch das Experimental Attribut verwenden, um experimentelle Cmdlets zu deklarieren:

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

Metadaten zu einem experimentellen Feature werden im Modulmanifest gespeichert. Verwenden Sie die PrivateData.PSData.ExperimentalFeatures Eigenschaft eines Modulmanifests, um die experimentellen Features aus dem Modul verfügbar zu machen. Die ExperimentalFeatures Eigenschaft ist ein Array von Hashtables, die den Namen und die Beschreibung des Features enthalten.

Zum Beispiel:

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

Sich gegenseitig ausschließende experimentelle Features

Es gibt Fälle, in denen ein experimentelles Feature nicht parallel zu einem vorhandenen Feature oder einem anderen experimentellen Feature vorhanden sein kann.

Beispielsweise können Sie über ein experimentelles Cmdlet verfügen, das ein vorhandenes Cmdlet außer Kraft setzt. Die beiden Versionen können nicht nebeneinander vorhanden sein. Mit ExperimentAction.Hide der Einstellung können nur eines der beiden Cmdlets gleichzeitig aktiviert werden.

In diesem Beispiel erstellen wir ein neues experimentelles Invoke-WebRequest Cmdlet. InvokeWebRequestCommand enthält die nicht experimentelle Implementierung. InvokeWebRequestCommandV2 enthält die experimentelle Version des Cmdlets.

Durch die Verwendung ExperimentAction.Hide können nur eine der beiden Features gleichzeitig aktiviert werden:

[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 { ... }

Wenn das MyWebCmdlets.PSWebCmdletV2 experimentelle Feature aktiviert ist, wird die vorhandene InvokeWebRequestCommand Implementierung ausgeblendet und bietet InvokeWebRequestCommandV2 die Implementierung von Invoke-WebRequest.

Auf diese Weise können Benutzer das neue Cmdlet ausprobieren und bei Bedarf auf die nicht experimentelle Version zurückgesetzt werden.

Experimentelle Parameter in Cmdlets

Das Experimental Attribut kann auch auf einzelne Parameter angewendet werden. Auf diese Weise können Sie einen experimentellen Satz von Parametern für ein vorhandenes Cmdlet anstelle eines völlig neuen Cmdlets erstellen.

Hier ist ein Beispiel in C#:

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

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

Hier ist ein anderes Beispiel in PowerShell-Skript:

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

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

Überprüfen, ob ein experimentelles Feature aktiviert ist

In Ihrem Code müssen Sie überprüfen, ob Ihr experimentelles Feature aktiviert ist, bevor Sie entsprechende Maßnahmen ergreifen. Sie können ermitteln, ob ein experimentelles Feature mithilfe der statischen IsEnabled() Methode für die System.Management.Automation.ExperimentalFeature Klasse aktiviert ist.

Hier ist ein Beispiel in C#:

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

Hier ist ein Beispiel für ein PowerShell-Skript:

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

Freigeben über