Creare un fornitore di proprietà PowerShell per Windows

Questo argomento descrive come creare un provider che consenta all'utente di manipolare le proprietà degli elementi in un archivio dati. Di conseguenza, questo tipo di provider è chiamato provider di proprietà Windows PowerShell. Ad esempio, il provider del registro fornito da Windows PowerShell gestisce i valori chiave del registro come proprietà dell'elemento chiave del registro. Questo tipo di provider deve aggiungere l'interfaccia System.Management.Automation.Provider.IPropertyCmdletProvider all'implementazione della classe .NET.

Annotazioni

Windows PowerShell fornisce un file modello che puoi utilizzare per sviluppare un provider PowerShell per Windows. Il file TemplateProvider.cs è disponibile nel Microsoft Windows Software Development Kit per Windows Vista e .NET Framework 3.0 Runtime Components. Per le istruzioni per il download, consulta Come installare Windows PowerShell e scaricare l'SDK di Windows PowerShell. Il template scaricato è disponibile nella <directory PowerShell Samples> . Dovresti fare una copia di questo file e usarla per creare un nuovo provider PowerShell di Windows, eliminando qualsiasi funzionalità non necessaria. Per maggiori informazioni su altre implementazioni di provider PowerShell di Windows, vedi Progettare il tuo provider PowerShell Windows.

Attenzione

I metodi del tuo fornitore immobiliare dovrebbero scrivere qualsiasi oggetto utilizzando il metodo System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* .

Definizione del provider PowerShell di Windows

Un provider immobiliare deve creare una classe .NET che supporti l'interfaccia System.Management.Automation.Provider.IPropertyCmdletProvider . Ecco la dichiarazione di classe predefinita dal file TemplateProvider.cs fornito da Windows PowerShell.

Definizione della funzionalità di base

L'interfaccia System.Management.Automation.Provider.IPropertyCmdletProvider può essere collegata a qualsiasi classe base provider, ad eccezione della classe System.Management.Automation.Provider.DriveCmdletProvider . Aggiungi la funzionalità di base richiesta dalla classe base che stai usando. Per maggiori informazioni sulle classi base, vedi Progettare il tuo provider PowerShell Windows.

Recupero delle proprietà

Per recuperare proprietà, il provider deve implementare il metodo System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* per supportare le chiamate dal Get-ItemProperty cmdlet. Questo metodo recupera le proprietà dell'elemento situato nel percorso fornitore-interno specificato (completamente qualificato).

Il parametro providerSpecificPickList indica quali proprietà recuperare. Se questo parametro è null o vuoto, il metodo dovrebbe recuperare tutte le proprietà. Inoltre, System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* scrive un'istanza di un oggetto System.Management.Automation.PSObject che rappresenta una borsa di proprietà delle proprietà recuperate. Il metodo non dovrebbe restituire nulla.

Si raccomanda che l'implementazione di System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* supporti l'espansione jolly dei nomi delle proprietà per ogni elemento nella lista di scelta. Per farlo, usa la classe System.Management.Automation.WildcardPattern per eseguire l'abbinamento dei modelli jolly.

Ecco l'implementazione predefinita di System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* dal file TemplateProvider.cs fornito da Windows PowerShell.

Cose da ricordare sull'implementazione di GetProperty

Le seguenti condizioni possono applicarsi alla tua implementazione di System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*:

Quando si definisce la classe provider, un provider di proprietà PowerShell di Windows potrebbe dichiarare le capacità del provider di ExpandWildcards, Filter, Include o Exclude, dall'enumerazione System.Management.Automation.Provider.ProviderCapabilities . In questi casi, l'implementazione del metodo System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* deve garantire che il percorso passato al metodo soddisfi i requisiti delle capacità specificate. Per farlo, il metodo dovrebbe accedere alla proprietà appropriata, ad esempio le proprietà System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* proprietà.
Di default, gli override di questo metodo non dovrebbero recuperare un lettore per oggetti nascosti all'utente a meno che la proprietà System.Management.Automation.Provider.CmdletProvider.Force * non sia impostata su true. Un errore dovrebbe essere scritto se il percorso rappresenta un elemento nascosto all'utente e System.Management.Automation.Provider.CmdletProvider.Force* è impostato su false.

