Verwenden der Cookiecutter-Erweiterung

Cookiecutter stellt eine grafische Benutzeroberfläche bereit, auf der Sie Vorlagen ermitteln, Vorlageoptionen eingeben und Projekte und Dateien erstellen können. Visual Studio 2017 und neuere Versionen enthalten die Cookiecutter-Erweiterung. Sie kann in früheren Versionen von Visual Studio separat installiert werden.

In Visual Studio ist die Cookiecutter-Erweiterung unter View>Cookiecutter Explorer verfügbar:

Voraussetzungen

• Visual Studio. Führen Sie zum Installieren des Produkts die Schritte unter Installieren von Visual Studio aus.

• Python 3.3 oder höher (32-bit oder 64-bit) oder Anaconda 3 4.2 oder höher (32-bit oder 64-bit).

  • Wenn kein geeigneter Python-Interpreter verfügbar ist, zeigt Visual Studio eine Warnung an.

  • Wenn Sie einen Python-Interpreter installieren, während Visual Studio ausgeführt wird, wählen Sie die Option Home in der Symbolleiste Cookiecutter Explorer, um den neu installierten Interpreter zu erkennen. Weitere Informationen finden Sie unter Erstellen und Verwalten von Python-Umgebungen in Visual Studio.

Arbeiten mit Cookiecutter Explorer

In Cookiecutter Explorer können Sie Vorlagen durchsuchen und auswählen, Vorlagen auf Ihren lokalen Computer klonen, Vorlagenoptionen festlegen und Code aus Vorlagen erstellen.

Durchsuchen der Vorlagen

Sie können die Vorlagen in Cookiecutter Explorer durchsuchen, um zu sehen, was bereits installiert ist und was verfügbar ist.

1. Wählen Sie in Cookiecutter Explorer die Option Home in der Symbolleiste, um die verfügbaren Vorlagen anzuzeigen.

   

   Auf der Startseite wird eine Liste von Vorlagen angezeigt, die in vier mögliche Gruppen unterteilt sind:

   Gruppieren	Beschreibung	Hinweise
   Installiert	Auf Ihrem lokalen Computer installierte Vorlagen. Bei Verwendung einer Onlinevorlage wird das zugehörige Repository automatisch in einen Unterordner von ~/.cookiecutters geklont.	Sie können eine installierte Vorlage von Ihrem System entfernen, indem Sie Delete in der Symbolleiste von Cookiecutter Explorer wählen.
   Empfohlen	Aus dem empfohlenen Feed geladene Vorlagen. Der Standard-Feed wird von Microsoft kuratiert.	Sie können den Feed anpassen, indem Sie die Schritte unter Set Cookiecutter options ausführen.
   GitHub	GitHub-Suchergebnisse für das Stichwort „cookiecutter“. Die Liste der Git-Repositorys wird in paginierter Form zurückgegeben.	Wenn die Liste der Ergebnisse die aktuelle Ansicht übersteigt, können Sie die Option Load More wählen, um die nächste Gruppe von paginierten Ergebnissen in der Liste anzuzeigen.
   Benutzerdefiniert	Alle benutzerdefinierten Vorlagen, die über Cookiecutter Explorer definiert wurden. Wenn ein benutzerdefinierter Vorlagenspeicherort in das Suchfeld Cookiecutter Explorer eingegeben wird, erscheint der Speicherort in dieser Gruppe.	Sie können eine benutzerdefinierte Vorlage definieren, indem Sie den vollständigen Pfad zum Git-Repository oder den vollständigen Pfad zu einem Ordner auf Ihrer lokalen Festplatte eingeben.

2. Um die Liste der verfügbaren Vorlagen für eine bestimmte Kategorie ein- oder auszublenden, wählen Sie den Pfeil neben der Kategorie.

Vorlagen klonen

Sie können mit den verfügbaren Vorlagen in Cookiecutter Explorer lokale Kopien zum Arbeiten erstellen.

1. Wählen Sie unter Cookiecutter Explorer eine Vorlage aus. Informationen über die ausgewählte Vorlage werden unten auf der Startseite von Cookiecutter Explorer angezeigt.

   

   Die Zusammenfassung der Vorlage enthält Links zu weiteren Informationen über die Vorlage. Sie können die GitHub-Repository-Seite für die Vorlage besuchen, das Vorlagen-Wiki ansehen oder gemeldete Probleme finden.

2. Um die ausgewählte Vorlage zu klonen, wählen Sie Next . Cookiecutter erstellt eine lokale Kopie der Vorlage.

