about_Experimental_Features

Artigo
12/04/2023

O suporte a 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 projeto não é finalizado. O recurso está disponível para os usuários testarem e fornecerem feedback. Uma vez que um recurso experimental é finalizado, as mudanças de design tornam-se mudanças de rutura. Os recursos experimentais não se destinam a ser usados na produção, uma vez que as mudanças podem ser quebradas.

Os recursos experimentais são desativados 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.

Nota

Os recursos experimentais habilitados 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 sintaxe a seguir para declarar o Experimental atributo que fornece 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 este recurso experimental se o recurso estiver habilitado
Hide significa ocultar esse recurso experimental se o recurso estiver habilitado

Declarando características 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 do módulo para expor os recursos experimentais do módulo. A ExperimentalFeatures propriedade é uma matriz de hashtables contendo 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"
      }
    )
  }
}

Características experimentais mutuamente exclusivas

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 substitua 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 ao mesmo tempo.

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 do 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 é habilitado, a implementação existente InvokeWebRequestCommand fica oculta e o InvokeWebRequestCommandV2 fornece 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 seu 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
}

Partilhar via