Attacco dei parametri dinamici al Get-ItemProperty cmdlet

Il Get-ItemProperty cmdlet potrebbe richiedere parametri aggiuntivi specificati dinamicamente a runtime. Per fornire questi parametri dinamici, il provider di proprietà PowerShell di Windows deve implementare il metodo System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* . Il parametro path indica un percorso interno provider completamente qualificato, mentre il parametro providerSpecificPickList specifica le proprietà specifiche del provider inserite nella riga di comando. Questo parametro potrebbe essere null o vuoto se le proprietà sono inviate al cmdlet. In questo caso, questo metodo restituisce un oggetto che possiede proprietà e campi con attributi di parsing simili a una classe cmdlet o a un oggetto System.Management.Automation.RuntimeDefinedParameterDictionary . L'runtime di Windows PowerShell utilizza l'oggetto restituito per aggiungere i parametri al cmdlet.

Ecco l'implementazione predefinita di System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* dal file TemplateProvider.cs fornito da Windows PowerShell.

Impostazione delle proprietà

Per impostare le proprietà, il provider di proprietà PowerShell di Windows deve implementare il metodo System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* per supportare le chiamate dal Set-ItemProperty cmdlet. Questo metodo imposta una o più proprietà dell'elemento nel percorso specificato e sovrascrive le proprietà fornite secondo necessità. System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* scrive anche un'istanza di un oggetto System.Management.Automation.PSObject che rappresenta una cartella delle proprietà aggiornate.

Ecco l'implementazione predefinita di System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* dal file TemplateProvider.cs fornito da Windows PowerShell.

Cose da ricordare sull'implementazione delle Set-ItemProperty

Le seguenti condizioni possono applicarsi a un'implementazione di System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*:

Quando si definisce la classe provider, un provider di proprietà PowerShell di Windows potrebbe dichiarare le capacità del provider di ExpandWildcards, Filter, Include o Exclude, dall'enumerazione System.Management.Automation.Provider.ProviderCapabilities . In questi casi, l'implementazione del metodo System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* deve garantire che il percorso passato al metodo soddisfi i requisiti delle capacità specificate. Per farlo, il metodo dovrebbe accedere alla proprietà appropriata, ad esempio le proprietà System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* proprietà.
Di default, gli override di questo metodo non dovrebbero recuperare un lettore per oggetti nascosti all'utente a meno che la proprietà System.Management.Automation.Provider.CmdletProvider.Force * non sia impostata su true. Un errore dovrebbe essere scritto se il percorso rappresenta un elemento nascosto all'utente e System.Management.Automation.Provider.CmdletProvider.Force* è impostato su false.
La tua implementazione del metodo System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* dovrebbe chiamare System.Management.Automation.Provider.CmdletProvider.ShouldProcess e verificare il suo valore di ritorno prima di apportare qualsiasi modifica allo store dati. Questo metodo viene utilizzato per confermare l'esecuzione di un'operazione quando viene effettuata una modifica allo stato del sistema, ad esempio rinominando file. System.Management.Automation.Provider.CmdletProvider.ShouldProcess invia il nome della risorsa da cambiare all'utente, con l'runtime di Windows PowerShell e gestendo eventuali impostazioni da riga di comando o variabili di preferenza per determinare cosa deve essere visualizzato.

Dopo il ritorno truedella chiamata a System.Management.Automation.Provider.CmdletProvider.ShouldProcess , se si possono effettuare modifiche potenzialmente pericolose al sistema, il metodo System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* dovrebbe chiamare il metodo System.Management.Automation.Provider.CmdletProvider.ShouldContinue. Questo metodo invia un messaggio di conferma all'utente per permettere ulteriori feedback che indichino che l'operazione dovrebbe continuare.

