about_Experimental_Features

Статья
05/09/2024

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

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