Partilhar via

Utilizar a palavra-chave Import-DSCResource

  • Artigo

Import-DSCResource é uma palavra-chave dinâmica, que só pode ser utilizada dentro de um bloco de script de Configuração para importar os recursos necessários na Configuração. Os recursos em $PSHOME são importados automaticamente, mas continua a ser considerada a melhor prática para importar explicitamente todos os recursos utilizados na configuração.

A sintaxe para Import-DSCResource é apresentada abaixo. Ao especificar módulos por nome, é um requisito listar cada um numa nova linha.

Import-DscResource [-Name <ResourceName(s)>] [-ModuleName <ModuleName>] [-ModuleVersion <ModuleVersion>]

Parâmetros

  • -Name - Os nomes de recursos do DSC que tem de importar. Se o nome do módulo for especificado, o comando procura estes recursos do DSC neste módulo; caso contrário, o comando procura os recursos do DSC em todos os caminhos de recursos do DSC. Os carateres universais são suportados.
  • -ModuleName - O nome do módulo ou a especificação do módulo. Se especificar recursos a importar a partir de um módulo, o comando tentará importar apenas esses recursos. Se especificar apenas o módulo, o comando importa todos os recursos do DSC no módulo.
  • -ModuleVersion - A partir do PowerShell 5.0, pode especificar a versão de um módulo que uma configuração deve utilizar. Para obter mais informações, veja Importar uma versão específica de um recurso instalado.
Import-DscResource -ModuleName xActiveDirectory

Exemplo: Utilizar Import-DSCResource numa configuração

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

A especificação de vários valores para nomes de recursos e nomes de módulos no mesmo comando não é suportada. Pode ter um comportamento não determinista sobre o recurso a carregar a partir do qual o módulo, caso exista o mesmo recurso em vários módulos. O comando abaixo resultará num erro durante a compilação.

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

Aspetos a ter em conta ao utilizar apenas o parâmetro Nome:

  • Trata-se de uma operação de utilização intensiva de recursos, consoante o número de módulos instalados no computador.
  • Carregará o primeiro recurso encontrado com o nome especificado. No caso de existir mais do que um recurso com o mesmo nome instalado, pode carregar o recurso errado.

A utilização recomendada é especificar –ModuleName com o -Name parâmetro, conforme descrito abaixo.

Esta utilização tem os seguintes benefícios:

  • Reduz o impacto no desempenho ao limitar o âmbito de pesquisa do recurso especificado.
  • Define explicitamente o módulo que define o recurso, garantindo que o recurso correto é carregado.

Nota

No PowerShell 5.0, os recursos do DSC podem ter várias versões e as versões podem ser instaladas lado a lado num computador. Isto é implementado ao ter várias versões de um módulo de recursos que estão contidas na mesma pasta de módulo. Para obter mais informações, veja Utilizar recursos com várias versões.

Intellisense com Import-DSCResource

Ao criar a configuração do DSC no ISE, o PowerShell fornece o IntelliSense para recursos e propriedades de recursos. As definições de recursos no caminho do $pshome módulo são carregadas automaticamente. Quando importa recursos com a Import-DSCResource palavra-chave, as definições de recursos especificadas são adicionadas e o Intellisense é expandido para incluir o esquema do recurso importado.

Intellisense no ISE para um Recurso DSC

Nota

A partir do PowerShell 5.0, a conclusão do separador foi adicionada ao ISE para recursos do DSC e às respetivas propriedades. Para obter mais informações, veja Recursos.

Ao compilar a Configuração, o PowerShell utiliza as definições de recursos importados para validar todos os blocos de recursos na configuração. Cada bloco de recursos é validado, utilizando a definição de esquema do recurso, para as seguintes regras.

  • São utilizadas apenas as propriedades definidas no esquema.
  • Os tipos de dados para cada propriedade estão corretos.
  • As propriedades das chaves são especificadas.
  • Não é utilizada nenhuma propriedade só de leitura.
  • Validação em tipos de mapas de valores.

Considere a seguinte configuração:

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"
        }
    }
}

A compilação desta Configuração resulta num erro.

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.

O Intellisense e a validação do esquema permitem-lhe detetar mais erros durante o tempo de análise e compilação, evitando complicações no tempo de execução.

Nota

Cada recurso DSC pode ter um nome e um FriendlyName definido pelo esquema do recurso. Seguem-se as duas primeiras linhas de "MSFT_ServiceResource.shema.mof".

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

Ao utilizar este recurso numa Configuração, pode especificar MSFT_ServiceResource ou Serviço.

Diferenças do PowerShell v4 e v5

Existem várias diferenças que pode ver ao criar Configurações no PowerShell 4.0 vs. PowerShell 5.0 e posterior. Esta secção irá realçar as diferenças que vê relevantes para este artigo.

Várias Versões de Recursos

A instalação e utilização de várias versões de recursos lado a lado não foi suportada no PowerShell 4.0. Se notar problemas ao importar recursos para a Configuração, certifique-se de que tem apenas uma versão do recurso instalada.

Na imagem abaixo, são instaladas duas versões do módulo xPSDesiredStateConfiguration .

Várias Versões de Recursos instaladas na pasta

Copie o conteúdo da versão do módulo pretendida para o nível superior do diretório do módulo.

Copiar a versão pretendida para o diretório do módulo de nível superior

Localização do recurso

Ao criar e compilar Configurações, os seus recursos podem ser armazenados em qualquer diretório especificado pelo seu PSModulePath. No PowerShell 4.0, o LCM requer que todos os módulos de recursos do DSC sejam armazenados em "Programas\WindowsPowerShell\Modules" ou $pshome\Modules. A partir do PowerShell 5.0, este requisito foi removido e os módulos de recursos podem ser armazenados em qualquer diretório especificado pelo PSModulePath.

ModuleVersion adicionado

A partir do PowerShell 5.0, o -ModuleVersion parâmetro permite-lhe especificar a versão de um módulo a utilizar na sua configuração.

Ver também