Das Klonverhalten hängt von der Art der Vorlage ab, die Sie auswählen:

Vorlagentyp	Behavior
Installiert	Wenn die ausgewählte Vorlage in einer früheren Sitzung von Visual Studio installiert wurde, wird sie automatisch gelöscht und die neueste Version wird auf Ihrem lokalen Computer installiert und geklont.
Empfohlen	Die ausgewählte Vorlage wird geklont und auf Ihrem lokalen Computer installiert.
GitHub	Die ausgewählte Vorlage wird geklont und auf Ihrem lokalen Computer installiert.
Benutzerdefinierte Suche	- URL: Wenn Sie eine benutzerdefinierte URL für ein Git-Repository in das Suchfeld Cookiecutter Explorer eingeben und dann die Vorlage auswählen, wird die ausgewählte Vorlage geklont und auf Ihrem lokalen Computer installiert. - Ordnerpfad: Wenn Sie einen benutzerdefinierten Ordnerpfad in das Suchfeld eingeben und die Vorlage auswählen, lädt Visual Studio diese Vorlage ohne Klonen.

Wichtig

Cookiecutter-Vorlagen werden in einem einzigen Ordner geklont: ~/.cookiecutters. Jeder Unterordner wird nach dem Namen des Git-Repositorys benannt, der nicht den GitHub-Benutzernamen enthält. Wenn Sie verschiedene Vorlagen mit dem gleichen Namen, aber von unterschiedlichen Erstellern klonen, können Konflikte auftreten. In diesem Fall verhindert Cookiecutter das Überschreiben der vorhandenen Vorlage mit einer anderen Vorlage des gleichen Namens. Um die andere Vorlage zu installieren, müssen Sie zunächst die vorhandene löschen.

Festlegen von Vorlagenoptionen

Nachdem Sie eine Vorlage lokal installiert und geklont haben, zeigt Cookiecutter die Seite Options an. Auf dieser Seite können Sie Einstellungen vornehmen, wie z. B. den Speicherort des Ordners für die generierten Dateien:

Jede Cookiecutter-Vorlage definiert ihren eigenen Satz von Optionen. Wenn für eine Einstellung ein Standardwert verfügbar ist, wird auf der Seite Options ein Textvorschlag für das entsprechende Feld angezeigt. Ein Standardwert kann ein Codeschnipsel sein, oft wenn es sich um einen dynamischen Wert handelt, der andere Optionen verwendet.

Für dieses Beispiel ist der Name der Vorlage als cookiecutter-flask/cookiecutter-flask definiert. Wenn ein Einstellungswert geändert werden kann, ist der Feldtext zur Bearbeitung verfügbar.

1. Geben Sie in das Feld Create to den Ordnerpfad für die von Cookiecutter erzeugten Dateien ein.

2. Legen Sie dann weitere gewünschte Optionen für die Vorlage fest, wie z. B.:

   • full_name: Der vollständige Name, der für die Vorlage gelten soll.
   • email: Die E-Mail-Adresse des Autors der Vorlage.
   • github_username: Der GitHub-Benutzername des Vorlagenautors.
   • python_version: Die Ziel-Python-Version für Webanwendungen, die mit der Vorlage erstellt werden.

Festlegen von Standardwerten mit einer Konfigurationsdatei

Sie können die Standardwerte für bestimmte Optionen mit einer Benutzerkonfigurationsdatei anpassen. Wenn die Cookiecutter-Erweiterung eine Benutzerkonfigurationsdatei erkennt, überschreibt sie die Standardwerte der Vorlage mit den Werten der Konfigurationsdatei. Weitere Informationen zu diesem Verhalten finden Sie im Abschnitt User Config der Cookiecutter-Dokumentation.

Abmeldung von bestimmten Aufgaben

Einige Vorlagen legen bestimmte Visual Studio-Aufgaben fest, die nach der Codegenerierung ausgeführt werden sollen. Zu den üblichen Aufgaben gehören das Öffnen eines Webbrowsers, das Öffnen von Dateien im Editor und die Installation von Abhängigkeiten. Wenn eine Vorlage bestimmte Aufgaben identifiziert, wird die Einstellung Run additional tasks on completion zur Liste der Optionen hinzugefügt. Sie können diese Einstellung so konfigurieren, dass die angegebenen Visual Studio-Aufgaben nicht ausgeführt werden.

Code aus Vorlagen erstellen

Nachdem Sie Ihre Vorlagenoptionen festgelegt haben, ist Cookiecutter bereit, die Projektdateien zu erstellen und den Code zu generieren.

