Usando o Import-DSCResource
Aplica-se a: PowerShell 7, recurso de configuração de computador do Gerenciamento Automatizado do Azure
Import-DSCResourceé uma palavra-chave dinâmica, que só pode ser usada dentro de um Configuration bloco para importar todos os recursos necessários em sua Configuração de DSC. Os recursos de DSC em $PSHOME são importados automaticamente, mas é uma prática recomendada importar explicitamente todos os recursos de DSC usados em sua configuração de DSC.
A sintaxe para Import-DSCResource é mostrada abaixo. Ao especificar módulos por nome, é necessário listar cada um em uma nova linha.
Import-DscResource [-Name <ResourceName(s)>]
[-ModuleName <ModuleName>]
[-ModuleVersion <ModuleVersion>]
Parâmetros
- Nome – Os recursos que você deve importar. Se o nome do módulo for especificado, o comando procurará esses recursos DSC dentro desse módulo; caso contrário, o comando pesquisa os Recursos DSC em todos os módulos. Há suporte para caracteres curinga.
- ModuleName – o nome do módulo ou a especificação do módulo. Se você especificar recursos de DSC para importar de um módulo, o comando tentará importar apenas esses recursos de DSC. Se você especificar apenas o módulo, o comando importará todos os Recursos DSC no módulo.
- ModuleVersion – você pode especificar a versão de um módulo que uma configuração deve usar com esse parâmetro. Por padrão, a versão mais recente disponível do recurso DSC é importada.
Import-DSCResource -ModuleName xActiveDirectory
Exemplo: usar Import-DSCResource dentro de uma configuração de DSC
Configuration MSDSCConfiguration {
# Search for and imports two DSC Resources from the PSDscResources module.
Import-DSCResource -ModuleName PSDscResources -Name Service, Registry
# Search for and import Resource1 from the module that defines it. If only
# the -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 Service
Import-DSCResource -Name TimeZone
# Search for and import all DSC resources inside the PSDscResources module.
# When specifying the ModuleName parameter, it is a requirement to list each
# on a new line.
Import-DSCResource -ModuleName PSDscResources
# You can specify a ModuleVersion parameter
Import-DSCResource -ModuleName ComputerManagementDsc -ModuleVersion 6.0.0.0
...
Observação
Não há suporte para a especificação de vários valores para nomes de recursos e nomes de módulos de DSC no mesmo comando. Ele pode ter um comportamento não determinístico sobre qual recurso DSC carregar de qual módulo se o mesmo recurso DSC existir em vários módulos. O comando a seguir retorna um erro em durante a compilação.
Import-DSCResource -Name Service, TimeZone -ModuleName PSDscResources, xPSDesiredStateConfiguration
Coisas a serem consideradas ao usar apenas o parâmetro Name :
- É uma operação com uso intensivo de recursos, dependendo do número de módulos instalados no computador.
- Ele carrega o primeiro recurso DSC encontrado com o nome fornecido. Se houver mais de um recurso DSC com o mesmo nome instalado, ele poderá carregar o recurso DSC errado.
O uso recomendado é especificar ModuleName com o parâmetro Name , conforme descrito abaixo.
Esse uso oferece os seguintes benefícios:
- Ele reduz o impacto no desempenho limitando o escopo de pesquisa para o recurso de DSC especificado.
- Ele define explicitamente o módulo que fornece o recurso DSC, garantindo que o recurso DSC correto seja carregado.
Observação
Os recursos de DSC podem ter várias versões e as versões podem ser instaladas em um computador lado a lado. Isso é implementado com várias versões de um módulo de recurso DSC contidos na mesma pasta de módulo.
IntelliSense com Import-DSCResource
Ao criar a Configuração de DSC no VS Code, o PowerShell fornece o IntelliSense para recursos DSC e propriedades de recurso DSC. Definições de recurso sob o caminho do módulo $PSHOME são carregados automaticamente. Quando você importa recursos de DSC usando o Import-DSCResource palavra-chave, as definições de recurso DSC especificadas são adicionadas e o IntelliSense é expandido para incluir os esquemas dos recursos de DSC importados.
Ao compilar a Configuração de DSC, o PowerShell usa as definições de recurso de DSC importadas para validar os blocos de recursos do DSC no Configuration bloco. Cada bloco de recurso DSC é validado pela definição de esquema do Recurso DSC para as seguintes regras:
- Somente as propriedades definidas no esquema são especificadas.
- Os tipos de dados de cada propriedade estão corretos.
- As propriedades-chave estão especificadas.
- Nenhuma propriedade somente leitura é especificada.
Considere a seguinte configuração de DSC:
Configuration SchemaValidationInCorrectEnumValue {
Import-DSCResource -Name User -Module PSDscResources
User ExampleUser {
UserName = 'ExampleDscUser'
Ensure = 'Invalid'
}
}
Compilar essa Configuração de DSC resulta em um erro.
Write-Error: C:\code\dsc\sample.ps1:4:5
Line |
4 | User ExampleUser {
| ~~~~
| At least one of the values 'Invalid' is not supported or
| valid for property 'Ensure' on class 'User'. Please specify
| only supported values: Present, Absent.
InvalidOperation: Errors occurred while processing configuration
'SchemaValidationInCorrectEnumValue'.
O IntelliSense e a validação de esquema permitem capturar mais erros durante o tempo de análise e compilação, evitando complicações futuras.
Observação
Cada recurso DSC pode ter um nome e um FriendlyName definidos pelo esquema do recurso DSC.
Abaixo estão as duas primeiras linhas de MSFT_UserResource.schema.mof.
[ClassVersion("1.0.0"), FriendlyName("User")]
class MSFT_UserResource : OMI_BaseResource
Ao usar esse recurso DSC em um Configuration bloco, você pode especificar MSFT_UserResource ou User.
