Uso di Import-DSCResourceUsing Import-DSCResource

Import-DSCResource è una parola chiave dinamica che può essere usata solo all'interno di un blocco di script di configurazione per importare le risorse necessarie nella configurazione.Import-DSCResource is a dynamic keyword, which can only be used inside a Configuration script block to import any resources needed in your Configuration. Le risorse in $PSHOME vengono importate automaticamente, ma è comunque consigliabile importare in modo esplicito tutte le risorse usate nella configurazione.Resources under $PSHOME are imported automatically, but it is still considered best practice to explicitly import all resources used in your Configuration.

La sintassi per Import-DSCResource è illustrata di seguito.The syntax for Import-DSCResource is shown below. Quando si specificano moduli in base al nome, è necessario elencarne ognuno in una nuova riga.When specifying modules by name, it is a requirement to list each on a new line.

Import-DscResource [-Name <ResourceName(s)>] [-ModuleName <ModuleName>] [-ModuleVersion <ModuleVersion>]
ParametroParameter DescrizioneDescription
-Name Nome della risorsa DSC che è necessario importare.The DSC resource name(s) that you must import. Se viene specificato il nome del modulo, il comando cerca queste risorse DSC all'interno del modulo; in caso contrario, il comando cerca le risorse DSC in tutti i percorsi delle risorse DSC.If the module name is specified, the command searches for these DSC resources within this module; otherwise the command searches the DSC resources in all DSC resource paths. Sono supportati caratteri jolly.Wildcards are supported.
-ModuleName Nome del modulo o specifica del modulo.The module name, or module specification. Se si specificano risorse per l'importazione da un modulo, il comando tenterà di importare solo queste risorse.If you specify resources to import from a module, the command will try to import only those resources. Se si specifica solo il modulo, il comando importa tutte le risorse DSC nel modulo.If you specify the module only, the command imports all the DSC resources in the module.
-ModuleVersion A partire da PowerShell 5,0, è possibile specificare la versione di un modulo che deve essere usata da una configurazione.Beginning in PowerShell 5.0, you can specify which version of a module a configuration should use. Per altre informazioni, vedere Importare una versione specifica di una risorsa installata.For more information, see Import a specific version of an installed resource.
Import-DscResource -ModuleName xActiveDirectory

Esempio: Usare Import-DSCResource all'interno di una configurazioneExample: Use Import-DSCResource within a configuration

