Configurações parciais da Configuração de Estado Desejado do PowerShellPowerShell Desired State Configuration partial configurations

Aplica-se a: Windows PowerShell 5.0 e posterior.Applies To: Windows PowerShell 5.0 and later.

No PowerShell 5.0, a Configuração de Estado Desejado (DSC) permite que as configurações sejam entregues em fragmentos e de várias fontes.In PowerShell 5.0, Desired State Configuration (DSC) allows configurations to be delivered in fragments and from multiple sources. O Gerenciador de Configurações Local (LCM) no nó de destino reúne os fragmentos antes de aplicá-los como uma única configuração.The Local Configuration Manager (LCM) on the target node puts the fragments together before applying them as a single configuration. Essa capacidade permite compartilhar o controle de configuração entre equipes ou pessoas.This capability allows sharing control of configuration between teams or individuals. Por exemplo, se duas ou mais equipes de desenvolvedores estiverem colaborando em um serviço, cada uma poderá querer criar configurações para gerenciar sua parte do serviço.For example, if two or more teams of developers are collaborating on a service, they might each want to create configurations to manage their part of the service. Cada uma dessas configurações pode ser extraída de servidores de pull diferentes e adicionada em diferentes estágios do desenvolvimento.Each of these configurations could be pulled from different pull servers, and they could be added at different stages of development. Configurações parciais também permitem que diferentes pessoas ou equipes controlem diferentes aspectos da configuração de nós sem a necessidade de coordenar a edição de um documento único de configuração.Partial configurations also allow different individuals or teams to control different aspects of configuring nodes without having to coordinate the editing of a single configuration document. Por exemplo, uma equipe pode ser responsável por implantar uma VM e o sistema operacional, enquanto outra equipe pode implantar outros aplicativos e serviços em tal VM.For example, one team might be responsible for deploying a VM and operating system, while another team might deploy other applications and services on that VM. Com configurações parciais, cada equipe pode criar sua própria configuração, sem complicações desnecessárias.With partial configurations, each team can create its own configuration, without either of them being unnecessarily complicated.

É possível usar configurações parciais no modo de push, no modo de pull ou em uma combinação de ambos.You can use partial configurations in push mode, pull mode, or a combination of the two.

Configurações parciais no modo de pushPartial configurations in push mode

Para usar configurações parciais no modo de push, o LCM é configurado no nó de destino para receber as configurações parciais.To use partial configurations in push mode, you configure the LCM on the target node to receive the partial configurations. Cada configuração parcial deve ser enviada por push para o destino usando o cmdlet Publish-DSCConfiguration.Each partial configuration must be pushed to the target by using the Publish-DSCConfiguration cmdlet. Em seguida, o nó de destino combina a configuração parcial em uma única configuração; pode-se aplicar a configuração chamando o cmdlet Start-DscConfiguration.The target node then combines the partial configuration into a single configuration, and you can apply the configuration by calling the Start-DscConfiguration cmdlet.

Configurando o LCM para configurações parciais no modo de pushConfiguring the LCM for push-mode partial configurations

Para configurar o LCM para configurações parciais no modo de push, é criada uma configuração DSCLocalConfigurationManager com um bloco PartialConfiguration para cada configuração parcial.To configure the LCM for partial configurations in push mode, you create a DSCLocalConfigurationManager configuration with one PartialConfiguration block for each partial configuration. Para obter mais informações sobre como configurar o LCM, consulte Configurando o Gerenciador de Configurações Local com o Windows.For more information about configuring the LCM, see Windows Configuring the Local Configuration Manager. O exemplo a seguir mostra uma configuração do LCM que espera duas configurações parciais—uma que implanta o sistema operacional e outra que implanta e configura o SharePoint.The following example shows an LCM configuration that expects two partial configurations—one that deploys the OS, and one that deploys and configures SharePoint.

[DSCLocalConfigurationManager()]
configuration PartialConfigDemo
{
    Node localhost
    {

           PartialConfiguration ServiceAccountConfig
        {
            Description = 'Configuration to add the SharePoint service account to the Administrators group.'
            RefreshMode = 'Push'
        }
           PartialConfiguration SharePointConfig
        {
            Description = 'Configuration for the SharePoint server'
            RefreshMode = 'Push'
        }
    }
}
PartialConfigDemo 

