Lista de verificação da criação de recursosResource authoring checklist

Esta lista de verificação é uma lista de melhores práticas ao criar um novo Recurso de DSC.This checklist is a list of best practices when authoring a new DSC Resource.

O módulo de recurso contém os arquivos .psd1 e schema.mof de cada um dos recursosResource module contains .psd1 file and schema.mof for every resource

Verifique se o recurso tem a estrutura correta e se ele contém todos os arquivos necessários.Check that your resource has correct structure and contains all required files. Cada módulo de recurso deve conter um arquivo .psd1 e cada recurso de não composição deve ter o arquivo schema.mof.Every resource module should contain a .psd1 file and every non-composite resource should have schema.mof file. Recursos que não contêm o esquema não serão listados por Get-DscResource e os usuários não poderão usar o IntelliSense ao escrever código nesses módulos no ISE.Resources that do not contain schema will not be listed by Get-DscResource and users will not be able to use the intellisense when writing code against those modules in ISE. A estrutura de diretório para o recurso xRemoteFile, que faz parte do módulo de recurso xPSDesiredStateConfiguration, tem a seguinte aparência:The directory structure for xRemoteFile resource, which is part of the xPSDesiredStateConfiguration resource module, looks as follows:

xPSDesiredStateConfiguration
    DSCResources
        MSFT_xRemoteFile
            MSFT_xRemoteFile.psm1
            MSFT_xRemoteFile.schema.mof
    Examples
        xRemoteFile_DownloadFile.ps1
    ResourceDesignerScripts
        GenerateXRemoteFileSchema.ps1
    Tests
        ResourceDesignerTests.ps1
    xPSDesiredStateConfiguration.psd1

Os recursos e o esquema estão corretos##Resource and schema are correct##

Verifique o arquivo de esquema do recurso (.schema.mof).Verify the resource schema (.schema.mof) file. Você pode usar o Designer de Recursos da DSC para ajudar a desenvolver e testar seu esquema.You can use the DSC Resource Designer to help develop and test your schema. Certifique-se de que:Make sure that:

  • Os tipos de propriedade estão corretos (por exemplo, não use Cadeia de caracteres para propriedades que aceitam valores numéricos; em vez disso, use UInt32 ou outros tipos numéricos)Property types are correct (e.g. don’t use String for properties which accept numeric values, you should use UInt32 or other numeric types instead)
  • Os atributos de propriedade foram especificados corretamente como: ([key], [required], [write] e [read])Property attributes are specified correctly as: ([key], [required], [write], [read])
  • Pelo menos, um parâmetro no esquema deve estar marcado como [key]At least one parameter in the schema has to be marked as [key]
  • A propriedade [read] não coexiste com nenhuma dessas: [required], [key] e [write][read] property does not coexist together with any of: [required], [key], [write]
  • Se forem especificados vários qualificadores, exceto [read], [key] terá precedênciaIf multiple qualifiers are specified except [read], then [key] takes precedence
  • Se [write] e [required] forem especificados, [required] terá precedênciaIf [write] and [required] are specified, then [required] takes precedence
  • ValueMap foi especificado, quando apropriadoValueMap is specified where appropriate

Exemplo:Example:

[Read, ValueMap{"Present", "Absent"}, Values{"Present", "Absent"}, Description("Says whether DestinationPath exists on the machine")] String Ensure;
  • O nome amigável é especificado e está em conformidade com as convenções de nomenclatura do DSCFriendly name is specified and confirms to DSC naming conventions

Exemplo: [ClassVersion("1.0.0.0"), FriendlyName("xRemoteFile")]Example: [ClassVersion("1.0.0.0"), FriendlyName("xRemoteFile")]

Além disso, é necessário usar os cmdlets Test-xDscResource e Test-xDscSchema do Designer de Recursos da DSC para verificar automaticamente o recurso e o esquema:Additionally, you should use Test-xDscResource and Test-xDscSchema cmdlets from DSC Resource Designer to automatically verify the resource and schema:

Test-xDscResource <Resource_folder>
Test-xDscSchema <Path_to_resource_schema_file>

Por exemplo:For example:

Test-xDscResource ..\DSCResources\MSFT_xRemoteFile
Test-xDscSchema ..\DSCResources\MSFT_xRemoteFile\MSFT_xRemoteFile.schema.mof

O recurso é carregado sem errosResource loads without errors

