about_Experimental_Features

  • Artykuł

Obsługa funkcji eksperymentalnych w programie PowerShell zapewnia mechanizm eksperymentalnych funkcji współistnienia z istniejącymi stabilnymi funkcjami w modułach programu PowerShell lub programu PowerShell.

Funkcja eksperymentalna jest funkcją, w której projekt nie jest sfinalizowany. Funkcja jest dostępna dla użytkowników do testowania i przekazywania opinii. Po sfinalizowaniu funkcji eksperymentalnej zmiany projektu staną się zmianami powodujących niezgodność. Funkcje eksperymentalne nie są przeznaczone do użycia w środowisku produkcyjnym, ponieważ zmiany mogą być przerywane.

Funkcje eksperymentalne są domyślnie wyłączone i muszą być jawnie włączone przez użytkownika lub administratora systemu.

Włączone funkcje eksperymentalne są wymienione w pliku w powershell.config.json$PSHOME pliku dla wszystkich użytkowników lub pliku konfiguracji specyficznego dla użytkownika dla określonego użytkownika.

Uwaga

Funkcje eksperymentalne włączone w pliku konfiguracji użytkownika mają pierwszeństwo przed funkcjami eksperymentalnymi wymienionymi w pliku konfiguracji systemu.

Atrybut eksperymentalny

Użyj atrybutu , Experimental aby zadeklarować kod jako eksperymentalny.

Użyj następującej składni, aby zadeklarować Experimental atrybut podający nazwę funkcji eksperymentalnej i akcję do wykonania, jeśli funkcja eksperymentalna jest włączona:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

W przypadku modułów NameOfExperimentalFeature element musi mieć postać <modulename>.<experimentname>. Należy ExperimentAction określić parametr, a jedynymi prawidłowymi wartościami są:

  • Show oznacza, aby pokazać tę funkcję eksperymentalną, jeśli funkcja jest włączona
  • Hide oznacza ukrycie tej funkcji eksperymentalnej, jeśli funkcja jest włączona

Deklarowanie funkcji eksperymentalnych w modułach napisanych w języku C#

Autorzy modułów, którzy chcą używać flag funkcji eksperymentalnych, mogą zadeklarować polecenie cmdlet jako eksperymentalne przy użyciu atrybutu Experimental .

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

Deklarowanie funkcji eksperymentalnych w modułach napisanych w programie PowerShell

Moduł napisany w programie PowerShell może również używać atrybutu Experimental do deklarowania eksperymentalnych poleceń cmdlet:

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

Metadane dotyczące funkcji eksperymentalnej są przechowywane w manifeście modułu. PrivateData.PSData.ExperimentalFeatures Użyj właściwości manifestu modułu, aby uwidocznić funkcje eksperymentalne z modułu. Właściwość ExperimentalFeatures to tablica tabel skrótów zawierająca nazwę i opis funkcji.

Na przykład:

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

Wzajemnie wykluczające się funkcje eksperymentalne

Istnieją przypadki, w których funkcja eksperymentalna nie może współistnieć obok istniejącej funkcji lub innej funkcji eksperymentalnej.

Możesz na przykład mieć eksperymentalne polecenie cmdlet, które zastępuje istniejące polecenie cmdlet. Obie wersje nie mogą współistnieć obok siebie. Ustawienie ExperimentAction.Hide umożliwia włączenie tylko jednego z dwóch poleceń cmdlet jednocześnie.

W tym przykładzie utworzymy nowe eksperymentalne Invoke-WebRequest polecenie cmdlet. InvokeWebRequestCommand zawiera implementację nie eksperymentalną. InvokeWebRequestCommandV2 zawiera eksperymentalną wersję polecenia cmdlet.

Użycie funkcji ExperimentAction.Hide pozwoli jednocześnie włączyć tylko jedną z dwóch funkcji:

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

Po włączeniu funkcji eksperymentalnej MyWebCmdlets.PSWebCmdletV2 istniejąca InvokeWebRequestCommand implementacja jest ukryta i InvokeWebRequestCommandV2 zapewnia implementację programu Invoke-WebRequest.

Dzięki temu użytkownicy mogą wypróbować nowe polecenie cmdlet i przekazać opinię, a następnie przywrócić nie eksperymentalną wersję w razie potrzeby.

Parametry eksperymentalne w poleceniach cmdlet

Atrybut Experimental można również zastosować do poszczególnych parametrów. Dzięki temu można utworzyć eksperymentalny zestaw parametrów dla istniejącego polecenia cmdlet, a nie całkowicie nowego polecenia cmdlet.

Oto przykład w języku C#:

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

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

Oto inny przykład skryptu programu PowerShell:

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

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

Sprawdzanie, czy funkcja eksperymentalna jest włączona

W kodzie należy sprawdzić, czy funkcja eksperymentalna jest włączona przed podjęciem odpowiednich działań. Możesz określić, czy funkcja eksperymentalna jest włączona przy użyciu metody statycznej IsEnabled() w System.Management.Automation.ExperimentalFeature klasie .

Oto przykład w języku C#:

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

Oto przykład skryptu programu PowerShell:

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

Zobacz też