Поделиться через

сведения_об_экспериментальных_функциях

Поддержка экспериментальных функций в 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

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

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
}

См. также

  • Last updated on