about_Experimental_Features

  • Artigo

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 arquivo para $PSHOME todos os usuários ou no powershell.config.json arquivo de configuração específico do usuário para um usuário específico.

Observação

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 os 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 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 de módulo para expor os recursos experimentais do módulo. A ExperimentalFeatures propriedade é uma matriz de hashtables 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 uma característica experimental não pode coexistir lado a lado com uma característica existente ou outra característica 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 a ação apropriada. 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
}

Confira também