Come aggiungere sintassi a un argomento della Guida del cmdlet

Nota

La creazione manuale della Guida basata su XML è molto difficile. Il modulo PlatyPS consente di scrivere aiuto in Markdown e quindi convertirlo nella Guida basata su XML. In questo modo è molto più semplice scrivere e gestire la Guida. PlatyPS può anche creare automaticamente i pacchetti della Guida aggiornabili. Per altre informazioni, vedere Creare una Guida basata su XML con PlatyPS.

Prima di iniziare a scrivere il codice XML per il diagramma della sintassi nel file della Guida del cmdlet, leggere questa sezione per ottenere un'immagine chiara del tipo di dati da fornire, ad esempio gli attributi dei parametri e il modo in cui i dati vengono visualizzati nel diagramma della sintassi.

Attributi di parametro

Obbligatorio
- Se true, il parametro deve essere visualizzato in tutti i comandi che usano il set di parametri.
- Se false, il parametro è facoltativo in tutti i comandi che usano il set di parametri.
Posizione
- Se denominato, il nome del parametro è obbligatorio.
- Se posizionale, il nome del parametro è facoltativo. Quando viene omesso, il valore del parametro deve trovarsi nella posizione specificata nel comando . Ad esempio, se il valore è position="1", il valore del parametro deve essere il primo o solo il valore di parametro senza nome nel comando.
Pipeline Input
- Se true (ByValue), è possibile inviare tramite pipe l'input al parametro . L'input è associato al parametro ("associato a") anche se il nome della proprietà e il tipo di oggetto non corrispondono al tipo previsto. I componenti di associazione dei parametri di PowerShell tentano di convertire l'input nel tipo corretto e non riescono il comando solo quando il tipo non può essere convertito. È possibile associare un solo parametro in un set di parametri in base al valore.
- Se true (ByPropertyName), è possibile inviare tramite pipe l'input al parametro . Tuttavia, l'input è associato al parametro solo quando il nome del parametro corrisponde al nome di una proprietà dell'oggetto di input. Ad esempio, se il nome del parametro è Path, gli oggetti inviati tramite pipe al cmdlet sono associati a tale parametro solo quando l'oggetto ha una proprietà denominata path.
- Se true (ByValue, ByPropertyName), è possibile inviare tramite pipe l'input al parametro in base al nome della proprietà o al valore. È possibile associare un solo parametro in un set di parametri in base al valore.
- Se false, non è possibile inviare tramite pipe l'input a questo parametro.
Globbing
- Se true, il testo digitato dall'utente per il valore del parametro può includere caratteri jolly.
- Se false, il testo digitato dall'utente per il valore del parametro non può includere caratteri jolly.

Attributi del valore del parametro

Obbligatorio
- Se true, il valore specificato deve essere usato ogni volta che si usa il parametro in un comando.
- Se false, il valore del parametro è facoltativo. In genere, un valore è facoltativo solo quando è uno dei diversi valori validi per un parametro, ad esempio in un tipo enumerato.

L'attributo Required di un parametro è diverso dall'attributo Required di un parametro.

L'attributo obbligatorio di un parametro indica se il parametro (e il relativo valore) deve essere incluso quando si richiama il cmdlet. Al contrario, l'attributo obbligatorio di un valore di parametro viene usato solo quando il parametro è incluso nel comando . Indica se il valore specifico deve essere usato con il parametro .

In genere, i valori dei parametri che sono segnaposto sono obbligatori e i valori dei parametri che sono valori letterali non sono obbligatori, perché sono uno dei diversi valori che possono essere usati con il parametro .

Raccolta di informazioni sulla sintassi

Iniziare con il nome del cmdlet.
```
SYNTAX
    Get-Tech
```
Elencare tutti i parametri del cmdlet. Digitare un trattino (-) prima di ogni nome di parametro. Separare i parametri in set di parametri (alcuni cmdlet possono avere un solo set di parametri). In questo esempio il cmdlet Get-Tech ha due set di parametri.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Avviare ogni set di parametri con il nome del cmdlet.

Elencare prima il set di parametri predefinito. Il parametro predefinito viene specificato dalla classe cmdlet .

Per ogni set di parametri, elencare prima il parametro univoco, a meno che non siano presenti parametri posizionali che devono essere visualizzati per primi. Nell'esempio precedente i parametri Name e Id sono parametri univoci per i due set di parametri ( ogni set di parametri deve avere un parametro univoco per tale set di parametri). In questo modo è più semplice per gli utenti identificare il parametro che devono fornire per il set di parametri.