Im Dialogfeld wird nach der Liste der Optionen eine Schaltfläche angezeigt. Der Text für die Schaltfläche hängt von der Vorlage ab. Sie sehen eventuell Create and Open folder (Ordner erstellen und öffnen), Add to Solution (Zur Lösung hinzufügen), und so weiter.

1. Wählen Sie auf der Seite Options die Schaltfläche, die auf die Liste der Optionen folgt, z. B. Create and Open folder oder Add to Solution.

   

   Cookiecutter erzeugt den Code. Wenn der Ausgabeordner nicht leer ist, wird eine Warnung angezeigt.

   • Wenn Sie mit der Ausgabe der Vorlage vertraut sind und es Ihnen nichts ausmacht, Dateien zu überschreiben, wählen Sie OK, um die Warnung zu ignorieren.

   • Andernfalls wählen Sie Cancel, geben Sie einen leeren Ordner an und kopieren Sie die erstellten Dateien manuell in Ihren nicht leeren Ausgabeordner.

2. Nachdem Cookiecutter die Dateien erfolgreich erstellt hat, öffnet Visual Studio die Vorlagenprojektdateien im Solution Explorer.

Cookiecutter-Optionen einstellen

Cookiecutter-Optionen stehen über Extras>Optionen>Cookiecutter zur Verfügung:

Option	Beschreibung
Nach aktualisierten Vorlagen suchen	Steuert, ob Cookiecutter automatisch online nach Updates für die installierten Vorlagen sucht.
URL des empfohlenen Feeds	Der Speicherort der empfohlenen Vorlagen-Feed-Datei. Der Speicherort kann eine URL oder ein Pfad zu einer lokalen Datei sein. Lassen Sie die URL leer, um den standardmäßigen, von Microsoft kuratierten Feed zu verwenden. Der Feed bietet eine einfache, durch Zeilenumbrüche getrennte Liste mit Vorlagenspeicherorten. Um Änderungen am kuratierten Feed anzufordern, führen Sie eine Pullanforderung in der Quelle in GitHub aus.
Anzeigen von Hilfe	Steuert die Sichtbarkeit der Hilfeinformationsleiste am oberen Rand des Cookiecutter-Fensters.

Optimieren von Cookiecutter-Vorlagen für Visual Studio

Die Cookiecutter-Erweiterung für Visual Studio unterstützt Vorlagen, die für Cookiecutter v1.4 erstellt wurden. Weitere Informationen zur Erstellung von Cookiecutter-Vorlagen finden Sie in der Cookiecutter-Dokumentation.

Die standardmäßige Umsetzung von Vorlagenvariablen hängt vom Datentyp ab (Zeichenfolge oder Liste):

• String: Der Datentyp String verwendet eine Beschriftung für den Variablennamen, ein Textfeld für die Eingabe des Wertes und ein Wasserzeichen, das den Standardwert anzeigt. Ein Tooltip auf dem Textfeld zeigt den Standardwert an.
• Liste: Der Datentyp „List“ verwendet eine Beschriftung für den Variablennamen und ein Kombinationsfeld für die Auswahl eines Wertes. Ein Tooltip auf dem Kombinationsfeld zeigt den Standardwert an.

Sie können das Rendering verbessern, indem Sie andere Metadaten in Ihrer cookiecutter.json-Datei angeben, die spezifisch für Visual Studio sind (und vom Cookiecutter CLI ignoriert werden). Alle Eigenschaften sind optional:

Eigenschaft	Beschreibung
label	Gibt den Text an, der oberhalb des Editors für die Variable angezeigt werden soll, anstelle des Namens der Variable.
description	Legt den Tooltip fest, der auf dem Bearbeitungssteuerelement anstelle des Standardwerts für diese Variable angezeigt wird.
url	Verwandelt die Beschriftung in einen Hyperlink mit einem Tooltip, der die URL anzeigt. Durch Auswählen des Hyperlinks wird diese URL im Standardbrowser des Benutzers geöffnet.
selector	Ermöglicht die Anpassung des Editors für eine Variable. Die folgenden Auswahlen werden derzeit unterstützt: - string: Standardtextfeld, standardmäßig für Zeichenfolgen. - list: Standardkombinationsfeld, standardmäßig für Listen. - yesno: Kombinationsfeld zur Auswahl zwischen y und n, für Zeichenfolgen. - odbcConnection: Textfeld mit einer Ellipsen-Schaltfläche (...), die einen Datenbankverbindungsdialog öffnet.

Das folgende Beispiel zeigt, wie Sie Rendering-Eigenschaften festlegen:

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

Ausführen von Visual Studio-Tasks

Cookiecutter hat eine Funktion namens Post-Generate Hooks, mit der Sie beliebigen Python-Code ausführen können, nachdem die Dateien generiert wurden. Diese Funktion ist zwar flexibel, ermöglicht aber keinen einfachen Zugriff auf Visual Studio.

Sie können diese Funktion verwenden, um eine Datei im Visual Studio-Editor oder im Webbrowser zu öffnen. Sie können auch die Visual Studio-Benutzeroberfläche auslösen, die den Benutzer auffordert, eine virtuelle Umgebung zu erstellen und Paketanforderungen zu installieren.

Um diese Szenarien zu ermöglichen, sucht Visual Studio nach erweiterten Metadaten in der Datei cookiecutter.json. Es sucht nach den Befehlen, die ausgeführt werden sollen, nachdem der Benutzer die generierten Dateien in Solution Explorer geöffnet hat oder nachdem die Dateien zu einem bestehenden Projekt hinzugefügt wurden. (Auch hier kann der Benutzer die Ausführung der Aufgaben deaktivieren, indem er die Option Run additional tasks on completion deaktiviert.)

Das folgende Beispiel zeigt, wie man erweiterte Metadaten in der Datei cookiecutter.json einstellt:

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

Geben Sie die Befehle namentlich an und verwenden Sie den nicht lokalisierten (englischen) Namen, um mit lokalisierten Installationen von Visual Studio zu arbeiten. Sie können Befehlsnamen im Visual Studio-Befehlsfenster testen und ermitteln.

Wenn Sie ein einzelnes Argument übergeben möchten, geben Sie das Argument als Zeichenkette an, wie im vorherigen Beispiel für die Metadaten name gezeigt.

Wenn Sie kein Argument übergeben müssen, lassen Sie den Wert als leere Zeichenfolge stehen oder lassen Sie ihn in der JSON-Datei weg:

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

Für mehrere Argumente ist ein Array zu verwenden. Bei Schaltern teilen Sie den Schalter und seinen Wert in separate Argumente auf und verwenden Sie korrekte Anführungszeichen, wie in diesem Beispiel gezeigt:

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

Argumente können auf andere Cookiecutter-Variablen verweisen. Im vorherigen Beispiel wird die interne Variable _output_folder_path verwendet, um einen absoluten Pfad zum Generieren von Dateien zu bilden.

Der Befehl Python.InstallProjectRequirements funktioniert nur beim Hinzufügen von Dateien zu einem bestehenden Projekt. Diese Einschränkung besteht, weil der Befehl vom Python-Projekt im Projektmappen-Explorer verarbeitet wird und kein Projekt zum Empfangen der Meldung vorhanden ist, wenn Sie sich in der Ordneransicht - des Projektmappen-Explorers befinden.

Behebung von Problemen mit Vorlagen

In den folgenden Abschnitten finden Sie Tipps zur Fehlerbehebung in Ihrer Python-Umgebung und Ihrem Code, wenn Sie mit Cookiecutter arbeiten.

Fehler beim Laden der Vorlage

Einige Vorlagen verwenden möglicherweise ungültige Datentypen in ihrer cookiecutter.json Datei, wie z. B. boolean. Sie können diese Fälle an den Autor der Vorlage melden, indem Sie den Link Issues im Informationsbereich der Vorlage auswählen.

Fehler beim Hookskript

Einige Vorlagen verwenden möglicherweise Post-Generierungs-Skripte, die nicht mit der Cookiecutter-Benutzeroberfläche kompatibel sind. So können beispielsweise Skripts, die den Benutzer um Eingaben bitten, fehlschlagen, weil keine Terminalkonsole vorhanden ist.

Keine Unterstützung für Hookskript unter Windows

Wenn die Post-Skript-Datei .sh lautet, ist sie möglicherweise nicht mit einer Anwendung auf Ihrem Windows-Computer verbunden. Möglicherweise wird ein Windows-Dialogfeld mit der Aufforderung angezeigt, eine kompatible Anwendung im Windows-Store zu suchen.

Vorlagen mit bekannten Fehlern

Sie können herausfinden, ob eine Vorlage bekannte Probleme aufweist, indem Sie den Link Issues in der Vorlagenübersicht in Cookiecutter Explorer verwenden:

Der Link öffnet die GitHub-Themenseite für die Vorlage:

Zugehöriger Inhalt

• Python item templates reference (Referenz für Python-Elementvorlagen)
• Cookiecutter: Bessere Projektvorlagen