Sdílet prostřednictvím

Kontrolní seznam pro vytváření prostředků DSC

  • Článek

Tento kontrolní seznam obsahuje seznam osvědčených postupů při vytváření nového prostředku DSC.

Modul obsahuje manifest.

Váš modul obsahující prostředky DSC by měl mít soubor manifestu (.psd1) modulu. Nastavení DscResourcesToExport manifestu by mělo obsahovat název každého prostředku DSC.

Žádné prostředky DSC založené na třídách, které nezahrnute do nastavení DscResourcesToExport , nebudou zjistitelné pomocí Get-DscResource rutiny, nebudou se s rutinou Invoke-DscResource používat a autoři konfigurace DSC nezískají intellisense pro tyto prostředky DSC při vytváření konfigurace DSC v nástroji VS Code.

Každý prostředek DSC založený na MOF má soubor schématu.

Zkontrolujte, že váš prostředek DSC má správnou strukturu a obsahuje všechny požadované soubory. Každý prostředek DSC založený na MOF by měl mít schema.mof soubor. Prostředky DSC založené na MOF, které nemají soubor schématu, nebudou uvedené v seznamu a autoři konfigurace DSC nezískají IntelliSense pro tyto prostředky DSC při vytváření konfigurace DSC v nástroji Get-DscResource VS Code.

Adresářová struktura prostředku xRemoteFile DSC, který je součástí modulu xPSDesiredStateConfiguration , vypadá takto:

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

Prostředek DSC se načte bez chyb.

Prostředky DSC by se měly načítat bez chyb. Pokud to chcete ověřit, spusťte Import-Module <resource_module> -Force a potvrďte, že příkaz nevyvolá žádné chyby.

Prostředek DSC je idempotentní

Prostředky DSC by měly být idempotentní. Prostředek DSC je idempotentní, když můžete vícekrát vyvolat metodu Set prostředku DSC se stejnými vlastnostmi a vždy dosáhnout stejného výsledku.

Například s tímto parametrem hash definující požadovaný stav hodnoty klíče registru pomocí Registry prostředku DSC z modulu PSDscResources :

$DscParameters = @{
    Name       = 'Registry'
    ModuleName = 'PSDscResources'
    Property   = @{
        Key       = 'HKEY_CURRENT_USER\DscExample'
        Ensure    = 'Present'
        Force     = $true
        ValueName = 'Test'
        ValueData = 'Example'
        ValueType = 'String'
    }
}

Při prvním volání Invoke-DscResource -Method Set @DscParametersby se DscExample měl klíč registru objevit v podregistru HKEY_CURRENT_USER s hodnotou Test nastavenou na Example. Budoucí vyvolání by nemělo měnit stav systému.

Pokud chcete zajistit, aby byl prostředek idempotentní, můžete ho otestovat přímo nebo pomocí Invoke-DscResourcepříkazu .

Přímé testování prostředku DSC založeného na MOF:

  1. Spusťte funkci prostředku Set-TargetResource DSC.
  2. Zkontrolujte stav systému a ověřte, že je v požadovaném stavu bez nežádoucího nastavení.
  3. Znovu spusťte funkci Set-TargetResource prostředku DSC. Nemělo by to vyvolávat žádné chyby.
  4. Opakujte kroky 2 až 3, dokud nebudete spokojeni s tím, že volání Set-TargetResource nastaví požadovaný stav podle očekávání a bez chyb.

Přímé testování prostředku DSC založeného na třídě:

  1. Vytvořte novou instanci třídy prostředku DSC a uložte ji do proměnné jako objekt.
  2. Nastavte hodnotu každé vlastnosti na požadovaný stav objektu.
  3. Zavolejte metodu Set objektu.
  4. Zkontrolujte stav systému a ověřte, že je v požadovaném stavu bez nežádoucího nastavení.
  5. Znovu zavolejte metodu Set na objektu. Nemělo by to vyvolávat žádné chyby.
  6. Opakujte kroky 4 až 5, dokud nebudete spokojeni s tím, že volání metody Set nastaví požadovaný stav pouze podle očekávání a bez chyb.

