A Cookiecutter bővítmény használata

Cookiecutter grafikus felhasználói felületet biztosít a sablonok felderítéséhez, a sablonbeállítások beviteléhez, valamint projektek és fájlok létrehozásához. A Visual Studio 2017 és újabb verziói tartalmazzák a Cookiecutter bővítményt. A Visual Studio korábbi verzióiban külön telepíthető.

A Visual Studio alkalmazásban a Cookiecutter bővítmény a >Cookiecutter Exploreralatt érhető el:

Előfeltételek

• Visual Studio. A termék telepítéséhez kövesse a Visual Studio telepítéselépéseit.

• Python 3.3 vagy újabb (32 bites vagy 64 bites) vagy Anaconda 3 4.2 vagy újabb (32 bites vagy 64 bites).

  • Ha nem érhető el megfelelő Python-értelmező, a Visual Studio figyelmeztetést jelenít meg.

  • Ha Python-értelmezőt telepít a Visual Studio futtatása közben, válassza a Kezdőlap lehetőséget a Cookiecutter Explorer eszköztáron az újonnan telepített értelmező észleléséhez. További információ: Python-környezetek létrehozása és kezelése a Visual Studio.

A Cookiecutter Explorerrel való munka

A Cookiecutter Explorerböngészhet és kiválaszthat sablonokat, sablonokat klónozhat a helyi számítógépre, megadhatja a sablonbeállításokat, és sablonokat hozhat létre.

Sablonok tallózása

A Cookiecutter Explorer sablonjai között böngészve megtekintheti a már telepített és elérhető elemeket.

1. Az Cookiecutter Explorereszköztáron válassza a Kezdőlap lehetőséget az elérhető sablonok megtekintéséhez.

   

   A kezdőlapon a választható sablonok listája látható, négy lehetséges csoportba rendezve:

   Csoport	Leírás	Jegyzetek
   telepített	A helyi számítógépre telepített sablonok. Online sablon használata esetén a rendszer automatikusan klónozza az adattárát ~/.cookiecuttersalmappájára.	A telepített sablonokat a Cookiecutter Explorer eszköztár Törlés lehetőség kiválasztásával távolíthatja el a rendszerből.
   Ajánlott	Az ajánlott hírcsatornából betöltött sablonok. A Microsoft az alapértelmezett hírcsatornát curatálja.	A hírcsatornát testreszabhatja, ha a Cookiecutter beállításainak lépéseit követi a következőképpen: .
   GitHub	A GitHub a "cookiecutter" kulcsszóra keres. A git-adattárak listája lapszámozott formában jelenik meg.	Ha az eredmények listája meghaladja az aktuális nézetet, a Továbbiak betöltése lehetőséget választva megjelenítheti a lapszámozott találatok következő készletét a listában.
   egyéni	Az Cookiecutter Exploreráltal definiált egyéni sablonok. Ha egyéni sablonhelyet ad meg a Cookiecutter Explorer keresőmezőbe, a hely ebben a csoportban jelenik meg.	Egyéni sablont úgy határozhat meg, hogy megadja a git-adattár teljes elérési útját, vagy a helyi lemez egy mappájának teljes elérési útját.

2. Egy adott kategória elérhető sablonjainak megjelenítéséhez vagy elrejtéséhez válassza a kategória melletti nyíl.

Sablonok klónozása

Az Cookiecutter Explorer elérhető sablonjaival dolgozhat, hogy helyi másolatokat készítsen, amelyekből kiindulva dolgozhat.

1. A Cookiecutter Explorer-ben válasszon ki egy sablont. A kiválasztott sablonra vonatkozó információk a Cookiecutter Explorer kezdőlapjának alján jelennek meg.

   

   A sablon összefoglalása hivatkozásokat tartalmaz a sablonnal kapcsolatos további információkhoz. Nyissa meg a GitHub tárház lapját a sablonhoz, tekintse meg a sablont Wiki, vagy keresse meg a jelentett problémákat.

2. A kijelölt sablon klónozásához válassza a Következőlehetőséget. A Cookiecutter helyi másolatot készít a sablonról.

