about_Experimental_Features

  • Artículo

La compatibilidad con las características experimentales de PowerShell proporciona un mecanismo para que las características experimentales coexistan con las características estables existentes en PowerShell o los módulos de PowerShell.

Una característica experimental es aquella en la el diseño no ha finalizado. La característica está disponible para que los usuarios puedan probar y proporcionar comentarios. Una vez finalizada una característica experimental, los cambios de diseño se vuelven importantes. No está previsto que las características experimentales se usen en producción, ya que los cambios se pueden interrumpir.

Las características experimentales están deshabilitadas de forma predeterminada y deben estar habilitadas explícitamente por el usuario o el administrador del sistema.

Las características experimentales habilitadas se muestran en el powershell.config.json archivo en $PSHOME para todos los usuarios o el archivo de configuración específico del usuario para un usuario específico.

Nota:

Las características experimentales habilitadas en el archivo de configuración de usuario tienen prioridad sobre las características experimentales enumeradas en el archivo de configuración del sistema.

Atributo experimental

Use el Experimental atributo para declarar código como experimental.

Use la sintaxis siguiente para declarar el Experimental atributo que proporciona el nombre de la característica experimental y la acción que se va a realizar si la característica experimental está habilitada:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

En el caso de los módulos, NameOfExperimentalFeature debe seguir la forma de <modulename>.<experimentname>. El ExperimentAction parámetro debe especificarse y los únicos valores válidos son:

  • Show significa mostrar esta característica experimental si la característica está habilitada
  • Hide significa ocultar esta característica experimental si la característica está habilitada

Declarar características experimentales en módulos escritos en C#

Los autores de módulos que quieran usar las marcas de características experimentales pueden declarar un cmdlet como experimental mediante el Experimental atributo .

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

Declaración de características experimentales en módulos escritos en PowerShell

El módulo escrito en PowerShell también puede usar el Experimental atributo para declarar cmdlets experimentales:

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

Los metadatos sobre una característica experimental se conservan en el manifiesto del módulo. Use la PrivateData.PSData.ExperimentalFeatures propiedad de un manifiesto de módulo para exponer las características experimentales del módulo. La ExperimentalFeatures propiedad es una matriz de tablas hash que contienen el nombre y la descripción de la característica.

Por ejemplo:

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 experimentales mutuamente excluyentes

Hay casos en los que una característica experimental no puede coexistir en paralelo con una característica existente u otra característica experimental.

Por ejemplo, puede tener un cmdlet experimental que invalide un cmdlet existente. Las dos versiones no pueden coexistir en paralelo. La ExperimentAction.Hide configuración solo permite habilitar uno de los dos cmdlets a la vez.

En este ejemplo, se crea un nuevo cmdlet experimental Invoke-WebRequest . InvokeWebRequestCommand contiene la implementación no experimental. InvokeWebRequestCommandV2 contiene la versión experimental del cmdlet.

El uso de ExperimentAction.Hide permitirá habilitar solo una de las dos características a la vez:

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

Cuando la MyWebCmdlets.PSWebCmdletV2 característica experimental está habilitada, la implementación existente InvokeWebRequestCommand está oculta y InvokeWebRequestCommandV2 proporciona la implementación de Invoke-WebRequest.

Esto permite a los usuarios probar el nuevo cmdlet y proporcionar comentarios y, a continuación, revertir a la versión no experimental cuando sea necesario.

Parámetros experimentales en cmdlets

El Experimental atributo también se puede aplicar a parámetros individuales. Esto le permite crear un conjunto experimental de parámetros para un cmdlet existente en lugar de un cmdlet completamente nuevo.

Este es un ejemplo en C#:

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

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

Este es un ejemplo diferente en el script de PowerShell:

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

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

Comprobación de si una característica experimental está habilitada

En el código, deberá comprobar si la característica experimental está habilitada antes de realizar las acciones adecuadas. Puede determinar si una característica experimental está habilitada mediante el método estático IsEnabled() en la System.Management.Automation.ExperimentalFeature clase .

Este es un ejemplo en C#:

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

Este es un ejemplo en el script de PowerShell:

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

Consulte también