about_Experimental_Features

Articolo
12/04/2023

Il supporto delle funzionalità sperimentali in PowerShell mette a disposizione un meccanismo per la coesistenza delle funzionalità sperimentali con le funzionalità stabili esistenti in PowerShell o nei moduli di PowerShell.

Una funzionalità sperimentale è una funzionalità la cui progettazione non è finalizzata. La funzionalità è disponibile per consentire agli utenti di testarla e offrire feedback. Dopo che una funzionalità sperimentale è stata finalizzata, le modifiche alla progettazione diventano modifiche che causano un'interruzione. Le funzionalità sperimentali non sono destinate all'uso nell'ambiente di produzione perché in tali funzionalità le modifiche che causano un'interruzione sono consentite.

Le funzionalità sperimentali sono disabilitate per impostazione predefinita e devono essere abilitate in modo esplicito dall'utente o dall'amministratore del sistema.

Le funzionalità sperimentali abilitate sono elencate nel file in powershell.config.json$PSHOME per tutti gli utenti o il file di configurazione specifico dell'utente per un utente specifico.

Nota

Le funzionalità sperimentali abilitate nel file di configurazione utente hanno la precedenza sulle funzionalità sperimentali elencate nel file di configurazione del sistema.

Attributo sperimentale

Usare l'attributo Experimental per dichiarare codice come sperimentale.

Usare la sintassi seguente per dichiarare l'attributo Experimental specificando il nome della funzionalità sperimentale e l'azione da eseguire se la funzionalità sperimentale è abilitata:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

Per i moduli, l'oggetto NameOfExperimentalFeature deve seguire il formato di <modulename>.<experimentname>. Il ExperimentAction parametro deve essere specificato e gli unici valori validi sono:

Show significa mostrare questa funzionalità sperimentale se la funzionalità è abilitata
Hide significa nascondere questa funzionalità sperimentale se la funzionalità è abilitata

Dichiarazione di funzionalità sperimentali nei moduli scritti in C#

Gli autori di moduli che vogliono usare i flag di funzionalità sperimentale possono dichiarare un cmdlet come sperimentale usando l'attributo Experimental .

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

Dichiarazione di funzionalità sperimentali nei moduli scritti in PowerShell

Il modulo scritto in PowerShell può anche usare l'attributo Experimental per dichiarare i cmdlet sperimentali:

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

I metadati relativi a una funzionalità sperimentale vengono mantenuti nel manifesto del modulo. Usare la PrivateData.PSData.ExperimentalFeatures proprietà di un manifesto del modulo per esporre le funzionalità sperimentali del modulo. La ExperimentalFeatures proprietà è una matrice di tabelle hash contenenti il nome e la descrizione della funzionalità.

Ad esempio:

PrivateData = @{
  PSData = @{
    ExperimentalFeatures = @(
      @{
          Name = "PSWebCmdletV2"
          Description = "Rewrite the web cmdlets for better performance"
      },
      @{
          Name = "PSRestCmdletV2"
          Description = "Rewrite the REST API cmdlets for better performance"
      }
    )
  }
}

Funzionalità sperimentali che si escludono a vicenda

Esistono casi in cui una funzionalità sperimentale non può coesistere side-by-side con una funzionalità esistente o un'altra funzionalità sperimentale.

Ad esempio, è possibile avere un cmdlet sperimentale che esegue l'override di un cmdlet esistente. Le due versioni non possono coesistere affiancate. L'impostazione ExperimentAction.Hide consente di abilitare solo uno dei due cmdlet contemporaneamente.

In questo esempio viene creato un nuovo cmdlet sperimentale Invoke-WebRequest . InvokeWebRequestCommand contiene l'implementazione non sperimentale. InvokeWebRequestCommandV2 contiene la versione sperimentale del cmdlet.

L'uso di ExperimentAction.Hide consentirà di abilitare una sola delle due funzionalità contemporaneamente:

[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 la MyWebCmdlets.PSWebCmdletV2 funzionalità sperimentale è abilitata, l'implementazione esistente InvokeWebRequestCommand è nascosta e InvokeWebRequestCommandV2 fornisce l'implementazione di Invoke-WebRequest.

In questo modo gli utenti possono provare il nuovo cmdlet e fornire commenti e suggerimenti e quindi ripristinare la versione non sperimentale quando necessario.

Parametri sperimentali nei cmdlet

L'attributo Experimental può essere applicato anche ai singoli parametri. In questo modo è possibile creare un set sperimentale di parametri per un cmdlet esistente anziché un cmdlet completamente nuovo.

Ecco un esempio in C#:

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

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

Di seguito è riportato un esempio diverso nello script di PowerShell:

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

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

Verifica se una funzionalità sperimentale è abilitata

Nel codice è necessario verificare se la funzionalità sperimentale è abilitata prima di intraprendere un'azione appropriata. È possibile determinare se una funzionalità sperimentale è abilitata usando il metodo statico IsEnabled() nella System.Management.Automation.ExperimentalFeature classe .

Ecco un esempio in C#:

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

Di seguito è riportato un esempio di script di PowerShell:

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

Condividi tramite