about_Experimental_Features

Článek
12/04/2023

Podpora experimentálních funkcí v PowerShellu poskytuje mechanismus pro experimentální funkce, které spolu existují se stávajícími stabilními funkcemi v modulech PowerShellu nebo PowerShellu.

Experimentální funkce je jedna, kde návrh není finalizován. Tato funkce je dostupná pro uživatele, kteří můžou testovat a poskytovat zpětnou vazbu. Po dokončení experimentální funkce se změny návrhu stanou zásadními změnami. Experimentální funkce nejsou určeny k použití v produkčním prostředí, protože změny mohou být zásadní.

Experimentální funkce jsou ve výchozím nastavení zakázané a musí je explicitně povolit uživatel nebo správce systému.

Povolené experimentální funkce jsou uvedené v powershell.config.json souboru $PSHOME pro všechny uživatele nebo konfigurační soubor specifický pro konkrétního uživatele.

Poznámka:

Experimentální funkce povolené v konfiguračním souboru uživatele mají přednost před experimentálními funkcemi uvedenými v konfiguračním souboru systému.

Experimentální atribut

Pomocí atributu Experimental deklarujte nějaký kód jako experimentální.

Pomocí následující syntaxe deklarujte Experimental atribut, který obsahuje název experimentální funkce, a akci, která se má provést, pokud je povolená experimentální funkce:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

Pro moduly NameOfExperimentalFeature musí následovat forma <modulename>.<experimentname>. Parametr ExperimentAction musí být zadán a jediné platné hodnoty jsou:

Show znamená zobrazit tuto experimentální funkci, pokud je tato funkce povolená.
Hide znamená skrytí této experimentální funkce, pokud je tato funkce povolená.

Deklarace experimentálních funkcí v modulech napsaných v jazyce C#

Autoři modulů, kteří chtějí používat příznaky experimentální funkce, mohou deklarovat rutinu jako experimentální pomocí atributu Experimental .

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

Deklarace experimentálních funkcí v modulech napsaných v PowerShellu

Modul napsaný v PowerShellu může také pomocí atributu Experimental deklarovat experimentální rutiny:

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

Metadata o experimentální funkci se uchovávají v manifestu modulu. PrivateData.PSData.ExperimentalFeatures Pomocí vlastnosti manifestu modulu zpřístupněte experimentální funkce z modulu. Vlastnost ExperimentalFeatures je pole hashtable obsahující název a popis funkce.

Příklad:

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

Vzájemně se vylučují experimentální funkce

Existují případy, kdy experimentální funkce nemůže existovat souběžně s existující funkcí nebo jinou experimentální funkcí.

Můžete mít například experimentální rutinu, která přepíše existující rutinu. Obě verze nemůžou existovat vedle sebe. Nastavení ExperimentAction.Hide umožňuje povolení pouze jedné ze dvou rutin najednou.

V tomto příkladu vytvoříme novou experimentální Invoke-WebRequest rutinu. InvokeWebRequestCommand obsahuje nekonkuilní implementaci. InvokeWebRequestCommandV2 obsahuje experimentální verzi rutiny.

Použití ExperimentAction.Hide bude umožňovat povolení pouze jedné ze dvou funkcí najednou:

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

MyWebCmdlets.PSWebCmdletV2 Pokud je experimentální funkce povolena, stávající InvokeWebRequestCommand implementace je skrytá a InvokeWebRequestCommandV2 poskytuje implementaci Invoke-WebRequest.

To uživatelům umožňuje vyzkoušet novou rutinu a poskytnout zpětnou vazbu a v případě potřeby se vrátit k ne experimentální verzi.

Experimentální parametry v rutinách

Atribut Experimental lze také použít pro jednotlivé parametry. Díky tomu můžete vytvořit experimentální sadu parametrů pro existující rutinu, nikoli zcela novou rutinu.

Tady je příklad v jazyce C#:

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

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

Tady je jiný příklad ve skriptu PowerShellu:

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

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

Kontrola, jestli je povolená experimentální funkce

V kódu budete muset před provedením odpovídající akce zkontrolovat, jestli je vaše experimentální funkce povolená. Pomocí statické IsEnabled() metody ve System.Management.Automation.ExperimentalFeature třídě můžete určit, jestli je povolená experimentální funkce.

Tady je příklad v jazyce C#:

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

Tady je příklad ve skriptu PowerShellu:

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