Verifique se o módulo de recurso poderá ser carregado com êxito.Check whether the resource module can be successfully loaded. Isso pode ser feito manualmente executando Import-Module <resource_module> -force e confirmando se não ocorreu nenhum erro, ou ainda escrevendo uma automação de teste.This can be achieved manually, by running Import-Module <resource_module> -force and confirming that no errors occurred, or by writing test automation. No caso do último, é possível seguir esta estrutura em seu caso de teste:In case of the latter, you can follow this structure in your test case:

$error = $null
Import-Module <resource_module> –force
If ($error.count –ne 0) {
    Throw “Module was not imported correctly. Errors returned: $error”
}

O recurso é idempotente no caso positivoResource is idempotent in the positive case

Uma das características fundamentais dos recursos da DSC é a idempotência.One of the fundamental characteristics of DSC resources is be idempotence. Isso significa que aplicar várias vezes uma configuração de DSC que contém esse recurso fará com que o mesmo resultado seja obtido sempre.It means that applying a DSC configuration containing that resource multiple times will always achieve the same result. Por exemplo, se criarmos uma configuração que contém o seguinte recurso File:For example, if we create a configuration which contains the following File resource:

File file {
    DestinationPath = "C:\test\test.txt"
    Contents = "Sample text"
} 

Depois de aplicá-la pela primeira vez, o arquivo test.txt deve aparecer na pasta C:\test.After applying it for the first time, file test.txt should appear in C:\test folder. No entanto, execuções posteriores da mesma configuração não devem alterar o estado do computador (por exemplo, nenhuma cópia do arquivo test.txt deve ser criada).However, subsequent runs of the same configuration should not change the state of the machine (e.g. no copies of the test.txt file should be created). Para garantir que um recurso é idempotente, você pode chamar repetidamente Set-TargetResource ao testar o recurso diretamente, ou chamar Start-DscConfiguration várias vezes ao realizar testes de ponta a ponta.To ensure a resource is idempotent you can repeatedly call Set-TargetResource when testing the resource directly, or call Start-DscConfiguration multiple times when doing end to end testing. O resultado deve ser o mesmo após cada execução.The result should be the same after every run.

Cenário de modificação de usuário de testeTest user modification scenario

Ao alterar o estado do computador e, em seguida, executar a DSC novamente, você poderá verificar se Set-TargetResource e Test-TargetResource funcionam corretamente.By changing the state of the machine and then rerunning DSC, you can verify that Set-TargetResource and Test-TargetResource function properly. Aqui estão as etapas que devem ser seguidas:Here are steps you should take:

  1. Inicie com o recurso fora do estado desejado.Start with the resource not in the desired state.
  2. Executar a configuração com o recursoRun configuration with your resource
  3. Verificar se Test-DscConfiguration retorna TrueVerify Test-DscConfiguration returns True
  4. Modificar o item configurado para ficar fora do estado desejadoModify the configured item to be out of the desired state
  5. Verifique se Test-DscConfiguration retorna false. Veja um exemplo mais concreto usando o recurso de Registro:Verify Test-DscConfiguration returns false Here’s a more concrete example using Registry resource:
  6. Inicie com a chave do Registro fora do estado desejadoStart with registry key not in the desired state
  7. Executar Start-DscConfiguration com uma configuração para colocá-la no estado desejado e verificar se ela é passada.Run Start-DscConfiguration with a configuration to put it in the desired state and verify it passes.
  8. Executar Test-DscConfiguration e verificar se ela retorna TrueRun Test-DscConfiguration and verify it returns true
  9. Modificar o valor da chave para que ela não esteja no estado desejadoModify the value of the key so that it is not in the desired state
  10. Executar Test-DscConfiguration e verificar se ela retorna FalseRun Test-DscConfiguration and verify it returns false
  11. A funcionalidade de Get-TargetResource foi verificada usando Get-DscConfigurationGet-TargetResource functionality was verified using Get-DscConfiguration

Get-TargetResource deve retornar detalhes do estado atual do recurso.Get-TargetResource should return details of the current state of the resource. Certifique-se de testá-lo chamando Get-DscConfiguration depois de aplicar a configuração e verificar se a saída reflete corretamente o estado atual do computador.Make sure to test it by calling Get-DscConfiguration after you apply the configuration and verifying that output correctly reflects the current state of the machine. É importante testá-lo separadamente, pois quaisquer problemas nesta área não aparecerão ao chamar Start-DscConfiguration.It's important to test it separately, since any issues in this area won't appear when calling Start-DscConfiguration.