A klónozás viselkedése a kiválasztott sablon típusától függ:

Sablon típusa	Magatartás
telepített	Ha a kijelölt sablon a Visual Studio egy korábbi munkamenetében lett telepítve, a rendszer automatikusan törli, és a legújabb verziót telepíti és klónozza a helyi számítógépen.
Ajánlott	A kiválasztott sablon klónozása és telepítése a helyi számítógépen történik.
GitHub	A kiválasztott sablon klónozása és telepítése a helyi számítógépen történik.
Egyéni keresés	- URL-: Ha egyéni URL-címet ad meg egy git-adattárhoz a Cookiecutter Explorer keresőmezőbe, majd kiválasztja a sablont, a rendszer klónozza és telepíti a kiválasztott sablont a helyi számítógépen. - mappa elérési útja: Ha egyéni mappa elérési útját adja meg a keresőmezőbe, és kiválasztja a sablont, a Visual Studio klónozás nélkül betölti a sablont.

Fontos

A cookiecutter-sablonok egyetlen mappa alatt vannak klónozva, ~/.cookiecutters. Minden almappát a Git-adattár neve után nevezünk el, amely nem tartalmazza a GitHub-felhasználónevet. Ütközések léphetnek fel, ha azonos nevű, de különböző szerzőktől származó sablonokat klónoz. Ebben az esetben a Cookiecutter megakadályozza, hogy felülírja a meglévő sablont egy másik, azonos nevű sablonnal. A másik sablon telepítéséhez először törölnie kell a meglévőt.

Sablonbeállítások megadása

Miután helyileg telepített és klónozott egy sablont, a Cookiecutter megjeleníti a Beállítások lapot. Ezen a lapon megadhatja a beállításokat, például a létrehozott fájlok mappa elérési útját:

Minden Cookiecutter-sablon saját beállításokat határoz meg. Ha egy beállításhoz alapértelmezett érték érhető el, a Beállítások lapon a megfelelő mezőben javasolt szöveg jelenik meg. Az alapértelmezett érték lehet kódrészlet, gyakran olyan dinamikus érték, amely más beállításokat használ.

Ebben a példában a sablon neve cookiecutter-flask/cookiecutter-flask. Ha egy beállítási érték módosítható, a mező szövege szerkeszthető.

1. A Létrehozás mezőbe írja be a mappa elérési útját bármely Cookiecutter által generált fájl esetében.

2. Ezután adja meg a sablon egyéb kívánt beállításait, például:

   • full_name: A sablonra alkalmazandó teljes név.
   • e-mail-: A sablon szerzője e-mail-címe.
   • github_username: A sablonkészítő GitHub-aliasa.
   • python_version: A sablonból létrehozott webalkalmazások cél Python-verziója.

Alapértelmezett beállítások beállítása konfigurációs fájllal

A felhasználói konfigurációs fájllal testre szabhatja az adott beállítások alapértelmezett értékeit. Amikor a Cookiecutter bővítmény észlel egy felhasználói konfigurációs fájlt, felülírja a sablon alapértelmezett értékeit a konfigurációs fájl értékeivel. Erről a viselkedésről a Cookiecutter dokumentációjának Felhasználói konfiguráció szakaszában talál további információt.

A megadott tevékenységek letiltása

Egyes sablonok konkrét Visual Studio-feladatokat azonosítanak, amelyeket kódgenerálás után kell futtatni. A gyakori feladatok közé tartozik a webböngésző megnyitása, a fájlok megnyitása a szerkesztőben, valamint a függőségek telepítése. Ha egy sablon meghatározott tevékenységeket azonosít, a További feladatok futtatása befejezéskor beállítás hozzáadódik a beállítások listájához. Ezt a beállítást úgy konfigurálhatja, hogy kikapcsolja a megadott Visual Studio-feladatokat.

Kód létrehozása sablonokból

Miután megadta a sablonbeállításokat, készen áll arra, hogy a Cookiecutter létrehozza a projektfájlokat, és létrehozza a kódot.

A párbeszédpanelen megjelenik egy gomb a beállítások listája után. A gomb szövege a sablontól függ. Előfordulhat, hogy a következőket látja: Mappa létrehozása és megnyitása, Hozzáadás a megoldáshoz, és így tovább.