Elencare i parametri nell'ordine in cui devono essere visualizzati nel comando . Se l'ordine non è importante, elencare i parametri correlati insieme o elencare prima i parametri usati più di frequente.

Assicurarsi di elencare i parametri WhatIf e Confirm se il cmdlet supporta ShouldProcess.

Non elencare i parametri comuni, ad esempio Verbose, Debug e ErrorAction, nel diagramma della sintassi. Il cmdlet Get-Help aggiunge tali informazioni quando visualizza l'argomento della Guida.
Aggiungere i valori dei parametri. In PowerShell i valori dei parametri sono rappresentati dal tipo .NET. Tuttavia, il nome del tipo può essere abbreviato, ad esempio "string" per System.String.
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
I tipi abbreviati purché il loro significato sia chiaro, ad esempio stringa per System.String e int per System.Int32.

Elencare tutti i valori delle enumerazioni, ad esempio il parametro -Type nell'esempio precedente, che può essere impostato su di base o avanzate .

I parametri switch, ad esempio -List nell'esempio precedente, non hanno valori.
Aggiungere parentesi angolari ai valori dei parametri segnaposto, rispetto ai valori dei parametri che sono valori letterali.
```
SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced
```

Racchiudere i parametri facoltativi e le relative vales tra parentesi quadre.

SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

Racchiudere i nomi dei parametri facoltativi (per i parametri posizionali) tra parentesi quadre. Il nome per i parametri posizionali, ad esempio il parametro Name nell'esempio seguente, non deve essere incluso nel comando .
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
Se un valore di parametro può contenere più valori, ad esempio un elenco di nomi nel parametro Name, aggiungere una coppia di parentesi quadre direttamente dopo il valore del parametro.
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
Se l'utente può scegliere tra parametri o valori di parametro, ad esempio il parametro Type, racchiudere le scelte tra parentesi graffe e separarle con il simbolo OR esclusivo (;)).
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```
Se il valore del parametro deve usare formattazione specifica, ad esempio virgolette o parentesi, mostrare il formato nella sintassi.
```
SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

Codifica del codice XML del diagramma della sintassi

Il nodo della sintassi del codice XML inizia immediatamente dopo il nodo della descrizione, che termina con il tag </maml:description>. Per informazioni sulla raccolta dei dati usati nel diagramma della sintassi, vedere Raccolta di informazioni sulla sintassi.

Aggiunta di un nodo della sintassi

Il diagramma della sintassi visualizzato nell'argomento della Guida dei cmdlet viene generato dai dati nel nodo della sintassi del codice XML. Il nodo della sintassi è racchiuso in una coppia di tag <command:syntax>. Con ogni set di parametri del cmdlet racchiuso in una coppia di tag <command:syntaxitem>. Non esiste alcun limite al numero di tag <command:syntaxitem> che è possibile aggiungere.

Nell'esempio seguente viene illustrato un nodo della sintassi con nodi elemento della sintassi per due set di parametri.

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

Aggiunta del nome del cmdlet ai dati del set di parametri

Ogni set di parametri del cmdlet viene specificato in un nodo dell'elemento della sintassi. Ogni nodo dell'elemento della sintassi inizia con una coppia di tag <maml:name> che includono il nome del cmdlet.

L'esempio seguente include un nodo di sintassi con nodi elemento della sintassi per due set di parametri.

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

Aggiunta di parametri

Ogni parametro aggiunto al nodo dell'elemento della sintassi viene specificato all'interno di una coppia di tag <command:parameter>. È necessaria una coppia di tag <command:parameter> per ogni parametro incluso nel set di parametri, ad eccezione dei parametri comuni forniti da PowerShell.

Gli attributi del tag di apertura <command:parameter> determinano la modalità di visualizzazione del parametro nel diagramma della sintassi. Per informazioni sugli attributi dei parametri, vedere Parameter Attributes.

Nota

Il tag <command:parameter> supporta un elemento figlio <maml:description> il cui contenuto non viene mai visualizzato. Le descrizioni dei parametri vengono specificate nel nodo del parametro del codice XML. Per evitare incoerenze tra le informazioni contenute nell'elemento di sintassi bodes e il nodo del parametro, omettere (<maml:description> o lasciarlo vuoto.

L'esempio seguente include un nodo elemento della sintassi per un set di parametri con due parametri.

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-03-25