Chame as funções Get/Set/Test-TargetResource diretamenteCall Get/Set/Test-TargetResource functions directly

Certifique-se de testar as funções Get/Set/Test-TargetResource implementadas em seu recurso chamando-as diretamente e verificando se funcionam como esperado.Make sure you test the Get/Set/Test-TargetResource functions implemented in your resource by calling them directly and verifying that they work as expected.

Faça uma verificação completa usando Start-DscConfigurationVerify End to End using Start-DscConfiguration

É importante testar as funções Get/Set/Test-TargetResource chamando-as diretamente; no entanto, nem todos os problemas serão descobertos dessa maneira.Testing Get/Set/Test-TargetResource functions by calling them directly is important, but not all issues will be discovered this way. Você deve concentrar uma parte significativa do teste no uso de Start-DscConfiguration ou no servidor de pull.You should focus significant part of your testing on using Start-DscConfiguration or the pull server. Na verdade, essa é a forma como os usuários usarão o recurso; portanto, não subestime a importância desse tipo de testes.In fact, this is how users will use the resource, so don’t underestimate the significance of this type of tests. Possíveis tipos de problemas:Possible types of issues:

  • A Credencial/Sessão podem se comportar de maneira diferente, porque o agente do DSC é executado como um serviço.Credential/Session may behave differently because the DSC agent runs as a service. Certifique-se de testar quaisquer recursos aqui de ponta a ponta.Be sure to test any features here end to end.
  • Os erros gerados por Start-DscConfiguration podem ser diferentes daqueles exibidos ao chamar diretamente a função Set-TargetResource.Errors output by Start-DscConfiguration may be different than those displayed when calling the Set-TargetResource function directly.

Teste a compatibilidade em todas as plataformas com suporte para DSCTest compatability on all DSC supported platforms

O recurso deve funcionar em todas as plataformas do DSC com suporte (Windows Server 2008 R2 e mais recente).Resource should work on all DSC supported platforms (Windows Server 2008 R2 and newer). Instale o WMF (Windows Management Framework) mais recente em seu sistema operacional para obter a versão mais recente da DSC.Install the latest WMF (Windows Management Framework) on your OS to get the latest version of DSC. Se seu recurso não funcionar em algumas dessas plataformas por design, uma mensagem de erro específica deverá ser retornada.If your resource does not work on some of these platforms by design, a specific error message should be returned. Além disso, certifique-se de que o recurso verifica se os cmdlets que estão sendo chamados estão presentes em um computador específico.Also, make sure your resource checks whether cmdlets you are calling are present on particular machine. O Windows Server 2012 adicionou um grande número de novos cmdlets que não estão disponíveis no Windows Server 2008R2, mesmo com o WMF instalado.Windows Server 2012 added a large number of new cmdlets that are not available on Windows Server 2008R2, even with WMF installed.

Verifique no Windows Client (se aplicável)Verify on Windows Client (if applicable)

Um intervalo de teste muito comum é verificar o recurso somente nas versões do servidor do Windows.One very common test gap is verifying the resource only on server versions of Windows. Muitos recursos também foram projetados para funcionar em SKUs do Cliente; portanto, se esse for o seu caso, não se esqueça de testá-lo nessas plataformas também.Many resources are also designed to work on Client SKUs, so if that’s true in your case, don’t forget to test it on those platforms as well.

Get-DSCResource lista os recursosGet-DSCResource lists the resource

Depois de implantar o módulo, uma chamada a Get-DscResource deverá listar seu recurso, entre outros, como resultado.After deploying the module, calling Get-DscResource should list your resource among others as a result. Se não encontrar seu recurso na lista, verifique se o arquivo schema.mof para esse recurso existe.If you can’t find your resource in the list, make sure that schema.mof file for that resource exists.

O módulo de recurso contém exemplosResource module contains examples