O RefreshMode para cada configuração parcial é definido como "Push".The RefreshMode for each partial configuration is set to "Push". Os nomes dos blocos PartialConfiguration (nesse caso, “ServiceAccountConfig” e “SharePointConfig”) devem corresponder exatamente aos nomes das configurações que são enviados por push para o nó de destino.The names of the PartialConfiguration blocks (in this case, "ServiceAccountConfig" and "SharePointConfig") must match exactly the names of the configurations that are pushed to the target node.

Observação: o nome de cada bloco PartialConfiguration deve corresponder ao nome real da configuração conforme especificado no script de configuração e não o nome do arquivo MOF, que deve ser o nome do nó de destino ou localhost.Note: The named of each PartialConfiguration block must match the actual name of the configuration as it is specified in the configuration script, not the name of the MOF file, which should be either the name of the target node or localhost.

Publicando e iniciando configurações parciais no modo de pushPublishing and starting push-mode partial configurations

A seguir, chame Publish-DSCConfiguration para cada configuração, passando as pastas que contêm os documentos de configuração como os parâmetros Path.You then call Publish-DSCConfiguration for each configuration, passing the folders that contain the configuration documents as the Path parameters. O Publish-DSCConfiguration coloca os arquivos MOF de configuração para os nós de destino.Publish-DSCConfigurationplaces the configuration MOF files to the target nodes. Depois de publicar as duas configurações, é possível chamar Start-DSCConfiguration –UseExisting no nó de destino.After publishing both configurations, you can call Start-DSCConfiguration –UseExisting on the target node.

Por exemplo, se você compilou os seguintes documentos MOF de configuração no nó de criação:For example, if you have compiled the following configuration MOF documents on the authoring node:

PS C:\PartialConfigTest> Get-ChildItem -Recurse


    Directory: C:\PartialConfigTest


Mode                LastWriteTime         Length Name                                                                                                                                         
----                -------------         ------ ----                                                                                                                                         
d-----        8/11/2016   1:55 PM                ServiceAccountConfig                                                                                                                  
d-----       11/17/2016   4:14 PM                SharePointConfig                                                                                                                                    


    Directory: C:\PartialConfigTest\ServiceAccountConfig


Mode                LastWriteTime         Length Name                                                                                                                                         
----                -------------         ------ ----                                                                                                                                         
-a----        8/11/2016   2:02 PM           2034 TestVM.mof                                                                                                                                


    Directory: C:\DscTests\SharePointConfig


Mode                LastWriteTime         Length Name                                                                                                                                         
----                -------------         ------ ----                                                                                                                                         
-a----       11/17/2016   4:14 PM           1930 TestVM.mof                                                                                                                                     

É necessário publicar e executar as configurações da seguinte maneira:You would publish and run the configurations as follows:

PS C:\PartialConfigTest> Publish-DscConfiguration .\ServiceAccountConfig -ComputerName 'TestVM'
PS C:\PartialConfigTest> Publish-DscConfiguration .\SharePointConfig -ComputerName 'TestVM'
PS C:\PartialConfigTest> Start-DscConfiguration -UseExisting -ComputerName 'TestVM'

Id     Name            PSJobTypeName   State         HasMoreData     Location             Command                  
--     ----            -------------   -----         -----------     --------             -------                  
17     Job17           Configuratio... Running       True            TestVM            Start-DscConfiguration...

Observação: o usuário que estiver executando o cmdlet Publish-DSCConfiguration deve ter privilégios de administrador no nó de destino.Note: The user running the Publish-DSCConfiguration cmdlet must have administrator privileges on the target node.

Configurações parciais no modo de pullPartial configurations in pull mode