Aggiunta dei parametri dinamici per il cmdlet Set-ItemProperty

Il Set-ItemProperty cmdlet potrebbe richiedere parametri aggiuntivi specificati dinamicamente a runtime. Per fornire questi parametri dinamici, il provider di proprietà PowerShell di Windows deve implementare il metodo System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* . Questo metodo restituisce un oggetto che possiede proprietà e campi con attributi di analisi analoghe a una classe cmdlet o a un oggetto System.Management.Automation.RuntimeDefinedParameterDictionary . Il null valore può essere restituito se non si aggiungono parametri dinamici.

Ecco l'implementazione predefinita di System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* dal file TemplateProvider.cs fornito da Windows PowerShell.

Proprietà di Clearing

Per liberare le proprietà, il provider di proprietà PowerShell di Windows deve implementare il metodo System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* per supportare le chiamate dal Clear-ItemProperty cmdlet. Questo metodo stabilisce una o più proprietà per l'oggetto situato sul percorso specificato.

Ecco l'implementazione predefinita di System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* dal file TemplateProvider.cs fornito da Windows PowerShell.

Cosa da ricordare sull'implementazione di ClearProperty

Le seguenti condizioni possono applicarsi alla tua implementazione di System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*:

Quando si definisce la classe provider, un provider di proprietà PowerShell di Windows potrebbe dichiarare le capacità del provider di ExpandWildcards, Filter, Include o Exclude, dall'enumerazione System.Management.Automation.Provider.ProviderCapabilities . In questi casi, l'implementazione del metodo System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* deve garantire che il percorso passato al metodo soddisfi i requisiti delle capacità specificate. Per farlo, il metodo dovrebbe accedere alla proprietà appropriata, ad esempio le proprietà System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* proprietà.
Di default, gli override di questo metodo non dovrebbero recuperare un lettore per oggetti nascosti all'utente a meno che la proprietà System.Management.Automation.Provider.CmdletProvider.Force * non sia impostata su true. Un errore dovrebbe essere scritto se il percorso rappresenta un elemento nascosto all'utente e System.Management.Automation.Provider.CmdletProvider.Force* è impostato su false.
La tua implementazione del metodo System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* dovrebbe chiamare System.Management.Automation.Provider.CmdletProvider.ShouldProcess e verificare il valore di ritorno prima di apportare qualsiasi modifica allo store dati. Questo metodo viene utilizzato per confermare l'esecuzione di un'operazione prima che venga apportato un cambiamento allo stato del sistema, come la cancellazione del contenuto. System.Management.Automation.Provider.CmdletProvider.ShouldProcess invia il nome della risorsa da cambiare all'utente, con l'runtime di Windows PowerShell che tiene conto di eventuali impostazioni da riga di comando o variabili di preferenza nel determinare cosa deve essere visualizzato.

Dopo il ritorno truedella chiamata a System.Management.Automation.Provider.CmdletProvider.ShouldProcess, se possono essere apportate modifiche potenzialmente pericolose al sistema, il metodo System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* dovrebbe chiamare il metodo System.Management.Automation.Provider.CmdletProvider.ShouldContinue. Questo metodo invia un messaggio di conferma all'utente per consentire ulteriori feedback che indichino che l'operazione potenzialmente pericolosa dovrebbe continuare.

Attacco dei parametri dinamici al Clear-ItemProperty cmdlet

Il Clear-ItemProperty cmdlet potrebbe richiedere parametri aggiuntivi specificati dinamicamente a runtime. Per fornire questi parametri dinamici, il provider di proprietà PowerShell di Windows deve implementare il metodo System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* . Questo metodo restituisce un oggetto che possiede proprietà e campi con attributi di analisi analoghe a una classe cmdlet o a un oggetto System.Management.Automation.RuntimeDefinedParameterDictionary . Il null valore può essere restituito se non si aggiungono parametri dinamici.

Ecco l'implementazione predefinita di System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* dal file TemplateProvider.cs fornito da Windows PowerShell.