Compartilhar via

about_Experimental_Features

O suporte aos Recursos Experimentais no PowerShell fornece um mecanismo para que os recursos experimentais coexistam com os recursos estáveis existentes em módulos do PowerShell ou do PowerShell.

Um recurso experimental é aquele em que o design não é 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 significativas. 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 powershell.config.json em $PSHOME para todos os usuários ou o 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 atributo Experimental para declarar algum código como experimental.

Use a sintaxe a seguir para declarar o atributo Experimental 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 parâmetro ExperimentAction 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 recursos experimentais em módulos escritos em C#

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

[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 atributo Experimental para declarar cmdlets experimentais:

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

Metadados sobre um recurso experimental são mantidos no manifesto do módulo. Use a propriedade PrivateData.PSData.ExperimentalFeatures de um manifesto de módulo para expor os recursos experimentais do módulo. A propriedade ExperimentalFeatures é um array de tabelas 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 configuração de ExperimentAction.Hide permite que apenas um dos dois cmdlets seja habilitado ao mesmo tempo.

Neste exemplo, criamos um novo cmdlet de Invoke-WebRequest experimental. 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 recurso experimental MyWebCmdlets.PSWebCmdletV2 está habilitado, a implementação de InvokeWebRequestCommand existente fica oculta e o InvokeWebRequestCommandV2 fornece a implementação de 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 atributo Experimental 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 de IsEnabled() estático na classe System.Management.Automation.ExperimentalFeature.

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
}

Consulte também

  • Last updated on