about_Experimental_Features

Artikel
12/04/2023

Stöd för experimentella funktioner i PowerShell ger en mekanism för experimentella funktioner som kan samexistera med befintliga stabila funktioner i PowerShell- eller PowerShell-moduler.

En experimentell funktion är en funktion där designen inte har slutförts. Funktionen är tillgänglig för användare att testa och ge feedback. När en experimentell funktion har slutförts blir designändringarna icke-bakåtkompatibla. Experimentella funktioner är inte avsedda att användas i produktion eftersom ändringarna tillåts brytas.

Experimentella funktioner är inaktiverade som standard och måste uttryckligen aktiveras av systemets användare eller administratör.

Aktiverade experimentella funktioner visas i powershell.config.json filen i $PSHOME för alla användare eller den användarspecifika konfigurationsfilen för en specifik användare.

Kommentar

Experimentella funktioner som är aktiverade i användarkonfigurationsfilen har företräde framför experimentella funktioner som anges i systemkonfigurationsfilen.

Det experimentella attributet

Använd attributet Experimental för att deklarera viss kod som experimentell.

Använd följande syntax för att deklarera Experimental attributet som anger namnet på den experimentella funktionen och den åtgärd som ska vidtas om den experimentella funktionen är aktiverad:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

För moduler NameOfExperimentalFeature måste du följa formen <modulename>.<experimentname>. Parametern ExperimentAction måste anges och de enda giltiga värdena är:

Show innebär att visa den här experimentella funktionen om funktionen är aktiverad
Hide innebär att dölja den här experimentella funktionen om funktionen är aktiverad

Deklarera experimentella funktioner i moduler skrivna i C#

Modulförfattare som vill använda flaggorna experimentell funktion kan deklarera en cmdlet som experimentell med hjälp Experimental av attributet.

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

Deklarera experimentella funktioner i moduler skrivna i PowerShell

Modulen som skrivits i PowerShell kan också använda Experimental attributet för att deklarera experimentella cmdletar:

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

Metadata om en experimentell funktion sparas i modulmanifestet. Använd egenskapen för PrivateData.PSData.ExperimentalFeatures ett modulmanifest för att exponera experimentella funktioner från modulen. Egenskapen ExperimentalFeatures är en matris med hashtables som innehåller funktionens namn och beskrivning.

Till exempel:

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

Ömsesidigt uteslutande experimentella funktioner

Det finns fall där en experimentell funktion inte kan samexistera sida vid sida med en befintlig funktion eller en annan experimentell funktion.

Du kan till exempel ha en experimentell cmdlet som åsidosätter en befintlig cmdlet. De två versionerna kan inte samexistera sida vid sida. Inställningen ExperimentAction.Hide tillåter endast att en av de två cmdletarna aktiveras samtidigt.

I det här exemplet skapar vi en ny experimentell Invoke-WebRequest cmdlet. InvokeWebRequestCommand innehåller den icke-experimentella implementeringen. InvokeWebRequestCommandV2 innehåller den experimentella versionen av cmdleten.

Användningen av ExperimentAction.Hide tillåter endast en av de två funktionerna att aktiveras samtidigt:

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

När den MyWebCmdlets.PSWebCmdletV2 experimentella funktionen är aktiverad döljs den befintliga InvokeWebRequestCommand implementeringen och InvokeWebRequestCommandV2 tillhandahåller implementeringen av Invoke-WebRequest.

På så sätt kan användarna prova den nya cmdleten och ge feedback och sedan återgå till den icke-experimentella versionen när det behövs.

Experimentella parametrar i cmdletar

Attributet Experimental kan också tillämpas på enskilda parametrar. På så sätt kan du skapa en experimentell uppsättning parametrar för en befintlig cmdlet i stället för en helt ny cmdlet.

Här är ett exempel i C#:

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

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

Här är ett annat exempel i PowerShell-skript:

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

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

Kontrollera om en experimentell funktion är aktiverad

I koden måste du kontrollera om den experimentella funktionen är aktiverad innan du vidtar lämpliga åtgärder. Du kan avgöra om en experimentell funktion är aktiverad med hjälp av den statiska IsEnabled() metoden i System.Management.Automation.ExperimentalFeature klassen.

Här är ett exempel i C#:

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

Här är ett exempel i PowerShell-skript:

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