Partilhar via

sobre_Funcionalidades_Experimentais

O suporte a recursos experimentais no PowerShell fornece um mecanismo para que estes possam coexistir com os recursos estáveis existentes no próprio PowerShell ou nos seus módulos.

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 alterações de design tornam-se mudanças de rutura. Os recursos experimentais não se destinam a ser usados em produção, uma vez que as mudanças podem causar interrupções.

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 arquivo powershell.config.json 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 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 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 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 características experimentais em módulos escritos em C#

Os autores de módulos que desejam usar os sinalizadores de recurso experimental 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()
    ...
}

Os 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 é uma matriz de hashtables contendo o nome e a descrição da funcionalidade.

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 configuração ExperimentAction.Hide 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 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 seu recurso experimental está habilitado antes de tomar as medidas apropriadas. Você pode determinar se um recurso experimental está habilitado usando o método 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