Testování prostředku DSC pomocí Invoke-DscResource:

  1. Spusťte Invoke-DscResource metodu Set .
  2. Zkontrolujte stav systému a ověřte, že je v požadovaném stavu bez nežádoucího nastavení.
  3. Spusťte Invoke-DscResource metodu Set .
  4. Opakujte kroky 2 až 3, dokud nebudete spokojeni s tím, že volání Invoke-DscResource pomocí metody Set nastaví požadovaný stav pouze podle očekávání a bez chyb.

Scénář testování změn uživatele

Prostředky DSC by se měly chovat předvídatelně i v případě, že uživatelé změní stav systému ručně mimo DSC. Tady jsou kroky, které byste měli provést k ověření chování prostředku DSC při úpravě systému uživatelem:

  1. Začněte systémem, který není v požadovaném stavu.
  2. Spuštění Invoke-DscResource -Method Set s prostředkem
  3. Ověření Invoke-DscResource -Method Test vrácení $true
  4. Nastavení nakonfigurované položky tak, aby byla mimo požadovaný stav
  5. Ověření Invoke-DscResource -Method Test vrácení $false

Tady je konkrétnější příklad použití Registry prostředku DSC:

  1. Začněte klíčem registru, který není v požadovaném stavu.
  2. Spusťte Invoke-DscResource -Method Test příkaz s vlastnostmi požadovaného stavu a ujistěte se, že vlastnost InDesiredState výsledku je $false.
  3. Spusťte Invoke-DscResource -Method Get příkaz s požadovanými vlastnostmi a ujistěte se, že nahlášený stav neodpovídá požadovaným vlastnostem stavu.
  4. Spusťte Invoke-DscResource -Method Set příkaz s požadovanými vlastnostmi stavu a ujistěte se, že nedojde k chybě.
  5. Spusťte Invoke-DscResource -Method Test znovu a ujistěte se, že vlastnost InDesiredState výsledku je nyní true.
  6. Spusťte Invoke-DscResource -Method Get znovu a ujistěte se, že nahlášený stav odpovídá požadovaným vlastnostem stavu.
  7. Nastavte hodnotu klíče tak, aby nebyl v požadovaném stavu.
  8. Znovu spusťte Invoke-DscResource -Method Get příkaz a ověřte změněný stav.
  9. Spusťte Invoke-DscResource -Method Test znovu a ověřte, že vrátí hodnotu false.

Přímé volání funkcí a metod prostředků DSC

Nezapomeňte otestovat *-TargetResource funkce (pro prostředky DSC založené na MOF) a metody Get, Set a Test (pro prostředky DSC založené na třídách) tak, že je zavoláte přímo a ověříte, že fungují podle očekávání.

Testování kompatibility na všech podporovaných platformách

Prostředky DSC by měly fungovat na jakékoli platformě, na které je DSC podporováno. Pokud váš prostředek DSC na některých z těchto platforem záměrně nefunguje, vraťte konkrétní chybovou zprávu. Ujistěte se, že prostředek DSC kontroluje, jestli jsou rutiny, které voláte, přítomné na konkrétním počítači.

Poznámka

Jednou z běžných testovacích mezer je ověření prostředku DSC pouze na serverových verzích Windows. Prostředky DSC jsou často také navržené tak, aby pracovaly na SKU klientů. Ujistěte se, že testujete chování pro skladové položky klienta nebo chybu, pokud je váš prostředek DSC nepodporuje.

Get-DSCResource seznam prostředků DSC

Když je modul nainstalovaný, Get-DscResource měl by do výstupu rutiny zahrnout váš prostředek DSC.

Modul obsahuje příklady.