Configurações parciais podem ser extraídas por push de um ou mais servidores de pull (para obter mais informações sobre servidores de pull, consulte Servidores de Pull de Configuração de Estado Desejado do Windows PowerShell.Partial configurations can be pulled from one or more pull servers (for more information about pull servers, see Windows PowerShell Desired State Configuration Pull Servers. Para fazer isso, você precisa configurar o LCM no nó de destino a fim de extrair por push as configurações parciais, bem como nomear e localizar os documentos de configuração corretamente nos servidores de pull.To do this, you have to configure the LCM on the target node to pull the partial configurations, and name and locate the configuration documents properly on the pull servers.

Configurando o LCM para configurações no nó de pullConfiguring the LCM for pull node configurations

Para configurar o LCM para efetuar o pull de configurações parciais de um servidor de pull, defina o servidor de pull em um bloco ConfigurationRepositoryWeb (para um servidor de pull de HTTP) ou ConfigurationRepositoryShare (para um servidor de pull de SMB).To configure the LCM to pull partial configurations from a pull server, you define the pull server in either a ConfigurationRepositoryWeb (for an HTTP pull server) or ConfigurationRepositoryShare (for an SMB pull server) block. Em seguida, crie blocos PartialConfiguration que se refiram ao servidor de pull, usando a propriedade ConfigurationSource.You then create PartialConfiguration blocks that refer to the pull server by using the ConfigurationSource property. Também é necessário criar um bloco Settings para especificar que o LCM usa o modo de pull, além de especificar o ConfigurationNames ou o ConfigurationID que o servidor de pull e o nó de destino usam para identificar as configurações.You also need to create a Settings block to specify that the LCM uses pull mode, and to specify the ConfigurationNames or ConfigurationID that the pull server and target node use to identify the configurations. A metaconfiguração a seguir define um servidor de pull de HTTP denominado CONTOSO-PullSrv e duas configurações parciais que usam um servidor de pull.The following meta-configuration defines an HTTP pull server named CONTOSO-PullSrv and two partial configurations that use that pull server.

Para obter mais informações sobre como configurar um LCM usando ConfigurationNames, consulte Configurando um cliente de pull usando nomes de configuração.For more information about configuring the LCM using ConfigurationNames, see Setting up a pull client using configuration names. Para obter mais informações sobre como configurar um LCM usando ConfigurationID, consulte Configurando um cliente de pull usando a ID de configuração.For information about configuring the LCM using ConfigurationID, see Setting up a pull client using configuration ID.

Configurando o LCM para configurações de modo de pull usando os nomes de configuraçãoConfiguring the LCM for pull mode configurations using configuration names

[DscLocalConfigurationManager()]
Configuration PartialConfigDemoConfigNames
{
        Settings
        {
            RefreshFrequencyMins            = 30;
            RefreshMode                     = "PULL";
            ConfigurationMode               ="ApplyAndAutocorrect";
            AllowModuleOverwrite            = $true;
            RebootNodeIfNeeded              = $true;
            ConfigurationModeFrequencyMins  = 60;
        }
        ConfigurationRepositoryWeb CONTOSO-PullSrv
        {
            ServerURL                       = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'    
            RegistrationKey                 = 5b41f4e6-5e6d-45f5-8102-f2227468ef38     
            ConfigurationNames              = @("ServiceAccountConfig", "SharePointConfig")
        }     

        PartialConfiguration ServiceAccountConfig 
        {
            Description                     = "ServiceAccountConfig"
            ConfigurationSource             = @("[ConfigurationRepositoryWeb]CONTOSO-PullSrv") 
        }

        PartialConfiguration SharePointConfig
        {
            Description                     = "SharePointConfig"
            ConfigurationSource             = @("[ConfigurationRepositoryWeb]CONTOSO-PullSrv")
            DependsOn                       = '[PartialConfiguration]ServiceAccountConfig'
        }

}

Configurando o LCM para configurações de modo de pull usando ConfigurationIDConfiguring the LCM for pull mode configurations using ConfigurationID

[DSCLocalConfigurationManager()]
configuration PartialConfigDemoConfigID
{
    Node localhost
    {
        Settings
        {
            RefreshMode                     = 'Pull'
            ConfigurationID                 = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
            RefreshFrequencyMins            = 30 
            RebootNodeIfNeeded              = $true
        }
        ConfigurationRepositoryWeb CONTOSO-PullSrv
        {
            ServerURL                       = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'

        }

           PartialConfiguration ServiceAccountConfig
        {
            Description                     = 'Configuration for the Base OS'
            ConfigurationSource             = '[ConfigurationRepositoryWeb]CONTOSO-PullSrv'
            RefreshMode                     = 'Pull'
        }
           PartialConfiguration SharePointConfig
        {
            Description                     = 'Configuration for the Sharepoint Server'
            ConfigurationSource             = '[ConfigurationRepositoryWeb]CONTOSO-PullSrv'
            DependsOn                       = '[PartialConfiguration]ServiceAccountConfig'
            RefreshMode                     = 'Pull'
        }
    }
}
PartialConfigDemo 

É possível extrair configurações parciais de mais de um servidor de pull – você precisaria apenas definir cada servidor de pull e consultar o servidor de pull apropriado em cada bloco PartialConfiguration.You can pull partial configurations from more than one pull server—you would just need to define each pull server, and then refer to the appropriate pull server in each PartialConfiguration block.

Depois de criar a metaconfiguração, deve executá-la para criar um documento de configuração (um arquivo MOF) e, em seguida, chamar Set-DscLocalConfigurationManager para configurar o LCM.After creating the meta-configuration, you must run it to create a configuration document (a MOF file), and then call Set-DscLocalConfigurationManager to configure the LCM.

Nomeando e colocando os documentos de configuração no servidor de pull (ConfigurationNames)Naming and placing the configuration documents on the pull server (ConfigurationNames)

Os documentos de configuração parcial devem ser colocados na pasta especificada como o ConfigurationPath no arquivo web.config para o servidor de pull (geralmente C:\Program Files\WindowsPowerShell\DscService\Configuration).The partial configuration documents must be placed in the folder specified as the ConfigurationPath in the web.config file for the pull server (typically C:\Program Files\WindowsPowerShell\DscService\Configuration).

Como nomear os documentos de configuração no servidor de pull no PowerShell 5.1Naming configuration documents on the pull server in PowerShell 5.1

Se você estiver extraindo somente uma configuração parcial de um servidor de pull individual, o documento de configuração poderá ter qualquer nome.If you are pulling only one partial configuration from an individual pull server, the configuration document can have any name. Se você está extraindo mais de uma configuração parcial de um servidor de pull, o documento de configuração pode ser denominado <ConfigurationName>.mof, onde ConfigurationName é o nome da configuração parcial, ou <ConfigurationName>.<NodeName>.mof, onde ConfigurationName é o nome da configuração parcial, e NodeName é o nome do nó de destino.If you are pulling more than one partial configuration from a pull server, the configuration document can be named either <ConfigurationName>.mof, where ConfigurationName is the name of the partial configuration, or <ConfigurationName>.<NodeName>.mof, where ConfigurationName is the name of the partial configuration, and NodeName is the name of the target node. Isso permite extrair configurações do servidor de pull de DSC de Automação do Azure.This allows you to pull configurations from Azure Automation DSC pull server.

Como nomear os documentos de configuração no servidor de pull no PowerShell 5.0Naming configuration documents on the pull server in PowerShell 5.0

Os documentos de configuração devem ser nomeados da seguinte maneira: ConfigurationName.mof, em que ConfigurationName é o nome da configuração parcial.The configuration documents must be named as follows: ConfigurationName.mof, where ConfigurationName is the name of the partial configuration. Para nosso exemplo, os documentos de configuração devem ser nomeados da seguinte maneira:For our example, the configuration documents should be named as follows:

ServiceAccountConfig.mof
ServiceAccountConfig.mof.checksum
SharePointConfig.mof
SharePointConfig.mof.checksum

Nomeando e colocando os documentos de configuração no servidor de pull (ConfigurationID)Naming and placing the configuration documents on the pull server (ConfigurationID)

Os documentos de configuração parcial devem ser colocados na pasta especificada como o ConfigurationPath no arquivo web.config para o servidor de pull (geralmente C:\Program Files\WindowsPowerShell\DscService\Configuration).The partial configuration documents must be placed in the folder specified as the ConfigurationPath in the web.config file for the pull server (typically C:\Program Files\WindowsPowerShell\DscService\Configuration). Os documentos de configuração devem ser nomeados da seguinte maneira: ConfigurationName.The configuration documents must be named as follows: ConfigurationName. ConfigurationID.mof, em que ConfigurationName é o nome da configuração parcial e ConfigurationID é a ID de configuração definida no LCM no nó de destino.ConfigurationID.mof, where ConfigurationName is the name of the partial configuration and ConfigurationID is the configuration ID defined in the LCM on the target node. Para nosso exemplo, os documentos de configuração devem ser nomeados da seguinte maneira:For our example, the configuration documents should be named as follows:

ServiceAccountConfig.1d545e3b-60c3-47a0-bf65-5afc05182fd0.mof
ServiceAccountConfig.1d545e3b-60c3-47a0-bf65-5afc05182fd0.mof.checksum
SharePointConfig.1d545e3b-60c3-47a0-bf65-5afc05182fd0.mof
SharePointConfig.1d545e3b-60c3-47a0-bf65-5afc05182fd0.mof.checksum

Executando configurações parciais de um servidor de pullRunning partial configurations from a pull server

Depois que o LCM no nó de destino tiver sido configurado e os documentos de configuração tiverem sido criados e chamados corretamente no servidor de pull, o nó de destino vai efetuar o pull das configurações parciais, combiná-las e aplicar a configuração resultante em intervalos regulares, conforme especificado pela propriedade RefreshFrequencyMins do LCM.After the LCM on the target node has been configured, and the configuration documents have been created and properly named on the pull server, the target node will pull the partial configurations, combine them, and apply the resulting configuration at regular intervals as specified by the RefreshFrequencyMins property of the LCM. Se você quiser forçar uma atualização, poderá chamar o cmdlet Update-DscConfiguration para efetuar o pull das configurações e, em seguida, Start-DSCConfiguration –UseExisting para aplicá-las.If you want to force a refresh, you can call the Update-DscConfiguration cmdlet, to pull the configurations, and then Start-DSCConfiguration –UseExisting to apply them.

Configurações parciais nos modos de push e pull combinadosPartial configurations in mixed push and pull modes

Também é possível combinar os modos de push e pull para configurações parciais.You can also mix push and pull modes for partial configurations. Ou seja, você pode ter uma configuração parcial que é extraída por pull de um servidor de pull, enquanto outra configuração parcial é enviada por push.That is, you could have one partial configuration that is pulled from a pull server, while another partial configuration is pushed. Especifique o modo de atualização para cada configuração parcial conforme descrito nas seções anteriores.Specify the refresh mode for each partial configuration as described in the previous sections. Por exemplo, a metaconfiguração a seguir descreve o mesmo exemplo, com a configuração parcial da ServiceAccountConfig no modo de pull e a configuração parcial do SharePointConfig no modo de push.For example, the following meta-configuration describes the same example, with the ServiceAccountConfig partial configuration in pull mode and the SharePointConfig partial configuration in push mode.

Modos de pull e push mistos usando ConfigurationNamesMixed push and pull modes using ConfigurationNames

[DscLocalConfigurationManager()]
Configuration PartialConfigDemoConfigNames
{
        Settings
        {
            RefreshFrequencyMins            = 30;
            RefreshMode                     = "PULL";
            ConfigurationMode               = "ApplyAndAutocorrect";
            AllowModuleOverwrite            = $true;
            RebootNodeIfNeeded              = $true;
            ConfigurationModeFrequencyMins  = 60;
        }
        ConfigurationRepositoryWeb CONTOSO-PullSrv
        {
            ServerURL                       = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'    
            RegistrationKey                 = 5b41f4e6-5e6d-45f5-8102-f2227468ef38     
            ConfigurationNames              = @("ServiceAccountConfig", "SharePointConfig")
        }     

        PartialConfiguration ServiceAccountConfig 
        {
            Description                     = "ServiceAccountConfig"
            ConfigurationSource             = @("[ConfigurationRepositoryWeb]CONTOSO-PullSrv")
            RefreshMode                     = 'Pull' 
        }

        PartialConfiguration SharePointConfig
        {
            Description                     = "SharePointConfig"
            DependsOn                       = '[PartialConfiguration]ServiceAccountConfig'
            RefreshMode                     = 'Push'
        }

}

Modos de pull e push mistos usando ConfigurationIDMixed push and pull modes using ConfigurationID

[DSCLocalConfigurationManager()]
configuration PartialConfigDemo
{
    Node localhost
    {
        Settings
        {
            RefreshMode             = 'Pull'
            ConfigurationID         = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
            RefreshFrequencyMins    = 30 
            RebootNodeIfNeeded      = $true
        }
        ConfigurationRepositoryWeb CONTOSO-PullSrv
        {
            ServerURL               = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'

        }

           PartialConfiguration ServiceAccountConfig
        {
            Description             = 'Configuration for the Base OS'
            ConfigurationSource     = '[ConfigurationRepositoryWeb]CONTOSO-PullSrv'
            RefreshMode             = 'Pull'
        }
           PartialConfiguration SharePointConfig
        {
            Description             = 'Configuration for the Sharepoint Server'
            DependsOn               = '[PartialConfiguration]ServiceAccountConfig'
            RefreshMode             = 'Push'
        }
    }
}
PartialConfigDemo 

Observe que o RefreshMode especificado no bloco Settings é "Pull", mas o RefreshMode para a configuração parcial SharePointConfig é "Push".Note that the RefreshMode specified in the Settings block is "Pull", but the RefreshMode for the SharePointConfig partial configuration is "Push".

É necessário nomear e localizar os documentos do MOF de configuração, conforme descrito acima, para os respectivos modos de atualização.Name and locate the configuration MOF files as described above for their respective refresh modes. Chame Publish-DSCConfiguration para publicar a configuração parcial de SharePointConfig e aguarde até que a configuração de ServiceAccountConfig seja extraída do servidor de pull ou force uma atualização chamando Update-DscConfiguration.Call Publish-DSCConfiguration to publish the SharePointConfig partial configuration, and either wait for the ServiceAccountConfig configuration to be pulled from the pull server, or force a refresh by calling Update-DscConfiguration.

Exemplo de configuração parcial de ServiceAccountConfigExample ServiceAccountConfig Partial Configuration

Configuration ServiceAccountConfig
{
    Param (
        [Parameter(Mandatory,
                   HelpMessage="Domain credentials required to add domain\sharepoint_svc to the local Administrators group.")]
        [ValidateNotNullOrEmpty()]
        [pscredential]$Credential
    )

    Import-DscResource -ModuleName PSDesiredStateConfiguration


    Node localhost
    {
        Group LocalAdmins
        {
            GroupName           = 'Administrators'
            MembersToInclude    = 'domain\sharepoint_svc',
                                  'admins@example.domain'
            Ensure              = 'Present'
            Credential          = $Credential

        }

        WindowsFeature Telnet
        {
            Name                = 'Telnet-Server'
            Ensure              = 'Absent'
        }
    }
}
ServiceAccountConfig

Exemplo de configuração parcial do SharePointConfigExample SharePointConfig Partial Configuration

Configuration SharePointConfig
{
    Param (
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [pscredential]$ProductKey
    )

    Import-DscResource -ModuleName xSharePoint

    Node localhost
    {
        xSPInstall SharePointDefault
        {
            Ensure      = 'Present'
            BinaryDir   = '\\FileServer\Installers\Sharepoint\'
            ProductKey  = $ProductKey
        }
    }
}
SharePointConfig

Consulte TambémSee Also

Conceitos Servidores de Pull de Configuração de Estado Desejado do Windows PowerShellConcepts Windows PowerShell Desired State Configuration Pull Servers

Configurando o Gerenciador de Configurações Local com o WindowsWindows Configuring the Local Configuration Manager