about_Experimental_Features

Artigo
11/06/2024

O suporte de recursos experimentais no PowerShell fornece um mecanismo para que os recursos experimentais coexistam com os recursos estáveis existentes nos módulos PowerShell ou PowerShell.

Um recurso experimental é aquele em que o design não está finalizado. O recurso está disponível para os usuários testarem e fornecerem comentários. Depois que um recurso experimental é finalizado, as alterações de design se tornam alterações interruptivas. Os recursos experimentais não devem ser usados na produção, já que as alterações podem causar problemas.

Os recursos experimentais são desabilitados por padrão e precisam ser explicitamente habilitados pelo usuário ou administrador do sistema.

Os recursos experimentais habilitados são listados no powershell.config.json arquivo em $PSHOME para todos os usuários ou no arquivo de configuração específico do usuário para um usuário específico.

Observação

Os recursos experimentais ativados no arquivo de configuração do usuário têm precedência sobre os recursos experimentais listados no arquivo de configuração do sistema.

O Atributo Experimental

Use o Experimental atributo para declarar algum código como experimental.

Use a seguinte sintaxe para declarar o Experimental atributo fornecendo o nome do recurso experimental e a ação a ser executada se o recurso experimental estiver habilitado:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

Para módulos, o NameOfExperimentalFeature deve seguir a forma de <modulename>.<experimentname>. O ExperimentAction parâmetro deve ser especificado e os únicos valores válidos são:

Show significa mostrar esse recurso experimental se o recurso estiver ativado
Hide significa ocultar esse recurso experimental se o recurso estiver ativado

Declarando recursos experimentais em módulos escritos em C#

Os autores de módulo que desejam usar os sinalizadores de Recurso Experimental podem declarar um cmdlet como experimental usando o Experimental atributo.

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

Declarando recursos experimentais em módulos escritos no PowerShell

O módulo escrito no PowerShell também pode usar o Experimental atributo para declarar cmdlets experimentais:

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

Os metadados sobre um recurso experimental são mantidos no manifesto do módulo. Use a propriedade de um manifesto PrivateData.PSData.ExperimentalFeatures de módulo para expor os recursos experimentais do módulo. A ExperimentalFeatures propriedade é uma matriz de tabelas de hash que contém o nome e a descrição do recurso.

Por exemplo:

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

Recursos experimentais mutuamente exclusivos

Há casos em que um recurso experimental não pode coexistir lado a lado com um recurso existente ou outro recurso experimental.

Por exemplo, você pode ter um cmdlet experimental que substitui um cmdlet existente. As duas versões não podem coexistir lado a lado. A ExperimentAction.Hide configuração permite que apenas um dos dois cmdlets seja habilitado por vez.

Neste exemplo, criamos um novo cmdlet experimental Invoke-WebRequest . InvokeWebRequestCommand contém a implementação não experimental. InvokeWebRequestCommandV2 contém a versão experimental do cmdlet.

O uso de ExperimentAction.Hide permitirá que apenas um dos dois recursos seja habilitado ao mesmo tempo:

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

Quando o MyWebCmdlets.PSWebCmdletV2 recurso experimental está ativado, a implementação existente InvokeWebRequestCommand fica oculta e fornece InvokeWebRequestCommandV2 a implementação do Invoke-WebRequest.

Isso permite que os usuários experimentem o novo cmdlet e forneçam comentários e, em seguida, revertam para a versão não experimental quando necessário.

Parâmetros experimentais em cmdlets

O Experimental atributo também pode ser aplicado a parâmetros individuais. Isso permite que você crie um conjunto experimental de parâmetros para um cmdlet existente, em vez de um cmdlet totalmente novo.

Aqui está um exemplo em C#:

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

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

Aqui está um exemplo diferente no script do PowerShell:

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

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

Verificando se um recurso experimental está habilitado

Em seu código, você precisará verificar se o recurso experimental está habilitado antes de tomar as medidas apropriadas. Você pode determinar se um recurso experimental está habilitado usando o método estático IsEnabled() na System.Management.Automation.ExperimentalFeature classe.

Aqui está um exemplo em C#:

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

Aqui está um exemplo no script do PowerShell:

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

Compartilhar via