Configuration MSDSCConfiguration
{
    # Search for and imports Service, File, and Registry from the module PSDesiredStateConfiguration.
    Import-DSCResource -ModuleName PSDesiredStateConfiguration -Name Service, File, Registry

    # Search for and import Resource1 from the module that defines it.
    # If only –Name parameter is used then resources can belong to different PowerShell modules as well.
    # TimeZone resource is from the ComputerManagementDSC module which is not installed by default.
    # As a best practice, list each requirement on a different line if possible.  This makes reviewing
    # multiple changes in source control a bit easier.
    Import-DSCResource -Name File
    Import-DSCResource -Name TimeZone

    # Search for and import all DSC resources inside the module PSDesiredStateConfiguration.
    # When specifying the modulename parameter, it is a requirement to list each on a new line.
    Import-DSCResource -ModuleName PSDesiredStateConfiguration
    # In PowerShell 5.0 and later, you can specify a ModuleVersion parameter
    Import-DSCResource -ModuleName ComputerManagementDsc -ModuleVersion 6.0.0.0
...

Nota

Non è consentito specificare più valori per i nomi delle risorse e i nomi dei moduli nello stesso comando.Specifying multiple values for Resource names and modules names in same command are not supported. Può verificarsi un comportamento non deterministico sulla risorsa da caricare dal modulo cui nel caso in cui stessa risorsa sia presente in più moduli.It can have non-deterministic behavior about which resource to load from which module in case same resource exists in multiple modules. Il comando seguente genererà un errore durante la compilazione.Below command will result in error during compilation.

Import-DscResource -Name UserConfigProvider*,TestLogger1 -ModuleName UserConfigProv,PsModuleForTestLogger

Aspetti da considerare quando si usa solo il parametro Name:Things to consider when using only the Name parameter:

  • È un'operazione a elevato utilizzo di risorse in base al numero di moduli installati nel computer.It is a resource-intensive operation depending on the number of modules installed on machine.
  • Verrà caricata la prima risorsa trovata con il nome specificato.It will load the first resource found with the given name. Nel caso in cui sia installata più di una risorsa con lo stesso nome, potrebbe essere caricata la risorsa non corretta.In the case where there is more than one resource with same name installed, it could load the wrong resource.

L'utilizzo consigliato consiste nello specificare –ModuleName con il parametro -Name, come descritto di seguito.The recommended usage is to specify –ModuleName with the -Name parameter, as described below.

Questo utilizzo offre i vantaggi seguenti:This usage has the following benefits:

  • Riduce l'impatto sulle prestazioni, limitando l'ambito di ricerca per la risorsa specificata.It reduces the performance impact by limiting the search scope for the specified resource.
  • Definisce in modo esplicito il modulo di definizione della risorsa, garantendo il caricamento della risorsa corretta.It explicitly defines the module defining the resource, ensuring the correct resource is loaded.

Nota

In PowerShell 5.0, le risorse DSC possono avere più versioni e possono essere installate in un computer side-by-side.In PowerShell 5.0, DSC resources can have multiple versions, and versions can be installed on a computer side-by-side. Questo significa che più versioni di un modulo risorse sono disponibili nella stessa cartella di moduli.This is implemented by having multiple versions of a resource module that are contained in the same module folder. Per altre informazioni, vedere Uso di risorse con più versioni.For more information, see Using resources with multiple versions.

IntelliSense con Import-DSCResourceIntellisense with Import-DSCResource

Quando si crea la configurazione DSC in ISE, PowerShell fornisce IntelliSense per le risorse e le proprietà delle risorse.When authoring the DSC configuration in ISE, PowerShell provides IntelliSence for resources and resource properties. Le definizioni delle risorse nel percorso del modulo $pshome vengono caricate automaticamente.Resource definitions under the $pshome module path are loaded automatically. Quando si importano risorse con la parola chiave Import-DSCResource, le definizioni di risorse specificate vengono aggiunte e IntelliSense viene espanso per includere lo schema della risorsa importata.When you import resources using the Import-DSCResource keyword, the specified resource definitions are added and Intellisense is expanded to include the imported resource's schema.

IntelliSense in ISE per una risorsa DSC

Nota

A partire da PowerShell 5.0 è stato aggiunto il completamento tramite TAB a ISE per le risorse DSC e le relative proprietà.Beginning in PowerShell 5.0, tab completion was added to the ISE for DSC resources and their properties. Per altre informazioni, vedere Risorse.For more information, see Resources.

In fase di compilazione della configurazione, PowerShell usa le definizioni delle risorse importate per convalidare tutti i blocchi di risorse nella configurazione.When compiling the Configuration, PowerShell uses the imported resource definitions to validate all resource blocks in the configuration. Ogni blocco di risorse viene convalidato tramite definizione dello schema della risorsa per le regole seguenti.Each resource block is validated, using the resource's schema definition, for the following rules.

  • Vengono usate solo le proprietà definite nello schema.Only properties defined in schema are used.
  • I tipi di dati per ogni proprietà sono corretti.The data types for each property are correct.
  • Sono specificate le proprietà delle chiavi.Keys properties are specified.
  • Non viene usata alcuna proprietà di sola lettura.No read-only property is used.
  • La convalida sul valore esegue il mapping di tipi.Validation on value maps types.

Considerare la configurazione seguente:Consider the following configuration:

Configuration SchemaValidationInCorrectEnumValue
{
    # It is best practice to explicitly import all resources used in your Configuration.
    # This includes resources that are imported automatically, like WindowsFeature.
    Import-DSCResource -Name WindowsFeature
    Node localhost
    {
        WindowsFeature ROLE1
        {
            Name = "Telnet-Client"
            Ensure = "Invalid"
        }
    }
}

La compilazione di questa configurazione genera un errore.Compiling this Configuration results in an error.

PSDesiredStateConfiguration\WindowsFeature: At least one of the values 'Invalid' is not supported or
valid for property 'Ensure' on class 'WindowsFeature'. Please specify only supported values:
Present, Absent.

IntelliSense e la convalida dello schema consentono di rilevare più errori durante le fasi di analisi e compilazione, evitando complicazioni in fase di esecuzione.Intellisense and schema validation allow you to catch more errors during parse and compilation time, avoiding complications at run time.

Nota

Ogni risorsa DSC può avere un nome e un FriendlyName definito dallo schema della risorsa.Each DSC resource can have a name, and a FriendlyName defined by the resource's schema. Di seguito sono riportate le prime due righe di "MSFT_ServiceResource.shema.mof".Below are the first two lines of "MSFT_ServiceResource.shema.mof".

[ClassVersion("1.0.0"),FriendlyName("Service")]
class MSFT_ServiceResource : OMI_BaseResource

Quando si usa questa risorsa in una configurazione, è possibile specificare MSFT_ServiceResource o Service.When using this resource in a Configuration, you can specify MSFT_ServiceResource or Service.

Differenze tra PowerShell v4 e v5PowerShell v4 and v5 differences

Sussistono varie differenze nell'ambito della creazione di configurazioni in PowerShell 4.0 e PowerShell 5.0 e versioni successive.There are multiple differences you see when authoring Configurations in PowerShell 4.0 vs. PowerShell 5.0 and later. Questa sezione evidenzia le differenze pertinenti a questo articolo.This section will highlight the differences that you see relevant to this article.

Più versioni di risorseMultiple Resource Versions

L'installazione e l'utilizzo di più versioni di risorse affiancate non sono supportati in PowerShell 4.0.Installing and using multiple versions of resources side by side was not supported in PowerShell 4.0. Se si verificano problemi di importazione delle risorse nella configurazione, assicurarsi di avere solo una versione della risorsa installata.If you notice issues importing resources into your Configuration, ensure that you only have one version of the resource installed.

Nell'immagine seguente sono installare due versioni del modulo xPSDesiredStateConfiguration.In the image below, two versions of the xPSDesiredStateConfiguration module are installed.

Più versioni di risorse installate nella cartella

Copiare il contenuto della versione del modulo desiderata nel livello superiore della directory del modulo.Copy the contents of your desired module version to the top level of the module directory.

Copiare la versione desiderata nella directory del modulo di livello superiore

Posizione risorsaResource location

Durante la creazione e la compilazione di configurazioni, le risorse possono essere archiviate in qualsiasi directory specificata mediante PSModulePath.When authoring and compiling Configurations, your resources can be stored in any directory specified by your PSModulePath. In PowerShell 4.0, Gestione configurazione locale richiede che tutti i moduli delle risorse DSC siano archiviati in "Programmi\WindowsPowerShell\Modules" o $pshome\Modules.In PowerShell 4.0, the LCM requires all DSC resource modules to be stored under "Program Files\WindowsPowerShell\Modules" or $pshome\Modules. A partire da PowerShell 5.0, questo requisito è stato rimosso e i moduli delle risorse possono essere archiviati in qualsiasi directory specificata mediante PSModulePath.Beginning in PowerShell 5.0, this requirement was removed, and resource modules can be stored in any directory specified by PSModulePath.

Aggiunta di ModuleVersionModuleVersion added

A partire da PowerShell 5.0, il parametro -ModuleVersion consente di specificare la versione di un modulo da usare all'interno della configurazione.Beginning in PowerShell 5.0, the -ModuleVersion parameter allows you to specify which version of a module to use within your configuration.

Vedere ancheSee also