Uso de la extensión Cookiecutter
Cookiecutter proporciona una interfaz gráfica de usuario para detectar plantillas, opciones de plantilla de entrada y crear proyectos y archivos. Visual Studio 2017 y versiones posteriores incluye la extensión Cookiecutter. Se puede instalar por separado en versiones anteriores de Visual Studio.
En Visual Studio, la extensión Cookiecutter está disponible en Ver>Explorador de Cookiecutter:
Prerrequisitos
Visual Studio. Para instalar el producto, siga los pasos descritos en Instalación de Visual Studio.
Python 3.3 o posterior (32 o 64 bits) o Anaconda 3 4.2 o posterior (32 o 64 bits).
Si un intérprete de Python adecuado no está disponible, Visual Studio muestra una advertencia.
Si instala un intérprete de Python mientras se ejecuta Visual Studio, seleccione la opción Inicio en la barra de herramientas Cookiecutter Explorer para detectar el intérprete recién instalado. Para obtener más información, consulte Creación y administración de entornos de Python en Visual Studio.
Uso de "Cookiecutter Explorer"
En Cookiecutter Explorer, puede examinar y seleccionar plantillas, clonar plantillas en el equipo local, establecer opciones de plantilla y crear código a partir de plantillas.
Examinar plantillas
Puede examinar plantillas en Cookiecutter Explorer para ver lo que ya está instalado y lo que está disponible.
En Explorador de Cookiecutter, seleccione la opción Inicio en la barra de herramientas para ver las plantillas disponibles.
La página principal muestra una lista de plantillas entre las que elegir, organizadas en cuatro grupos posibles:
Grupo Descripción Notas Instalado Plantillas instaladas en el equipo local. Cuando se usa una plantilla en línea, su repositorio se clona automáticamente en una subcarpeta de ~/.cookiecutters. Para quitar una plantilla instalada del sistema, seleccione Eliminar en la barra de herramientas de Cookiecutter Explorer. Recomendado Plantillas cargadas desde la fuente recomendada. Microsoft administra la fuente predeterminada. Puede personalizar la fuente de datos siguiendo los pasos descritos en Configurar opciones de Cookiecutter. GitHub Resultados de búsqueda de GitHub para la palabra clave "cookiecutter". La lista de repositorios de Git se devuelve en formato paginado. Cuando la lista de resultados supera la vista actual, puede seleccionar la opción Cargar más para mostrar el siguiente conjunto de resultados paginados en la lista. Custom Las plantillas personalizadas definidas a través del Explorador de Cookiecutter. Cuando se escribe una ubicación de plantilla personalizada en el cuadro de búsqueda del Explorador de Cookiecutter, la ubicación aparece en este grupo. Puede definir una plantilla personalizada escribiendo la ruta de acceso completa al repositorio de Git o la ruta de acceso completa a una carpeta del disco local. Para mostrar u ocultar la lista de plantillas disponibles para una categoría específica, seleccione la flecha junto a la categoría.
Clonar plantillas
Puede trabajar con plantillas disponibles en Cookiecutter Explorer para realizar copias locales desde las que trabajar.
En Cookiecutter Explorer, seleccione una plantilla. La información sobre la plantilla seleccionada se muestra en la parte inferior de la página principal Cookiecutter Explorer.
El resumen de la plantilla incluye vínculos para obtener más información sobre la plantilla. Puede ir a la página del repositorio de GitHub para la plantilla, consultar la Wiki de la plantilla , o buscar los problemas notificados.
Para clonar la plantilla seleccionada, seleccione Siguiente. Cookiecutter realiza una copia local de la plantilla.
El comportamiento de clonación depende del tipo de plantilla que seleccione:
| Tipo de plantilla | Comportamiento |
|---|---|
| Instalado | Si la plantilla seleccionada se instaló en una sesión anterior de Visual Studio, se eliminará automáticamente y se instalará y clonará la versión más reciente en el equipo local. |
| Recomendado | La plantilla seleccionada se clona e instala en el equipo local. |
| GitHub | La plantilla seleccionada se clona e instala en el equipo local. |
| búsqueda personalizada | - dirección URL: si escribe una dirección URL personalizada para un repositorio de Git en el cuadro de búsqueda Cookiecutter Explorer y, a continuación, selecciona la plantilla, la plantilla seleccionada se clona e instala en el equipo local. - Ruta de carpeta: Si introduces una ruta de carpeta personalizada en el cuadro de búsqueda y seleccionas la plantilla, Visual Studio carga esa plantilla sin clonar. |
Importante
Las plantillas de Cookiecutter se clonan en una sola carpeta ~/.cookiecutters. Cada subcarpeta se denomina después del nombre del repositorio de Git, que no incluye el nombre de usuario de GitHub. Pueden surgir conflictos si clona plantillas diferentes con el mismo nombre que proceden de diferentes autores. En este caso, Cookiecutter impide que sobrescriba la plantilla existente con una plantilla diferente del mismo nombre. Para instalar la otra plantilla, primero debe eliminar la existente.
Establecer opciones de plantilla
Después de instalar y clonar una plantilla localmente, Cookiecutter muestra la página Opciones. En esta página, puede especificar los ajustes, como la ruta de la carpeta para los archivos generados.
Cada plantilla de Cookiecutter define su propio conjunto de opciones. Cuando hay un valor predeterminado disponible para una configuración, la página Opciones muestra el texto sugerido en el campo correspondiente. Un valor predeterminado puede ser un fragmento de código, a menudo cuando se trata de un valor dinámico que usa otras opciones.
En este ejemplo, el nombre de la plantilla se define como cookiecutter-flask/cookiecutter-flask. Cuando se puede cambiar un valor de configuración, el texto del campo está disponible para su edición.
En el campo Crear en, escriba la ruta de la carpeta para los archivos que haya generado Cookiecutter.
A continuación, establezca otras opciones deseadas para la plantilla, como:
- full_name: nombre completo que se va a aplicar a la plantilla.
- correo electrónico: la dirección de correo electrónico del autor de la plantilla.
- github_username: alias de GitHub del autor de la plantilla.
- python_version: la versión de Python de destino para las aplicaciones web creadas a partir de la plantilla.
Establecimiento de valores predeterminados con un archivo de configuración
Puede personalizar los valores predeterminados para opciones específicas con un archivo de configuración de usuario. Cuando la extensión Cookiecutter detecta un archivo de configuración de usuario, sobrescribe los valores predeterminados de la plantilla con los valores del archivo de configuración. Para obtener más información sobre este comportamiento, consulte la sección Configuración de usuario de la documentación de Cookiecutter.
No participar en las tareas especificadas
Algunas plantillas identifican tareas específicas de Visual Studio para ejecutarse después de la generación de código. Las tareas comunes incluyen abrir un explorador web, abrir archivos en el editor e instalar dependencias. Cuando una plantilla identifica tareas específicas, la opción Ejecutar tareas adicionales al finalizar se agrega a la lista de opciones. Puede configurar esta opción para no participar en las tareas de Visual Studio especificadas.
Creación de código a partir de plantillas
Después de establecer las opciones de plantilla, estará listo para que Cookiecutter cree los archivos del proyecto y genere el código.
El cuadro de diálogo muestra un botón después de la lista de opciones. El texto del botón depende de la plantilla. Es posible que vea Crear y abrir carpeta, Agregar a la solución, etc.
En la página Opciones, seleccione el botón que sigue a la lista de opciones, como Crear y abrir carpeta o Agregar a la solución.
Cookiecutter genera el código. Si la carpeta de salida no está vacía, se muestra una advertencia.
Si está familiarizado con el resultado de la plantilla y no le importa sobrescribir archivos, seleccione Aceptar para descartar la advertencia.
De lo contrario, seleccione Cancelar, especifique una carpeta vacía y, a continuación, copie manualmente los archivos creados en la carpeta de salida no vacía.
Cuando Cookiecutter haya creado correctamente los archivos, Visual Studio abrirá los archivos de proyecto de plantilla en Explorador de soluciones.
Establecer las opciones de Cookiecutter
Las opciones de Cookiecutter están disponibles en Tools>Options>Cookiecutter (Herramientas > Opciones > Cookiecutter):
| Opción | Descripción |
|---|---|
| Buscar plantillas actualizadas | Controla si Cookiecutter comprueba automáticamente si hay actualizaciones en línea de las plantillas instaladas. |
| Recommended Feed URL (URL de fuente recomendada) | Ubicación del archivo de la fuente de plantillas recomendadas. La ubicación puede ser una dirección URL o una ruta de acceso a un archivo local. Deje en blanco la dirección URL para usar la fuente protegida por Microsoft predeterminada. La fuente proporciona una sencilla lista de ubicaciones de plantillas, separadas por nuevas líneas. Para solicitar cambios en la fuente protegida, realice una solicitud de extracción contra el origen de GitHub. |
| Show Help (Mostrar ayuda) | Controla la visibilidad de la barra de información de ayuda en la parte superior de la ventana Cookiecutter. |
Optimización de plantillas de Cookiecutter para Visual Studio
La extensión Cookiecutter para Visual Studio admite plantillas creadas para Cookiecutter v1.4. Para obtener más información sobre la creación de plantillas de Cookiecutter, consulte la documentación de Cookiecutter.
La representación predeterminada de variables de plantilla depende del tipo de datos (cadena o lista):
- string: el tipo de datos String usa una etiqueta para el nombre de la variable, un cuadro de texto para escribir el valor y una marca de agua que muestra el valor predeterminado. Una información en pantalla en el cuadro de texto muestra el valor predeterminado.
- List: el tipo de datos List usa una etiqueta para el nombre de la variable y un cuadro combinado para seleccionar un valor. La información en pantalla en el cuadro combinado muestra el valor predeterminado.
Puede mejorar la representación especificando otros metadatos en su archivo de cookiecutter.json, específicos para Visual Studio (y que son ignorados por la CLI de Cookiecutter). Todas las propiedades son opcionales:
| Propiedad | Descripción |
|---|---|
label |
Especifica el texto que se va a mostrar encima del editor de la variable, en lugar del nombre de la variable. |
description |
Especifica la información sobre herramientas que se va a mostrar en el control de edición, en lugar del valor predeterminado de esa variable. |
url |
Cambia la etiqueta en un hipervínculo con un tooltip que muestra la dirección URL. Al seleccionar el hipervínculo, se abre el explorador predeterminado del usuario en esa dirección URL. |
selector |
Permite la personalización del editor para una variable. Actualmente se admiten los siguientes selectores: - string: cuadro de texto estándar, valor predeterminado para las cadenas. - list: cuadro combinado estándar, predeterminado para listas. - yesno: Cuadro combinado para elegir entre y y n para las cadenas. - odbcConnection: cuadro de texto con un botón de puntos suspensivos (...) que abre un cuadro de diálogo de conexión de base de datos. |
En el ejemplo siguiente se muestra cómo establecer propiedades de representació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"
}
}
}
Ejecución de tareas de Visual Studio
Cookiecutter tiene una característica denominada Post-Generate Hooks que le permite ejecutar código arbitrario de Python después de generar los archivos. Aunque la característica es flexible, no permite el acceso sencillo a Visual Studio.
Puede usar esta característica para abrir un archivo en el editor de Visual Studio o en su explorador web. También puede desencadenar la interfaz de usuario de Visual Studio que solicita al usuario que cree un entorno virtual e instale los requisitos del paquete.
Para permitir estos escenarios, Visual Studio busca metadatos extendidos en el archivo cookiecutter.json. Busca que los comandos se ejecuten después de que el usuario abra los archivos generados en Explorador de soluciones o después de agregar los archivos a un proyecto existente. De nuevo, el usuario puede optar por no ejecutar las tareas desmarcando la opción de la plantilla Ejecutar tareas adicionales al finalizar.
En el ejemplo siguiente se muestra cómo establecer metadatos extendidos en el archivo 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"
}
]
Especifique los comandos por nombre y use el nombre no localizado (inglés) para trabajar en instalaciones localizadas de Visual Studio. Puede probar y detectar nombres de comandos en la ventana Comando de Visual Studio.
Si desea pasar un único argumento, especifique el argumento como una cadena como se muestra para los metadatos de name en el ejemplo anterior.
Si no necesita pasar un argumento, deje el valor como una cadena vacía o omita el valor del archivo JSON:
"_visual_studio_post_cmds": [
{
"name": "View.WebBrowser"
}
]
Para varios argumentos, use una matriz. En el caso de los modificadores, divida el modificador y su valor en argumentos independientes y use comillas adecuadas, como se muestra en este ejemplo:
"_visual_studio_post_cmds": [
{
"name": "File.OpenFile",
"args": [
"{{cookiecutter._output_folder_path}}\\read me.txt",
"/e:",
"Source Code (text) Editor"
]
}
]
Los argumentos pueden hacer referencia a otros variables de Cookiecutter. En el ejemplo anterior, la variable _output_folder_path interna se usa para formar una ruta de acceso absoluta para generar archivos.
El comando Python.InstallProjectRequirements solo funciona al agregar archivos a un proyecto existente. Esta limitación existe porque el proyecto de Python procesa el comando en Explorador de solucionesy no hay ningún proyecto para recibir el mensaje mientras está en Explorador de soluciones - Vista de carpetas.
Solución de problemas de plantilla
Revise las secciones siguientes para obtener sugerencias sobre cómo solucionar problemas del entorno y el código de Python al trabajar con Cookiecutter.
Error al cargar la plantilla
Algunas plantillas pueden usar tipos de datos no válidos en su archivo de cookiecutter.json, como booleano. Puede notificar estas instancias al autor de la plantilla seleccionando el vínculo Problemas en el panel de información de plantilla.
Error de script de enlace
Algunas plantillas pueden usar scripts posteriores a la generación que no son compatibles con la interfaz de usuario de Cookiecutter. Por ejemplo, los scripts que consultan al usuario para la entrada pueden producir errores debido a la falta de una consola de terminal.
Script de enlace no admitido en Windows
Si el archivo de script posterior es .sh, es posible que no esté asociado a una aplicación en el equipo Windows. Es posible que vea un cuadro de diálogo de Windows para buscar una aplicación compatible en Microsoft Store.
Plantillas con problemas conocidos
Puede averiguar si una plantilla tiene problemas conocidos mediante el vínculo Problemas en el resumen de la plantilla en Cookiecutter Explorer:
El vínculo abre la página problemas de GitHub para la plantilla:
