Použití rozšíření Cookiecutter

Cookiecutter poskytuje grafické uživatelské rozhraní pro zjišťování šablon, možností vstupní šablony a vytváření projektů a souborů. Visual Studio 2017 a novější obsahuje rozšíření Cookiecutter. Dá se nainstalovat samostatně ve starších verzích sady Visual Studio.

V sadě Visual Studio je rozšíření Cookiecutter k dispozici v průzkumníku View>Cookiecutter:

Požadavky

• Visual Studio. Pokud chcete nainstalovat produkt, postupujte podle kroků v části Instalace sady Visual Studio.

• Python 3.3 nebo novější (32bitová nebo 64bitová verze) nebo Anaconda 3 4.2 nebo novější (32bitová nebo 64bitová verze).

  • Pokud není dostupný vhodný interpret Pythonu, zobrazí Visual Studio upozornění.

  • Pokud nainstalujete interpret Pythonu, když je sada Visual Studio spuštěná, vyberte na panelu nástrojů Průzkumníka cookiecutter možnost Domů a detekujte nově nainstalovaný interpret. Další informace najdete v tématu Vytváření a správa prostředí Pythonu v sadě Visual Studio.

Práce s Průzkumníkem cookiecutter

V Průzkumníku cookiecutter můžete procházet a vybírat šablony, klonovat šablony do místního počítače, nastavit možnosti šablon a vytvořit kód ze šablon.

Procházet šablony

Šablony můžete procházet v Průzkumníku cookiecutter a zjistit, co je už nainstalované a co je k dispozici.

1. V Průzkumníku cookiecutter vyberte na panelu nástrojů možnost Domů a zobrazte dostupné šablony.

   

   Na domovské stránce se zobrazí seznam šablon, ze které si můžete vybrat, uspořádané do čtyř možných skupin:

   Seskupit	Popis	Notes
   Nainstalován	Šablony nainstalované do místního počítače. Při použití online šablony se jeho úložiště automaticky naklonuje do podsložky ~/.cookiecutters.	Nainstalovanou šablonu můžete ze systému odebrat výběrem možnosti Odstranit na panelu nástrojů Průzkumníka cookiecutter.
   Doporučené	Šablony načtené z doporučeného informačního kanálu Microsoft se vytkne výchozího informačního kanálu.	Informační kanál můžete přizpůsobit podle kroků v části Nastavení možností Cookiecutter.
   GitHub	Výsledky hledání v GitHubu pro klíčové slovo "cookiecutter". Seznam úložišť Git se vrátí ve stránkovaném formuláři.	Pokud seznam výsledků překročí aktuální zobrazení, můžete v seznamu vybrat možnost Načíst další a zobrazit další sadu stránkovaných výsledků.
   Vlastní	Všechny vlastní šablony definované prostřednictvím Průzkumníka cookiecutter. Při zadání vlastního umístění šablony do vyhledávacího pole Cookiecutter Explorer se umístění zobrazí v této skupině.	Vlastní šablonu můžete definovat zadáním úplné cesty k úložišti Git nebo úplnou cestou ke složce na místním disku.

2. Pokud chcete zobrazit nebo skrýt seznam dostupných šablon pro určitou kategorii, vyberte šipku vedle kategorie.

Klonování šablon

V Průzkumníku cookiecutter můžete pracovat s dostupnými šablonami a vytvářet místní kopie, ze které budou fungovat.

1. V Průzkumníku cookiecutter vyberte šablonu. Informace o vybrané šabloně se zobrazí v dolní části domovské stránky Cookiecutter Explorer .

   

   Souhrn šablony obsahuje odkazy na další informace o šabloně. Můžete přejít na stránku úložiště GitHub pro šablonu, zobrazit wikiweb šablony nebo najít nahlášené problémy.

2. Pokud chcete naklonovat vybranou šablonu, vyberte Další. Cookiecutter vytvoří místní kopii šablony.

Chování klonování závisí na typu vybrané šablony:

Typ šablony	Chování
Nainstalován	Pokud byla vybraná šablona nainstalována v předchozí relaci sady Visual Studio, automaticky se odstraní a naklonuje se na místním počítači nejnovější verze.
Doporučené	Vybraná šablona se naklonuje a nainstaluje do místního počítače.
GitHub	Vybraná šablona se naklonuje a nainstaluje do místního počítače.
Vlastní vyhledávání	- Adresa URL: Pokud zadáte vlastní adresu URL úložiště Git do vyhledávacího pole Cookiecutter Explorer a pak vyberete šablonu, vybraná šablona se naklonuje a nainstaluje do místního počítače. - Cesta ke složce: Pokud do vyhledávacího pole zadáte vlastní cestu ke složce a vyberete šablonu, Visual Studio tuto šablonu načte bez klonování.

Důležité

Šablony cookiecutter se naklonují pod jednou složkou ~/.cookiecutters. Každá podsložka má název úložiště Git, který nezahrnuje uživatelské jméno GitHubu. Konflikty můžou nastat, pokud naklonujete různé šablony se stejným názvem, který pochází od různých autorů. V tomto případě vám Cookiecutter brání v přepsání existující šablony s jinou šablonou se stejným názvem. Pokud chcete nainstalovat jinou šablonu, musíte nejprve odstranit existující šablonu.

Nastavení možností šablony

Po instalaci a klonování šablony místně soubor Cookiecutter zobrazí stránku Možnosti . Na této stránce můžete zadat nastavení, například umístění cesty ke složce pro vygenerované soubory:

Každá šablona Cookiecutter definuje vlastní sadu možností. Pokud je pro nastavení k dispozici výchozí hodnota, zobrazí se na stránce Možnosti navrhovaný text v odpovídajícím poli. Výchozí hodnota může být fragment kódu, často když se jedná o dynamickou hodnotu, která používá jiné možnosti.

V tomto příkladu je název šablony definován jako cookiecutter-flask/cookiecutter-flask. Při změně hodnoty nastavení je text pole k dispozici pro úpravy.

1. Do pole Vytvořit pro zadejte umístění cesty ke složce pro všechny soubory vygenerované souborem Cookiecutter.

2. Dále nastavte další požadované možnosti šablony, například:

   • full_name: Úplný název, který se má použít u šablony.
   • e-mail: E-mailová adresa autora šablony.
   • github_username: Alias GitHubu autora šablony.
   • python_version: Cílová verze Pythonu pro webové aplikace vytvořené ze šablony.

Nastavení výchozích hodnot pomocí konfiguračního souboru

Výchozí hodnoty můžete přizpůsobit pro konkrétní možnosti pomocí konfiguračního souboru uživatele. Když rozšíření Cookiecutter zjistí konfigurační soubor uživatele, přepíše výchozí hodnoty šablony hodnotami konfiguračního souboru. Další informace o tomto chování naleznete v části Konfigurace uživatele v dokumentaci cookiecutter.

Odhlášení ze zadaných úkolů

Některé šablony identifikují konkrétní úlohy sady Visual Studio, které se mají spustit po generování kódu. Mezi běžné úlohy patří otevření webového prohlížeče, otevírání souborů v editoru a instalace závislostí. Když šablona identifikuje konkrétní úlohy, přidá se do seznamu možností nastavení Spustit další úkoly při dokončení . Toto nastavení můžete nakonfigurovat tak, aby se odhlásilo ze zadaných úloh sady Visual Studio.

Vytvoření kódu ze šablon

Jakmile nastavíte možnosti šablony, budete připraveni na Cookiecutter vytvořit soubory projektu a vygenerovat kód.

V dialogovém okně se za seznamem možností zobrazí tlačítko. Text tlačítka závisí na šabloně. Může se zobrazit možnost Vytvořit a otevřít složku, Přidat do řešení atd.

1. Na stránce Možnosti vyberte tlačítko, které následuje za seznamem možností, například Vytvořit a Otevřít složku nebo Přidat do řešení.

   

   Cookiecutter vygeneruje kód. Pokud výstupní složka není prázdná, zobrazí se upozornění.

   • Pokud znáte výstup šablony a nevadí vám přepsání souborů, zavřete upozornění tak, že vyberete OK .

   • V opačném případě vyberte Storno, zadejte prázdnou složku a potom ručně zkopírujte vytvořené soubory do výstupní složky, která není bez náporu.