Criando exemplos de qualidade que ajudarão outros a entender como usá-los.Creating quality examples which will help others understand how to use it. Isso é crucial, especialmente porque muitos usuários tratam o código de exemplo como documentação.This is crucial, especially since many users treat sample code as documentation.

  • Primeiro, é necessário determinar os exemplos que serão incluídos com o módulo – no mínimo, deve-se abranger os casos de uso mais importantes para o recurso:First, you should determine the examples that will be included with the module – at minimum, you should cover most important use cases for your resource:
  • Se o módulo contiver vários recursos que precisam funcionar juntos para um cenário de ponta a ponta, o exemplo de ponta a ponta básico seria, teoricamente, o primeiro.If your module contains several resources that need to work together for an end-to-end scenario, the basic end-to-end example would ideally be first.
  • Os exemplos inicias devem ser bem simples – como começar a usar seus recursos em partes gerenciáveis pequenas (por exemplo, criar um novo VHD)The initial examples should be very simple -- how to get started with your resources in small manageable chunks (e.g. creating a new VHD)
  • Os exemplos posteriores devem se basear nesses exemplos (por exemplo, criar uma VM desde um VHD, remover a VM e modificá-la) e mostrar a funcionalidade avançada (por exemplo, criar uma VM com memória dinâmica)Subsequent examples should build on those examples (e.g. creating a VM from a VHD, removing VM, modifying VM), and show advanced functionality (e.g. creating a VM with dynamic memory)
  • Os exemplos de configurações devem ser parametrizados (todos os valores devem ser passados para a configuração como parâmetros e não deve haver nenhum valor fixo):Example configurations should be parameterized (all values should be passed to the configuration as parameters and there should be no hardcoded values):

    configuration Sample_xRemoteFile_DownloadFile
    {
      param
      (
          [string[]] $nodeName = 'localhost',
    
          [parameter(Mandatory = $true)]
          [ValidateNotNullOrEmpty()]
          [String] $destinationPath,
    
          [parameter(Mandatory = $true)]
          [ValidateNotNullOrEmpty()]
          [String] $uri,
    
          [String] $userAgent,
    
          [Hashtable] $headers
      )
    
      Import-DscResource -Name MSFT_xRemoteFile -ModuleName xPSDesiredStateConfiguration
    
      Node $nodeName
      {
          xRemoteFile DownloadFile
          {
              DestinationPath = $destinationPath
              Uri = $uri
              UserAgent = $userAgent
              Headers = $headers
          }
      }
    } 
    
  • É uma prática recomendada incluir um exemplo (comentado) de como chamar a configuração com os valores reais no final do script de exemplo.It’s a good practice to include (commented out) example of how to call the configuration with the actual values at the end of the example script. Por exemplo, na configuração acima, não é absolutamente óbvio que a melhor maneira de especificar o UserAgent é:For example, in the configuration above it isn't neccessarily obvious that the best way to specify UserAgent is:

UserAgent = [Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer
Nesse caso, um comentário pode esclarecer a execução pretendida da configuração:In which case a comment can clarify the intended execution of the configuration:

<# 
Sample use (parameter values need to be changed according to your scenario):

Sample_xRemoteFile_DownloadFile -destinationPath "$env:SystemDrive\fileName.jpg" -uri "http://www.contoso.com/image.jpg"

Sample_xRemoteFile_DownloadFile -destinationPath "$env:SystemDrive\fileName.jpg" -uri "http://www.contoso.com/image.jpg" `
-userAgent [Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer -headers @{"Accept-Language" = "en-US"}
#>  
  • Para cada exemplo, escreva uma breve descrição que explica o que ele faz e o significado dos parâmetros.For each example, write a short description which explains what it does, and the meaning of the parameters.
  • Certifique-se de que os exemplos abrangem a maioria dos cenários importantes para o recurso e que nada está faltando, verifique se todos eles são executados e coloque o computador no estado desejado.Make sure examples cover most the important scenarios for your resource and if there’s nothing missing, verify that they all execute and put machine in the desired state.

Mensagens de erro são fáceis de entender e ajudam os usuários a resolver problemasError messages are easy to understand and help users solve problems

Mensagens de erro úteis devem ser:Good error messages should be:

  • Existentes: o maior problema com mensagens de erro é que elas, geralmente, não existem; portanto, certifique-se de que elas existem.There: The biggest problem with error messages is that they often don’t exist, so make sure they are there.
  • Fáceis de entender: legíveis por humanos e sem códigos de erro obscurosEasy to understand: Human readable, no obscure error codes
  • Precisas: descrevem qual é exatamente o problemaPrecise: Describe what’s exactly the problem
  • Construtivas: fazem recomendações sobre como corrigir o problemaConstructive: Advice how to fix the issue
  • Cortês: não culpe o usuário nem o faça se sentir mal. Verifique os erros nos cenários de ponta a ponta (usando Start-DscConfiguration), pois eles podem ser diferentes daqueles retornados ao executar as funções de recurso diretamente.Polite: Don’t blame user or make them feel bad Make sure you verify errors in End to End scenarios (using Start-DscConfiguration), because they may differ from those returned when running resource functions directly.

Mensagens de log são informativas e fáceis de entender (incluindo –verbose, –debug e logs do ETW)Log messages are easy to understand and informative (including –verbose, –debug and ETW logs)

Certifique-se de que logs gerados pelo recurso são fáceis de entender e fornecem valor ao usuário.Ensure that logs outputted by the resource are easy to understand and provide value to the user. Os recursos devem gerar todas as informações que podem ser úteis para o usuário; contudo, mais logs nem sempre são o melhor.Resources should output all information which might be helpful to the user, but more logs is not always better. É necessário evitar a redundância e gerar dados que não fornecem valor adicional – não faça alguém percorrer centenas de entradas de log para encontrar o que está procurando.You should avoid redundancy and outputting data which does not provide additional value – don’t make someone go through hundreds of log entries in order to find what they're looking for. Obviamente, não fornecer nenhum log também não é uma solução aceitável para esse problema.Of course, no logs is not an acceptable solution for this problem either.

Durante o teste, também é necessário analisar logs detalhados e de depuração (executando Start-DscConfiguration com as opções –verbose e –debug de maneira adequada), bem como os logs do ETW.When testing, you should also analyze verbose and debug logs (by running Start-DscConfiguration with –verbose and –debug switches appropriately), as well as ETW logs. Para ver os logs do ETW no DSC, vá para o Visualizador de Eventos e abra a seguinte pasta: Aplicativos e Serviços – Microsoft – Windows – Configuração de Estado Desejado.To see DSC ETW logs, go to Event Viewer and open the following folder: Applications and Services- Microsoft - Windows - Desired State Configuration. Por padrão, haverá o canal Operacional, mas lembre-se de habilitar os canais Analítico e de Depuração antes de executar a configuração.By default there will be Operational channel, but make sure you enable Analytic and Debug channels before running the configuration. Para habilitar os canais Analítico/de Depuração, é possível executar o script abaixo:To enable Analytic/Debug channels, you can execute script below:

$statusEnabled = $true
# Use "Analytic" to enable Analytic channel
$eventLogFullName = "Microsoft-Windows-Dsc/Debug" 
$commandToExecute = "wevtutil set-log $eventLogFullName /e:$statusEnabled /q:$statusEnabled   "
$log = New-Object System.Diagnostics.Eventing.Reader.EventLogConfiguration $eventLogFullName
if($statusEnabled -eq $log.IsEnabled)
{
    Write-Host -Verbose "The channel event log is already enabled"
    return
}     
Invoke-Expression $commandToExecute 

A implementação de recurso não contêm caminhos fixosResource implementation does not contain hardcoded paths

Assegure-se de que não há nenhum caminho fixo na implementação de recurso, especialmente, se ele assume um idioma (en-us) ou quando houver variáveis do sistema que podem ser usadas.Ensure there are no hardcoded paths in the resource implementation, particularly if they assume language (en-us), or when there are system variables that can be used. Se o recurso precisar acessar caminhos específicos, use variáveis de ambiente em vez de fixar o caminho no código, pois ele pode ser diferente em outros computadores.If your resource need to access specific paths, use environment variables instead of hardcoding the path, as it may differ on other machines.

Exemplo:Example:

Em vez de:Instead of:

$tempPath = "C:\Users\kkaczma\AppData\Local\Temp\MyResource"
$programFilesPath = "C:\Program Files (x86)"

É possível escrever:You can write:

$tempPath = Join-Path $env:temp "MyResource"
$programFilesPath = ${env:ProgramFiles(x86)} 

A implementação de recurso não contêm informações do usuárioResource implementation does not contain user information

Assegure-se de que não há nenhum nome de email, informações de conta ou nome de pessoas no código.Make sure there are no email names, account information, or names of people in the code.

O recurso foi testado com credenciais válidas/inválidasResource was tested with valid/invalid credentials

Caso o recurso use uma credencial como parâmetro:If your resource takes a credential as parameter:

  • Verifique se o recurso funciona quando o Sistema Local (ou a conta de computador de recursos remotos) não tem acesso.Verify the resource works when Local System (or the computer account for remote resources) does not have access.
  • Verifique se o recurso funciona com uma credencial especificada para Get, Set e TestVerify the resource works with a credential specified for Get, Set and Test
  • Caso o recurso acesse os compartilhamentos, teste todas as variantes para as quais é necessário dar suporte, como:If your resource accesses shares, test all the variants you need to support, such as:
    • Compartilhamentos de janelas padrão.Standard windows shares.
    • Compartilhamentos DFS.DFS shares.
    • Compartilhamentos SAMBA (se desejar dar suporte ao Linux).SAMBA shares (if you want to support Linux.)

O recurso não requer entrada interativaResource does not require interactive input

As funções Get/Set/Test-TargetResource devem ser executadas automaticamente e não devem aguardar pela entrada do usuário em nenhum estágio de execução (por exemplo, não se deve usar Get-Credential dentro dessas funções).Get/Set/Test-TargetResource functions should be executed automatically and must not wait for user’s input at any stage of execution (e.g. you should not use Get-Credential inside these functions). Se precisar fornecer a entrada do usuário, será necessário passá-la para a configuração como parâmetro durante a fase de compilação.If you need to provide user’s input, you should pass it to the configuration as parameter during the compilation phase.

A funcionalidade do recurso foi totalmente testadaResource functionality was thoroughly tested

Esta lista de verificação contém itens cujo teste é importante e/ou que, frequentemente, estão ausentes.This checklist contains items which are important to be tested and/or are often missed. Haverá vários testes, principalmente, aqueles funcionais que serão específicos ao recurso que está sendo testado e que não são mencionados aqui.There will be bunch of tests, mainly functional ones which will be specific to the resource you are testing and are not mentioned here. Não se esqueça dos casos de teste negativos.Don’t forget about negative test cases.

Prática recomendada: o módulo de recurso contém a pasta Tests com o script ResourceDesignerTests.ps1Best practice: Resource module contains Tests folder with ResourceDesignerTests.ps1 script

É uma prática recomendada criar a pasta “Tests” dentro do módulo de recurso, criar o arquivo ResourceDesignerTests.ps1 e adicionar testes usando Test-xDscResource e Test-xDscSchema para todos os recursos em determinado módulo.It’s a good practice to create folder “Tests” inside resource module, create ResourceDesignerTests.ps1 file and add tests using Test-xDscResource and Test-xDscSchema for all resources in given module. Dessa forma, você pode validar rapidamente os esquemas de todos os recursos de determinado módulo e fazer a verificação de integridade antes da publicação.This way you can quickly validate schemas of all resources from the given modules and do a sanity check before publishing. Para xRemoteFile, ResourceTests.ps1 poderá ser bem simples, da seguinte forma:For xRemoteFile, ResourceTests.ps1 could look as simple as:

Test-xDscResource ..\DSCResources\MSFT_xRemoteFile
Test-xDscSchema ..\DSCResources\MSFT_xRemoteFile\MSFT_xRemoteFile.schema.mof 

Prática recomendada: a pasta do recurso contém um script de designer de recurso para geração de esquema##Best practice: Resource folder contains resource designer script for generating schema##

Cada recurso deve conter um script do designer de recursos que gera um esquema mof do recurso.Each resource should contain a resource designer script which generates a mof schema of the resource. Esse arquivo deve ser colocado em \ResourceDesignerScripts e ser nomeado GenerateSchema.ps1 Para o recurso xRemoteFile, esse arquivo será chamado GenerateXRemoteFileSchema.ps1 e conterá:This file should be placed in \ResourceDesignerScripts and be named GenerateSchema.ps1 For xRemoteFile resource this file would be called GenerateXRemoteFileSchema.ps1 and contain:

$DestinationPath = New-xDscResourceProperty -Name DestinationPath -Type String -Attribute Key -Description 'Path under which downloaded or copied file should be accessible after operation.'
$Uri = New-xDscResourceProperty -Name Uri -Type String -Attribute Required -Description 'Uri of a file which should be copied or downloaded. This parameter supports HTTP and HTTPS values.'
$Headers = New-xDscResourceProperty -Name Headers -Type Hashtable[] -Attribute Write -Description 'Headers of the web request.'
$UserAgent = New-xDscResourceProperty -Name UserAgent -Type String -Attribute Write -Description 'User agent for the web request.' 
$Ensure = New-xDscResourceProperty -Name Ensure -Type String -Attribute Read -ValidateSet "Present", "Absent" -Description 'Says whether DestinationPath exists on the machine'
$Credential = New-xDscResourceProperty -Name Credential -Type PSCredential -Attribute Write -Description 'Specifies a user account that has permission to send the request.'
$CertificateThumbprint = New-xDscResourceProperty -Name CertificateThumbprint -Type String -Attribute Write -Description 'Digital public key certificate that is used to send the request.'

New-xDscResource -Name MSFT_xRemoteFile -Property @($DestinationPath, $Uri, $Headers, $UserAgent, $Ensure, $Credential, $CertificateThumbprint) -ModuleName xPSDesiredStateConfiguration2 -FriendlyName xRemoteFile 

Melhor prática: o recurso dá suporte a -whatifBest practice: Resource supports -whatif

Caso o recurso esteja executando operações “perigosas”, é uma prática recomendada implementar a funcionalidade –whatif.If your resource is performing “dangerous” operations, it’s a good practice to implement -whatif functionality. Após a conclusão, certifique-se de que a saída –whatif descreve corretamente as operações que ocorreriam se o comando fosse executado sem a opção –whatif.After it’s done, make sure that whatif output correctly describes operations which would happen if command was executed without whatif switch. Além disso, verifique se as operações não são executadas (não é feita nenhuma alteração ao estado do nó) quando a opção –whatif está presente.Also, verify that operations does not execute (no changes to the node’s state are made) when –whatif switch is present. Por exemplo, vamos supor que estamos testando o recurso File.For example, let’s assume we are testing File resource. Veja abaixo uma configuração simples que cria o arquivo “test.txt” com o conteúdo “test”:Below is simple configuration which creates file “test.txt” with contents “test”:

configuration config
{
    node localhost 
    {
        File file
        {
            Contents="test"
            DestinationPath="C:\test\test.txt"
        }
    }
}
config 

Se compilarmos e, em seguida, executarmos a configuração com a opção –whatif, a saída nos informará exatamente o que aconteceria quando a configuração fosse executada.If we compile and then execute the configuration with the –whatif switch, the output is telling us exactly what would happen when we run the configuration. Todavia, a configuração propriamente dita não foi executada (o arquivo test.txt não foi criado).The configuration itself however was not executed (test.txt file was not created).

Start-DscConfiguration -path .\config -ComputerName localhost -wait -verbose -whatif
VERBOSE: Perform operation 'Invoke CimMethod' with following parameters, ''methodName' =
SendConfigurationApply,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' =
root/Microsoft/Windows/DesiredStateConfiguration'.
VERBOSE: An LCM method call arrived from computer CHARLESX1 with user sid
S-1-5-21-397955417-626881126-188441444-5179871.
What if: [X]: LCM:  [ Start  Set      ]
What if: [X]: LCM:  [ Start  Resource ]  [[File]file]
What if: [X]: LCM:  [ Start  Test     ]  [[File]file]
What if: [X]:                            [[File]file] The system cannot find the file specified.
What if: [X]:                            [[File]file] The related file/directory is: C:\test\test.txt.
What if: [X]: LCM:  [ End    Test     ]  [[File]file]  in 0.0270 seconds.
What if: [X]: LCM:  [ Start  Set      ]  [[File]file]
What if: [X]:                            [[File]file] The system cannot find the file specified.
What if: [X]:                            [[File]file] The related file/directory is: C:\test\test.txt.
What if: [X]:                            [C:\test\test.txt] Creating and writing contents and setting attributes.
What if: [X]: LCM:  [ End    Set      ]  [[File]file]  in 0.0180 seconds.
What if: [X]: LCM:  [ End    Resource ]  [[File]file]
What if: [X]: LCM:  [ End    Set      ]
VERBOSE: [X]: LCM:  [ End    Set      ]    in  0.1050 seconds.
VERBOSE: Operation 'Invoke CimMethod' complete.

Esta lista não é completa, mas abrange muitos problemas importantes que podem ser encontrados durante a criação, o desenvolvimento e o teste dos recursos da DSC.This list is not exhaustive, but it covers many important issues which can be encountered while designing, developing and testing DSC resources.