1. A Beállítások lapon válassza ki a beállítások listáját követő gombot, például Mappa létrehozása és megnyitása vagy Hozzáadás a megoldáshoz.

   

   A Cookiecutter létrehozza a kódot. Ha a kimeneti mappa nem üres, figyelmeztetés jelenik meg.

   • Ha ismeri a sablon kimenetét, és nem bánja a fájlok felülírását, válassza az OK lehetőséget a figyelmeztetés elvetéséhez.

   • Ellenkező esetben válassza a Mégselehetőséget, adjon meg egy üres mappát, majd másolja manuálisan a létrehozott fájlokat a nem megfelelő kimeneti mappába.

2. Miután a Cookiecutter sikeresen létrehozta a fájlokat, a Visual Studio megnyitja a sablonprojektfájlokat Megoldáskezelő.

Cookiecutter-beállítások megadása

A Cookiecutter beállítások az Tools>Options>Cookiecutterhasználatával érhetők el:

Opció	Leírás
Frissített sablonok keresése	Azt szabályozza, hogy a Cookiecutter automatikusan online ellenőrzi-e a telepített sablonok frissítéseit.
ajánlott hírcsatorna URL	Az ajánlott sablonokhoz tartozó hírcsatornafájl helye. A hely lehet EGY URL-cím vagy egy helyi fájl elérési útja. Hagyja üresen az URL-címet az alapértelmezett Microsoft-válogatott hírcsatorna használatához. A feed egyszerű sablonhelyek listáját nyújtja, sortörésekkel elválasztva. Ha módosítani szeretné a válogatott hírcsatornát, küldjön pull requestet a forrásra a GitHubon.
Súgó megjelenítése	A Cookiecutter ablak tetején található súgóinformációs sáv láthatóságát szabályozza.

Cookiecutter-sablonok optimalizálása a Visual Studióhoz

A Visual Studio Cookiecutter bővítménye támogatja a Cookiecutter v1.4-hez létrehozott sablonokat. A Cookiecutter-sablonok készítéséről a Cookiecutter dokumentációjábantalál további információt.

A sablonváltozók alapértelmezett renderelése az adatok típusától (sztring vagy lista) függ:

• Sztring: A sztring adattípus a változó nevének címkéjét, az érték megadására szolgáló szövegdobozt és az alapértelmezett értéket megjelenítő vízjelet használja. A szövegmező fölött megjelenő buboréksúgó az alapértelmezett értéket mutatja.
• Lista: A Lista adattípus a változó nevének címkéjét és egy kombinált listát használ az érték kiválasztásához. A kombinált lista mezőjének elemleírása az alapértelmezett értéket jeleníti meg.

A renderelés javításához meg kell adnia a cookiecutter.json fájlban található egyéb metaadatokat, amelyek a Visual Studióra vonatkoznak (és amelyeket a Cookiecutter parancssori felület figyelmen kívül hagy). Az összes tulajdonság megadása nem kötelező:

Ingatlan	Leírás
label	A változó szerkesztője fölött megjelenítendő szöveget adja meg a változó neve helyett.
description	A szerkesztési vezérlőn megjelenítendő elemleírást adja meg a változó alapértelmezett értéke helyett.
url	A címkét az URL-címet megjelenítő elemleírással ellátott hivatkozásra módosítja. A hivatkozás kiválasztásával megnyílik a felhasználó alapértelmezett böngészője erre az URL-címre.
selector	Lehetővé teszi a szerkesztő testreszabását egy változóhoz. Jelenleg a következő választók támogatottak: - string: Standard szövegmező, karakterláncok alapértelmezett szövegként. - list: Standard kombinált doboz, a listák alapértelmezése. - yesno: A sztringek y és nközötti választáshoz használható kombinált lista. - odbcConnection: Szövegdoboz ellipszis gombbal (...), amely megnyit egy adatbázis-kapcsolat párbeszédpanelt.

Az alábbi példa bemutatja, hogyan állíthatja be a renderelési tulajdonságokat:

{
    "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"
        }
    }
}

Visual Studio-feladatok futtatása

A Cookiecutter egy Post-Generate Hooks nevű funkcióval rendelkezik, amely lehetővé teszi tetszőleges Python-kód futtatását a fájlok létrehozása után. Bár a funkció rugalmas, nem teszi lehetővé a Visual Studio könnyű elérését.

Ezzel a funkcióval megnyithat egy fájlt a Visual Studio-szerkesztőben vagy annak webböngészőjében. A Visual Studio felhasználói felületét is aktiválhatja, amely arra kéri a felhasználót, hogy hozzon létre egy virtuális környezetet, és telepítse a csomagkövetelményeket.

Az ilyen forgatókönyvek engedélyezéséhez a Visual Studio kiterjesztett metaadatokat keres a cookiecutter.json fájlban. Megkeresi a futtatandó parancsokat, miután a felhasználó megnyitja a létrehozott fájlokat a Megoldáskezelőben vagy miután a fájlokat hozzáadta egy meglévő projekthez. (A felhasználó ismét kikapcsolhatja a feladatok futtatását a További feladatok futtatása befejezéskor sablonbeállítás törlésével.)

Az alábbi példa bemutatja, hogyan állíthat be kiterjesztett metaadatokat a cookiecutter.json fájlban:

"_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"
    }
]

Adja meg a parancsokat név szerint, és használja a nem helyi (angol) nevet a Visual Studio honosított telepítéseinek használatához. A Visual Studio Parancs ablakban tesztelheti és felderítheti a parancsneveket.

Ha egyetlen argumentumot szeretne átadni, adja meg az argumentumot sztringként az előző példában látható name metaadatoknak megfelelően.

Ha nem kell argumentumot átadnia, hagyja üres sztringként az értéket, vagy hagyja ki a JSON-fájlból:

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

Több argumentum esetén használjon tömböt. Kapcsolók esetén ossza fel a kapcsolót és annak értékét külön argumentumokra, és használjon megfelelő idézőjeleket, ahogyan az ebben a példában látható:

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

Az argumentumok más Cookiecutter-változókra is hivatkozhatnak. Az előző példában a belső _output_folder_path változó a fájlok létrehozásának abszolút elérési útját képezi.

A Python.InstallProjectRequirements parancs csak akkor működik, ha fájlokat ad hozzá egy meglévő projekthez. Ez a korlátozás azért létezik, mert a parancsot a Python-projekt dolgozza fel a Megoldáskezelőben, és nincs projekt, amely fogadná az üzenetet, amikor a Megoldáskezelő - Mappa nézetben van.

Sablonproblémák elhárítása

A Következő szakaszokban tippeket találhat a Python-környezet és -kód hibaelhárításához a Cookiecutter használatakor.

Hiba a sablon betöltésekor

Egyes sablonok érvénytelen adattípusokat használhatnak a cookiecutter.json fájlban, például logikai értékeket. Ezeket az eseményeket jelentheti a sablon készítőjének a sabloninformációs panelen lévő Problémák hivatkozás kiválasztásával.

Nem sikerült a hook script futtatása

Egyes sablonok olyan, generáció utáni szkripteket használhatnak, amelyek nem kompatibilisek a Cookiecutter felhasználói felületével. A felhasználót bemenetként lekérdező szkriptek például a terminálkonzol hiánya miatt meghiúsulhatnak.

A hook script nem támogatott Windows rendszeren

Ha a postscript fájl .sh, előfordulhat, hogy nincs társítva egy alkalmazáshoz a Windows számítógépén. Előfordulhat, hogy megjelenik egy Windows-párbeszédpanel, amely megkeres egy kompatibilis alkalmazást a Windows Áruházban.

Ismert problémákat tartalmazó sablonok

A Cookiecutter Explorersablonösszesítőjében található Problémák hivatkozás segítségével megtudhatja, hogy egy sablon ismert problémákkal rendelkezik-e:

A hivatkozás megnyitja a sablon GitHub-problémák oldalát:

Kapcsolódó tartalom

• Python-elemsablonok hivatkozási
• Cookiecutter: Kiváló projektsablonok