Powershell - Creazione cmdlet - Profili powershell e Crezione Moduli

In questo post tratteremo i seguenti argomenti: 


1) Come creare un cmdlet scritto in linguaggio script powershell
2) Come creare un cmdlet con un help
3) Come importare un cmdlet all'interno del profilo powershell per averlo sempre disponibile.
4) Come creare un nostro Modulo contenente un set di cmdlet.



1) Creare un cmdlet scritto in linguaggio script Powershell
In realtà non si dovrebbe parlare di cmdlet ma di funzioni avanzate caratterizzate dall'elemento  CmdletBinding() che permette alla funzione di avere un comportamente analogo a quello di un cmdlet scritto in linguaggio .NET framework C#.

Creando la nostra funzione avanzata, da adesso cmdlet, sarà possibile avere un help come quello dei tradizionali cmdlet, l'autocompletamento, i parametri switch ecc...


Vediamo ora un esempio classico: HELLO WORLD

function Send-Saluto{
          [CmdletBinding()]
          Param(
                      [Parameter(Mandatory=$true)]
                      [string] $Nome
           )#End Param


          Process
          {
                         write-host ("Hello " + $Nome + "!!!")
          }#End Process
 }#End Function

in questo modo potremo stampare a video un saluto,

Esempio: 

PS> Send-Saluto AuryTech

Hello AuryTech!

In questo modo abbiamo creato un cmdlet molto semplice. 

I parametri possono avere diverse proprietà ed è molto importante settarle, in questo modo sarà possibile definire se un parametro è obbligatorio o se può essere passato in pipeline o se deve far parte di un set specifico di parametri. 

Ad esempio, ipotizziamo di voler riscrivere la funzione send-saluto avendo il parametro Nome obbligatorio, passabile da pipeline e facente pare di un set di nomi. Inoltre, aggiungiamo una funzionalità che chiamiamo "cortesia", così da permettere al cmdlet di essere cortese e di chiedere come va all'utente. 

  function Send-Saluto
        {
          [CmdletBinding()]
          Param
          (
               [parameter(Mandatory=$true, ValueFromPipeline=$true)]
               [String]
               [ValidateSet("Gianni", "Marco", "Davide")]
              $nome,
                 [parameter(Mandatory=$false)]
               [Switch]
              $Cortesia
          ) #End Param
          Process
          {
              write-host ("Hello " + $nome+ "!!")
             if ($Cortesia) {write-host "Come va?"}
          }#End Process
}#End Function

Nota: Specificando un parametro come switch è possibile non specificare alcun valore al parametro ed usarlo appunto come switch. 

Esempio: 

PS> "Gianni" | Send-Saluto

Hello Gianni!!

PS> Send-Saluto gianni -Cortesia
Hello gianni!!
Come va?

Chiaramente se il nome non fa parte dei 3 indicati o  se non specificate alcun nome,  vi restituirà un errore.

Che nome dare alla funzione?  naturalmente verbo-sostantivo come le normali cmdlet. Per ottenere un elenco dei verbi utilizzabili digitare il comando Get-Verbs, 

Nota: se non utilizzate uno dei verbi indicati funzionerà tutto comunque ma avremo un errore in fase di importazione del cmdlet nel profilo utente, inoltre, la facilità di powershell è anche data dalla regola verbo-sostantivo. 

2) Aggiungere un help al cmdlet

Per aggiungere un help al cmdlet basta aggiungere il seguente blocco di commenti all'interno della funzione. 
<#
.SYNOPSIS
.DESCRIPTION .NOTES.EXAMPLE  
.EXAMPLE
.PARAMETER <nome parametro>
.PARAMETER <nome parametro>
#>


Esempio: 

  function Send-Saluto

        {

<#

.SYNOPSIS

            Questo cmdlet saluta

.DESCRIPTION 

           Questa cmdl saluta solo 3 persone Gianni Narco e Davide e può chiedere loro come va. 

.NOTES

             Aurtore: AuryTech

.EXAMPLE  

              "Gianni" | send-saluto

               Viene salutato gianni

.EXAMPLE
              send-saluto -nome gianni -cortesia

               Viene salutato gianni e gli viene chiesto come va

.PARAMETER Nome

                Il nome della persona da salutare tra le seguenti

                        - Gianni

                        - Marco

                         - Davide

 .PARAMETER Cortesia
                Se specificato viene chiesto "come va?" alla persona indicata in nome.

#>

          [CmdletBinding()]

          Param

          (

               [parameter(Mandatory=$true, ValueFromPipeline=$true)]

               [String]

               [ValidateSet("Gianni", "Marco", "Davide")]

              $nome,

                 [parameter(Mandatory=$false)]

               [Switch]

              $Cortesia

          ) #End Param

          Process

          {

              write-host ("Hello " + $nome+ "!!")

             if ($Cortesia) {write-host "Come va?"}

          }#End Process

}#End Function

Se provate a fare un help della funzione NON vi verrà restituito l'help. 
Abbiamo strutturato il tutto per funzionare come cmdlet non come script, se volete visualizzare l'help adesso salvate il codice in un file PS1 togliendo la definizione della function. 
A questo punto aprite powershell posizionatevi nella cartella del file e digitate:


PS> man .\<nomefile>.ps1 -full


Adesso vi verrà mostrato l'help! 


Abbiamo strutturato il codice per poter funzionare come cmdlet,  infatti se provate a salvarlo come file PSM1 e ad importarlo tramite il comando:


PS> import-module c:\send-saluto.psm1
PS> get-help send-saluto -Full


A questo punto vi verrà visualizzato l'help.


Quindi non ci resta che aggiungerlo tra i cmdlet della shell o meglio al profilo powershell.


3) Profili Powershell

Quello che dobbiamo fare per aggiungere al nostro profilo un cmdlet non è altro che il comando eseguito in precedenza ma con una variante.

PS>  import-module <Nome Modulo>


Adesso però deve essere specificato il nome del modulo e non il file PSM1.


Vediamo come.
1) Posizionarsi su C:\Users\<utente>\Documents\WindowsPowerShell\Modules (se non esiste create le cartelle)
2) Creare una cartella dentro modules, questa sarà il nome del vostro modulo e conterrà il file .PSM1 (cartella e file devono avere lo stesso nome)
3) Editate o create il file del profilo. 
Il file del profilo si trova all'interno della cartella WindowsPowerShell e si chiama Microsoft.PowerShell_profile.ps1. Questo file viene caricato ad ogni apertura di powershell.exe.
Inserite all'interno del file la stringa import-module <Nome Modulo>


Adesso aprendo powershell vi troverete il cmdlet già caricato. 


Il file del profilo editato non è il solo file di profili powershell, nello specifico è il file del profilo dell'utente corrente SOLO per la console di powershell. 


Se stampate a video la variabile $profile da powershell o dall'editor ISE vi accorgerete di come i file siano diversi: 


Powershell:  Microsoft.PowerShell_profile.ps1
Editor ISE: Microsoft.PowerShellISE_profile.ps1


La variabile $profile contiene altre proprietà relative ai profili powershell. 
$profile.AllUsersAllHosts    (tutti gli utenti, qualunque shell [ise,powershell,ecc])
$profile.AllUsersCurrentHost (tutti gli utenti, solo questa shell [ISE o powershell o...ecc....])
$profile.CurrentUserAllHosts  (l'utente corrente, qualunque shell [ise,powershell,ecc])
$profile.CurrentUserCurrentHost (l'utente corrente solo questa shell [ISE o powershell o...ecc....])


stampatele a video per avere più chiara la situazione. 


Quindi se volessimo importare il nostro cmdlet per tutti gli utenti che fanno login sulla macchina e con tutte le shell/editor modificheremo il file del profilo $profile.AllUsersAllHosts e creeremo la cartella del nostro modulo all'interno della cartella modules presente nel percorso del profilo editato. 


Esempio:
Profilo editato: 
                          C:\Windows\System32\WindowsPowerShell\v1.0\profile.ps1 
                          Inseriamo il comando import-module <Nome Modulo>
Quì mettiamo il modulo: 
                         C:\Windows\System32\WindowsPowerShell\v1.0\MODULES\<NOME NOSTRO MODULO>

4) MODULI

In realtà un modulo scritto in linguaggio script powershell non è altro che quello che abbiamo appena creato, ma vediamone alcuni aspetti.

Aprendo la vostra console powershell vi troverete il modulo che avete importato, provate a digitare i seguenti comandi:

Get-Module ( vi verrà visualizzato il vostro modulo)
Get-command -module <Nome Modulo> ( vi verrà visualizzata il vostro cmdlet)

Questo significa che possiamo creare un set di cmdlet ed integrarli tutti dentro un modulo.

Vediamo come:

1) Creiamo la cartella del nostro modulo
   Ipotizziamo AuryTech
2) Creiamo 2 file PS1 contenenti le funzioni (come visto durante la creazione del cmdlet)
    Ipotizziamo dei nomi tipo Send-Saluto, Send-Bacio
3) Creiamo 1 file PSM1 e lo chiamiamo come la cartella del nostro modulo, in questo caso AuryTech.psm1
4) Inseriamo il seguente codice all'interno del file AuryTech.psm1.

$directoryscript = (get-item $MyInvocation.MyCommand.Definition).directoryname #Il percorso dello script psm1

. "$directoryscript\Send-Baluto.ps1" #Importazione della function presente all'interno del file 
. "$directoryscript\Send-Bacio.ps1" #Importazione della function presente all'interno del file 

5) Editiamo il nostro file del profilo ed inseriamo il solito import-module <Nome Modulo>

import-module AuryTech


6) Copiamo la cartella AuryTech del nostro modulo e inseriamola nella cartella Modules di powershell (come visto nella parte profili di questo post).


Adesso se apriamo la console di powershell e digitiamo i seguenti comandi

Get-Module ( vi verrà visualizzato il nostro modulo AuryTech)

Get-command -module AuryTech ( vi verranno visualizzati i cmdlet Send-Saluto e Send-Bacio)

Adesso potete utilizzare i vostri cmdlet del vostro modulo come se fossero dei cmdlet nativi della console di powershell.

Di volta in volta che produco un cmdlet provvederò ad inserirlo sul Blog.

Fine ;-)