about_Experimental_Features
De ondersteuning voor experimentele functies in PowerShell biedt een mechanisme waarmee experimentele functies naast bestaande stabiele functies in PowerShell- of PowerShell-modules kunnen worden gebruikt.
Een experimentele functie is een functie waarbij het ontwerp nog niet is voltooid. De functie is beschikbaar voor gebruikers om te testen en feedback te geven. Zodra een experimentele functie is voltooid, worden de ontwerpwijzigingen belangrijke wijzigingen. Experimentele functies zijn niet bedoeld om te worden gebruikt in productie omdat de wijzigingen mogen worden verbroken.
Experimentele functies zijn standaard uitgeschakeld en moeten expliciet worden ingeschakeld door de gebruiker of beheerder van het systeem.
Ingeschakelde experimentele functies worden vermeld in het powershell.config.json bestand in $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 de vorm van <modulename>.<experimentname>volgen. De ExperimentAction parameter moet worden opgegeven en de enige geldige waarden zijn:
Showbetekent dat deze experimentele functie wordt weergegeven als de functie is ingeschakeldHidebetekent dat deze experimentele functie wordt verborgen als de functie is ingeschakeld
Experimentele functies declareren in modules die zijn geschreven in C#
Moduleauteurs die de markeringen voor experimentele functies willen gebruiken, kunnen een cmdlet als experimenteel declareren 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 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 met de naam en beschrijving van de functie.
Bijvoorbeeld:
PrivateData = @{
PSData = @{
ExperimentalFeatures = @(
@{
Name = "PSWebCmdletV2"
Description = "Rewrite the web cmdlets for better performance"
},
@{
Name = "PSRestCmdletV2"
Description = "Rewrite the REST API cmdlets for better performance"
}
)
}
}
Experimentele functies die elkaar wederzijds uitsluiten
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 die een bestaande cmdlet overschrijft. 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.
Als u van ExperimentAction.Hide gebruikt, 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 biedt de InvokeWebRequestCommandV2 de 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 voor 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 PowerShell-script:
if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature"))
{
# code specific to the experimental feature
}