about_Experimental_Features

  • Статья

Поддержка экспериментальных функций в PowerShell обеспечивает механизм для сосуществования экспериментальных функций с имеющимися стабильными функциями в модулях PowerShell или PowerShell.

Экспериментальной функцией называется та, которая находится на этапе проектирования. Эта функция доступна пользователям для тестирования и предоставления отзывов о ней. Как только процесс разработки экспериментальной функции будет завершен, изменения на этапе проектирования станут критическими. Экспериментальные функции не предназначены для использования в рабочей среде, так как изменения могут привести к нарушению работы.

Экспериментальные функции отключены по умолчанию и должны быть явно включены пользователем или администратором системы.

Экспериментальные функции перечислены в powershell.config.json файле $PSHOME для всех пользователей или файла конфигурации конкретного пользователя.

Примечание.

Экспериментальные функции, включенные в файл конфигурации пользователя, имеют приоритет над экспериментальными функциями, перечисленными в файле конфигурации системы.

Экспериментальный атрибут

Используйте атрибут, чтобы объявить некоторый Experimental код экспериментальным.

Используйте следующий синтаксис, чтобы объявить Experimental атрибут, предоставляющий имя экспериментальной функции, и действие, выполняемое, если экспериментальная функция включена:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

Для модулей NameOfExperimentalFeature необходимо следовать форме <modulename>.<experimentname>. Параметр ExperimentAction должен быть указан, а допустимые значения :

  • Show означает, чтобы показать эту экспериментальную функцию, если эта функция включена
  • Hide означает скрыть эту экспериментальную функцию, если эта функция включена

Объявление экспериментальных функций в модулях, написанных на C#

Авторы модулей, которые хотят использовать флаги экспериментальных компонентов, могут объявлять командлет как экспериментальный с помощью атрибута Experimental .

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

Объявление экспериментальных функций в модулях, написанных в PowerShell

Модуль, написанный Experimental в PowerShell, также может использовать атрибут для объявления экспериментальных командлетов:

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

Метаданные о экспериментальной функции хранятся в манифесте модуля. PrivateData.PSData.ExperimentalFeatures Используйте свойство манифеста модуля для предоставления экспериментальных функций из модуля. Это ExperimentalFeatures свойство представляет собой массив хэш-страниц, содержащий имя и описание функции.

Например:

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

Взаимоисключающие экспериментальные функции

Существуют случаи, когда экспериментальная функция не может сосуществовать параллельно с существующей функцией или другой экспериментальной функцией.

Например, можно использовать экспериментальный командлет, который переопределяет существующий командлет. Две версии не могут сосуществовать параллельно. Параметр ExperimentAction.Hide позволяет одновременно включить только один из двух командлетов.

В этом примере мы создадим новый экспериментальный Invoke-WebRequest командлет. InvokeWebRequestCommand содержит не экспериментальную реализацию. InvokeWebRequestCommandV2 содержит экспериментальную версию командлета.

Использование ExperimentAction.Hide позволяет одновременно включить только одну из двух функций:

[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 функция включена, существующая InvokeWebRequestCommand реализация скрыта и InvokeWebRequestCommandV2 предоставляет реализацию Invoke-WebRequest.

Это позволяет пользователям попробовать новый командлет и отправить отзыв, а затем отменить изменения в не экспериментальную версию при необходимости.

Экспериментальные параметры в командлетах

Атрибут Experimental также можно применить к отдельным параметрам. Это позволяет создать экспериментальный набор параметров для существующего командлета, а не полностью новый командлет.

Ниже приведен пример в C#:

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

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

Ниже приведен другой пример в скрипте PowerShell:

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

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

Проверка включения экспериментальной функции

В коде необходимо проверка, если экспериментальная функция включена перед принятием соответствующих действий. Можно определить, включена ли экспериментальная функция с помощью статического IsEnabled() метода в System.Management.Automation.ExperimentalFeature классе.

Ниже приведен пример в C#:

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

Ниже приведен пример сценария PowerShell:

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

См. также