Recursos de composição: usando uma configuração DSC como um recursoComposite resources: Using a DSC configuration as a resource

Aplica-se a: Windows PowerShell 4.0, Windows PowerShell 5.0Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

Em situações reais, as configurações podem se tornar longas e complexas, chamando muitos recursos diferentes e definindo um grande número de propriedades.In real-world situations, configurations can become long and complex, calling many different resources and setting a vast number of properties. Para ajudar a resolver essa complexidade, é possível usar uma configuração do tipo Configuração de Estado Desejado (DSC) do Windows PowerShell como um recurso para outras configurações.To help address this complexity, you can use a Windows PowerShell Desired State Configuration (DSC) configuration as a resource for other configurations. Chamamos isso de recurso de composição.We call this a composite resource. Um recurso de composição é uma configuração DSC que usa parâmetros.A composite resource is a DSC configuration that takes parameters. Os parâmetros da configuração atuam como as propriedades do recurso.The parameters of the configuration act as the properties of the resource. A configuração é salva como um arquivo com uma extensão . schema.psm1 e assume o lugar do esquema MOF e do script de recurso em um recurso típico de DSC (para obter mais informações sobre os recursos de DSC, consulte Recursos de Configuração de Estado Desejado do Windows PowerShell.The configuration is saved as a file with a .schema.psm1 extension, and takes the place of both the MOF schema and the resource script in a typical DSC resource (for more information about DSC resources, see Windows PowerShell Desired State Configuration Resources.

Criando o recurso de composiçãoCreating the composite resource

Em nosso exemplo, criamos uma configuração que invoca uma série de recursos existentes para configurar máquinas virtuais.In our example, we create a configuration that invokes a number of existing resources to configure virtual machines. Em vez de especificar os valores a serem definidos em blocos de configuração, a configuração pega uma série de parâmetros que são usados nos blocos de configuração.Instead of specifying the values to be set in configuration blocks, the configuration takes a number of parameters that are then used in the configuration blocks.

Configuration xVirtualMachine
{
    param
    (
        # Name of VMs
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String[]] $VMName,

        # Name of Switch to create
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String] $SwitchName,

        # Type of Switch to create
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String] $SwitchType,

        # Source Path for VHD
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String] $VHDParentPath,

        # Destination path for diff VHD
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String] $VHDPath,

        # Startup Memory for VM
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String] $VMStartupMemory,

        # State of the VM
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String] $VMState
    )

    # Import the module that defines custom resources
    Import-DscResource -Module xComputerManagement,xHyper-V

    # Install the Hyper-V role
    WindowsFeature HyperV
    {
        Ensure = "Present"
        Name = "Hyper-V"
    }

    # Create the virtual switch
    xVMSwitch $SwitchName
    {
        Ensure = "Present"
        Name = $SwitchName
        Type = $SwitchType
        DependsOn = "[WindowsFeature]HyperV"
    }

    # Check for Parent VHD file
    File ParentVHDFile
    {
        Ensure = "Present"
        DestinationPath = $VHDParentPath
        Type = "File"
        DependsOn = "[WindowsFeature]HyperV"
    }

    # Check the destination VHD folder
    File VHDFolder
    {
        Ensure = "Present"
        DestinationPath = $VHDPath
        Type = "Directory"
        DependsOn = "[File]ParentVHDFile"
    }

    # Creae VM specific diff VHD
    foreach ($Name in $VMName)
    {
        xVHD "VHD$Name"
        {
            Ensure = "Present"
            Name = $Name
            Path = $VHDPath
            ParentPath = $VHDParentPath
            DependsOn = @("[WindowsFeature]HyperV",
                          "[File]VHDFolder")
        }
    }

    # Create VM using the above VHD
    foreach($Name in $VMName)
    {
        xVMHyperV "VMachine$Name"
        {
            Ensure = "Present"
            Name = $Name
            VhDPath = (Join-Path -Path $VHDPath -ChildPath $Name)
            SwitchName = $SwitchName
            StartupMemory = $VMStartupMemory
            State = $VMState
            MACAddress = $MACAddress
            WaitForIP = $true
            DependsOn = @("[WindowsFeature]HyperV",
                          "[xVHD]VHD$Name")
        }
    }
}