2. Jakmile Soubor Cookiecutter úspěšně vytvoří soubory, Visual Studio otevře soubory projektu šablony v Průzkumník řešení.

Nastavení možností cookiecutteru

Možnosti cookiecutter jsou k dispozici prostřednictvím nástrojů>Možnosti>Cookiecutter:

Možnost	Popis
Kontrola aktualizovaných šablon	Určuje, zda Cookiecutter automaticky kontroluje online aktualizace nainstalovaných šablon.
Doporučená adresa URL informačního kanálu	Umístění doporučeného souboru informačního kanálu šablon Umístění může být adresa URL nebo cesta k místnímu souboru. Ponechte adresu URL prázdnou, aby používala výchozí kurátorovaný informační kanál Microsoftu. Informační kanál poskytuje jednoduchý seznam umístění šablon oddělených novými spojnicemi. Pokud chcete požádat o změny kurátorovaných informačních kanálů, vytvořte žádost o přijetí změn vůči zdroji na GitHubu.
Zobrazit nápovědu	Řídí viditelnost informačního panelu nápovědy v horní části okna Cookiecutter.

Optimalizace šablon cookiecutter pro Visual Studio

Rozšíření Cookiecutter pro Visual Studio podporuje šablony vytvořené pro Cookiecutter v1.4. Další informace o vytváření šablon Cookiecutter naleznete v dokumentaci cookiecutter.

Výchozí vykreslování proměnných šablony závisí na typu dat (řetězec nebo seznam):

• Řetězec: Datový typ String používá popisek pro název proměnné, textové pole pro zadání hodnoty a vodoznak, který zobrazuje výchozí hodnotu. Popis v textovém poli zobrazuje výchozí hodnotu.
• Seznam: Datový typ Seznam používá popisek pro název proměnné a pole se seznamem pro výběr hodnoty. Popis v poli se seznamem zobrazuje výchozí hodnotu.

Vykreslování můžete vylepšit zadáním dalších metadat v souboru cookiecutter.json , který je specifický pro Visual Studio (a ignorovaný rozhraním příkazového řádku Cookiecutter). Všechny vlastnosti jsou volitelné:

Vlastnost	Popis
label	Určuje text, který se má zobrazit nad editorem proměnné místo názvu proměnné.
description	Určuje popis, který se má zobrazit v ovládacím prvku pro úpravy místo výchozí hodnoty pro danou proměnnou.
url	Změní popisek na hypertextový odkaz s popisem, který zobrazuje adresu URL. Výběrem hypertextového odkazu se otevře výchozí prohlížeč uživatele na tuto adresu URL.
selector	Umožňuje přizpůsobení editoru pro proměnnou. V současné době jsou podporovány následující selektory: - string: Standardní textové pole, výchozí pro řetězce. - list: Standardní pole se seznamem, výchozí pro seznamy. - yesno: Pole se seznamem pro výběr mezi y řetězci a n, - odbcConnection: Textové pole s tlačítkem se třemi tečkami (...), které otevře dialogové okno připojení k databázi.

Následující příklad ukazuje, jak nastavit vlastnosti vykreslování:

{
    "site_name": "web-app",
    "python_version": ["3.5.2"],
    "use_azure": "y",

    "_visual_studio": {
        "site_name": {
            "label": "Site name",
            "description": "E.g. <site-name>.azurewebsites.net (can only contain alphanumeric characters and `-`)"
        },
        "python_version": {
            "label": "Python version",
            "description": "The version of Python to run the site on"
        },
        "use_azure" : {
            "label": "Use Azure",
            "description": "Include Azure deployment files",
            "selector": "yesno",
            "url": "https://azure.microsoft.com"
        }
    }
}

Spouštění úloh sady Visual Studio

Cookiecutter má funkci s názvem Post-Generate Hooks , která umožňuje spustit libovolný kód Pythonu po vygenerování souborů. I když je tato funkce flexibilní, neumožňuje snadný přístup k sadě Visual Studio.

Pomocí této funkce můžete otevřít soubor v editoru sady Visual Studio nebo ve webovém prohlížeči. Můžete také aktivovat uživatelské rozhraní sady Visual Studio, které uživatele vyzve k vytvoření virtuálního prostředí a instalaci požadavků na balíček.

Aby bylo možné tyto scénáře povolit, Visual Studio hledá v souboru cookiecutter.json rozšířená metadata. Vyhledá příkazy, které se mají spustit po otevření vygenerovaných souborů v Průzkumník řešení nebo po přidání souborů do existujícího projektu. (Uživatel se může opět odhlásit ze spuštění úkolů zrušením zaškrtnutí políčka Spuštění dalších úloh při dokončení šablony.)

Následující příklad ukazuje, jak nastavit rozšířená metadata v souboru cookiecutter.json :

"_visual_studio_post_cmds": [
    {
        "name": "File.OpenFile",
        "args": "{{cookiecutter._output_folder_path}}\\readme.txt"
    },
    {
        "name": "Cookiecutter.ExternalWebBrowser",
        "args": "https://learn.microsoft.com"
    },
    {
        "name": "Python.InstallProjectRequirements",
        "args": "{{cookiecutter._output_folder_path}}\\dev-requirements.txt"
    }
]

Zadejte příkazy podle názvu a použijte nelokalizovaný (anglický) název pro práci s lokalizovanými instalacemi sady Visual Studio. Názvy příkazů můžete testovat a zjišťovat v okně příkazového řádku sady Visual Studio.

Pokud chcete předat jeden argument, zadejte argument jako řetězec, jak je znázorněno pro name metadata v předchozím příkladu.

Pokud nepotřebujete předat argument, nechejte hodnotu jako prázdný řetězec nebo ji v souboru JSON vynecháte:

"_visual_studio_post_cmds": [
    {
        "name": "View.WebBrowser"
    }
]

Pro více argumentů použijte matici. U přepínačů rozdělte přepínač a jeho hodnotu do samostatných argumentů a použijte správné uvozování, jak je znázorněno v tomto příkladu:

"_visual_studio_post_cmds": [
    {
        "name": "File.OpenFile",
        "args": [
            "{{cookiecutter._output_folder_path}}\\read me.txt",
            "/e:",
            "Source Code (text) Editor"
        ]
    }
]

Argumenty mohou odkazovat na jiné proměnné Cookiecutter. V předchozím příkladu se interní _output_folder_path proměnná používá k vytvoření absolutní cesty k vygenerování souborů.

Příkaz Python.InstallProjectRequirements funguje jenom při přidávání souborů do existujícího projektu. Toto omezení existuje, protože příkaz zpracovává projekt Pythonu v Průzkumník řešení a v zobrazení Průzkumník řešení - Folder neexistuje žádný projekt, který by zprávu přijal.

Řešení potíží se šablonou

V následujících částech najdete tipy k řešení potíží s prostředím Pythonu a kódem při práci se souborem Cookiecutter.

Chyba při načítání šablony

Některé šablony můžou v souboru cookiecutter.json použít neplatné datové typy, jako je například logická hodnota. Tyto instance můžete nahlásit autorovi šablony tak , že v podokně informací o šabloně vyberete odkaz Problémy .

Skript háku selhal

Některé šablony můžou používat skripty po generování, které nejsou kompatibilní s uživatelským rozhraním Cookiecutter. Například skripty, které dotazují uživatele na vstup, můžou selhat kvůli nedostatku konzoly terminálu.

Skript hooku není ve Windows podporován.

Pokud je soubor post script .sh, nemusí být přidružen k aplikaci na počítači s Windows. Může se zobrazit dialogové okno Windows s výzvou k vyhledání kompatibilní aplikace ve Windows Storu.

Šablony se známými problémy

Pokud šablona obsahuje známé problémy, můžete zjistit pomocí odkazu Problémy v souhrnu šablony v Průzkumníku cookiecutter:

Odkaz otevře stránku s problémy GitHubu pro šablonu:

Související obsah

• Referenční dokumentace šablon položek Pythonu
• Cookiecutter: Lepší šablony projektů