Vytvořte příklady kvality, které uživatelům pomůžou pochopit, jak používat prostředky DSC. To je zásadní, protože uživatelé často nakládají s ukázkovým kódem jako s dokumentací.

Nejprve určete, jaké příklady se mají zahrnout do modulu. Měli byste alespoň pokrýt nejdůležitější případy použití prostředků DSC.

Pokud váš modul obsahuje několik prostředků DSC, které potřebují spolupracovat pro ucelený scénář, nejprve napište základní ucelený příklad.

Napište své počáteční příklady co nejsušnější a nejkratší. Ukažte, jak začít pracovat s prostředky DSC v malých spravovatelných blocích, jako je například vytvoření nového virtuálního pevného disku. Napište si pozdější příklady, abyste mohli stavět na dřívějších příkladech (například vytvoření virtuálního počítače z virtuálního pevného disku) a ukázat pokročilé funkce (například vytvoření virtuálního počítače s dynamickou pamětí).

Pro každý příklad:

  • Napište krátký popis vysvětlující jeho účel a způsob použití libovolných parametrů.
  • Ověřte, že každý příklad běží bez neúmyslných chyb nebo upozornění a vynucuje požadovaný stav.

Chybové zprávy jsou srozumitelné a pomáhají uživatelům řešit problémy.

Dobré chybové zprávy by měly:

  • Existuje: Bez chybové zprávy nebude uživatel ani vědět, že se něco pokazilo.
  • Být čitelný pro člověka: Žádné skryté kódy chyb.
  • Buďte přesní: Přesně popište problém.
  • Buďte konstruktivní: Poskytněte rady, jak problém vyřešit.
  • Buďte zdvořilí: Neobviňujte uživatele nebo ho nenuťte, aby se cítil špatně.

Ujistěte se, že jste ověřili chyby v kompletních scénářích, protože se můžou lišit od chyb vrácených při spuštění funkcí (u prostředků DSC založených na MOF) nebo metod (u prostředků DSC založených na třídách).

Implementace prostředku DSC neobsahuje pevně zakódované cesty.

Ujistěte se, že v žádné implementaci prostředků DSC nejsou žádné pevně zakódované cesty, zejména pokud předpokládají jazyk, jako en-USje . Pokud je to možné, používejte proměnné systémového prostředí.

Například místo:

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

Zápis:

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

Implementace prostředku DSC neobsahuje informace o uživateli.

Prostředky DSC by nikdy neměly v kódu obsahovat identifikovatelné osobní údaje. Ujistěte se, že kód neobsahuje žádná jména e-mailů, informace o účtu ani jména lidí.

Testováno s platnými a neplatnými přihlašovacími údaji

Pokud váš prostředek DSC přebírá jako parametr přihlašovací údaje:

  • Ověřte, že se prostředek DSC chová podle očekávání, když účet nemá přístup.
  • Ověřte, že prostředek DSC funguje s přihlašovacími údaji zadanými pro get, set a test.
  • Pokud váš prostředek DSC přistupuje ke sdíleným složkám, otestujte všechny varianty, které potřebujete podporovat, například:
    • Standardní sdílené složky windows
    • Sdílené složky DFS
    • Sdílené složky SAMBA (pokud chcete podporovat Linux)

Prostředek DSC nevyžaduje interaktivní vstup

Prostředky DSC by nikdy neměly zobrazovat výzvu k zadání vstupu. Místo toho by všechny požadované hodnoty měly být vlastnosti prostředku DSC. Například místo zobrazení výzvy uživatele Get-Credentialpřidejte vlastnost Přihlašovací údaje do prostředku DSC.

Důkladné testování

Tento kontrolní seznam obsahuje položky, které jsou důležité pro testování a které jsou často vynechány. Pro prostředek DSC byste také měli napsat funkční a kompletní testovací případy, abyste zajistili očekávané chování. Nezapomeňte použít negativní testovací případy a testovat neplatný vstup.