about_Experimental_Features

Artikel
12/04/2023

De ondersteuning voor experimentele functies in PowerShell biedt een mechanisme voor experimentele functies die naast bestaande stabiele functies in PowerShell- of PowerShell-modules kunnen worden gebruikt.

Een experimentele functie is een functie waarbij het ontwerp niet is voltooid. De functie is beschikbaar voor gebruikers om feedback te testen en te geven. Zodra een experimentele functie is voltooid, worden de ontwerpwijzigingen belangrijke wijzigingen. Experimentele functies zijn niet bedoeld voor gebruik in productie omdat de wijzigingen mogen worden onderbroken.

Experimentele functies zijn standaard uitgeschakeld en moeten expliciet worden ingeschakeld door de gebruiker of beheerder van het systeem.

Experimentele functies worden vermeld in het powershell.config.json bestand $PSHOME voor alle gebruikers of het gebruikersspecifieke configuratiebestand voor een specifieke gebruiker.

Notitie

Experimentele functies die zijn ingeschakeld in het gebruikersconfiguratiebestand hebben voorrang op experimentele functies die worden vermeld in het configuratiebestand van het systeem.

Het experimentele kenmerk

Gebruik het Experimental kenmerk om code als experimenteel te declareren.

Gebruik de volgende syntaxis om het Experimental kenmerk te declareren met de naam van de experimentele functie en de actie die moet worden ondernomen als de experimentele functie is ingeschakeld:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

Voor modules moet de NameOfExperimentalFeature vorm van <modulename>.<experimentname>. De ExperimentAction parameter moet worden opgegeven en de enige geldige waarden zijn:

Show betekent dat deze experimentele functie moet worden weergegeven als de functie is ingeschakeld
Hide betekent dat u deze experimentele functie wilt verbergen als de functie is ingeschakeld

Experimentele functies declareren in modules die zijn geschreven in C#

Auteurs van modules die de markeringen voor experimentele functies willen gebruiken, kunnen een cmdlet declareren als experimenteel met behulp van het Experimental kenmerk.

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

Experimentele functies declareren in modules die zijn geschreven in PowerShell

Module die is geschreven in PowerShell kan ook het Experimental kenmerk gebruiken om experimentele cmdlets te declareren:

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

Metagegevens over een experimentele functie worden bewaard in het modulemanifest. Gebruik de PrivateData.PSData.ExperimentalFeatures eigenschap van een modulemanifest om de experimentele functies van de module beschikbaar te maken. De ExperimentalFeatures eigenschap is een matrix van hashtabellen die de naam en beschrijving van de functie bevatten.

Voorbeeld:

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

Wederzijds exclusief experimentele functies

Er zijn gevallen waarin een experimentele functie niet naast een bestaande functie of een andere experimentele functie kan bestaan.

U kunt bijvoorbeeld een experimentele cmdlet hebben waarmee een bestaande cmdlet wordt overschreven. De twee versies kunnen niet naast elkaar bestaan. Met de ExperimentAction.Hide instelling kan slechts één van de twee cmdlets tegelijk worden ingeschakeld.

In dit voorbeeld maken we een nieuwe experimentele Invoke-WebRequest cmdlet. InvokeWebRequestCommand bevat de niet-experimentele implementatie. InvokeWebRequestCommandV2 bevat de experimentele versie van de cmdlet.

Met het gebruik van ExperimentAction.Hide kan slechts één van de twee functies tegelijk worden ingeschakeld:

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

Wanneer de MyWebCmdlets.PSWebCmdletV2 experimentele functie is ingeschakeld, wordt de bestaande InvokeWebRequestCommand implementatie verborgen en wordt de InvokeWebRequestCommandV2 implementatie van Invoke-WebRequest.

Hierdoor kunnen gebruikers de nieuwe cmdlet uitproberen en feedback geven en zo nodig terugkeren naar de niet-experimentele versie.

Experimentele parameters in cmdlets

Het Experimental kenmerk kan ook worden toegepast op afzonderlijke parameters. Hiermee kunt u een experimentele set parameters maken voor een bestaande cmdlet in plaats van een geheel nieuwe cmdlet.

Hier volgt een voorbeeld in C#:

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

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

Hier volgt een ander voorbeeld in PowerShell-script:

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

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

Controleren of een experimentele functie is ingeschakeld

In uw code moet u controleren of uw experimentele functie is ingeschakeld voordat u de juiste actie onderneemt. U kunt bepalen of een experimentele functie is ingeschakeld met behulp van de statische IsEnabled() methode in de System.Management.Automation.ExperimentalFeature klasse.

Hier volgt een voorbeeld in C#:

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

Hier volgt een voorbeeld in een PowerShell-script:

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