Salvando a configuração como um recurso de composiçãoSaving the configuration as a composite resource

Para usar a configuração com parâmetros como um recurso de DSC, salve-a em uma estrutura de diretórios semelhante à de qualquer outro recurso baseado em MOF e nomeie-a com uma extensão . schema.psm1.To use the parameterized configuration as a DSC resource, save it in a directory structure like that of any other MOF-based resource, and name it with a .schema.psm1 extension. Para esse exemplo, chamaremos o arquivo de xVirtualMachine.schema.psm1.For this example, we’ll name the file xVirtualMachine.schema.psm1. Você também precisa criar um manifesto chamado xVirtualMachine.psd1, que contém a linha a seguir.You also need to create a manifest named xVirtualMachine.psd1 that contains the following line. Observe que este se soma ao MyDscResources.psd1, o manifesto de módulo para todos os recursos na pasta MyDscResources.Note that this is in addition to MyDscResources.psd1, the module manifest for all resources under the MyDscResources folder.

RootModule = 'xVirtualMachine.schema.psm1'

Quando terminar, a estrutura de pastas deve ser a seguinte.When you are done, the folder structure should be as follows.

$env: psmodulepath
    |- MyDscResources
           MyDscResources.psd1
        |- DSCResources
            |- xVirtualMachine
                |- xVirtualMachine.psd1
                |- xVirtualMachine.schema.psm1

O recurso é detectável usando o cmdlet Get-DscResource; suas propriedades são detectáveis por meio desse cmdlet ou usando o preenchimento automático com Ctrl + espaço no ISE do Windows PowerShell.The resource is now discoverable by using the Get-DscResource cmdlet, and its properties are discoverable by either that cmdlet or by using Ctrl+Space auto-complete in the Windows PowerShell ISE.

Usando o recurso de composiçãoUsing the composite resource

Em seguida, criamos uma configuração que chama o recurso de composição.Next we create a configuration that calls the composite resource. Essa configuração chama o recurso de composição xVirtualMachine para criar uma máquina virtual e, em seguida, chama o recurso xComputer para renomeá-lo.This configuration calls the xVirtualMachine composite resource to create a virtual machine, and then calls the xComputer resource to rename it.


configuration RenameVM
{

    Import-DscResource -Module TestCompositeResource
    Node localhost
    {
        xVirtualMachine VM
        {
            VMName = "Test"
            SwitchName = "Internal"
            SwitchType = "Internal"
            VhdParentPath = "C:\Demo\VHD\RTM.vhd"
            VHDPath = "C:\Demo\VHD"
            VMStartupMemory = 1024MB
            VMState = "Running"
        }
    }

    Node "192.168.10.1"
    {
        xComputer Name
        {
            Name = "SQL01"
            DomainName = "fourthcoffee.com"
        }
    }
}

Dando suporte a PsDscRunAsCredentialSupporting PsDscRunAsCredential

Observação: PsDscRunAsCredential tem suporte no PowerShell 5.0 e posterior.Note: PsDscRunAsCredential is supported in PowerShell 5.0 and later.

A propriedade PsDscRunAsCredential pode ser usada no bloco de recurso Configurações DSC para especificar que o recurso deve ser executado em um conjunto de credenciais específico.The PsDscRunAsCredential property can be used in DSC configurations resource block to specify that the resource should be run under a specified set of credentials. Para obter mais informações, veja Executando o DSC com as credenciais do usuário.For more information, see Running DSC with user credentials.

Para acessar o contexto do usuário de dentro de um recurso personalizado, você pode usar a variável automática $PsDscContext.To access the user context from within a custom resource, you can use the automatic variable $PsDscContext.

Por exemplo, o código a seguir escreveria o contexto do usuário em que o recurso está em execução para o fluxo de saída detalhada:For example the following code would write the user context under which the resource is running to the verbose output stream:

if (PsDscContext.RunAsUser) {
    Write-Verbose "User: $PsDscContext.RunAsUser";
}

Consulte TambémSee Also

ConceitosConcepts