Uso de la extensión Cookiecutter
Cookiecutter proporciona una interfaz gráfica de usuario para descubrir plantillas, opciones de plantilla de entrada y crear proyectos y archivos. Visual Studio 2017 y versiones posteriores incluyen 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>Cookiecutter Explorer:
Requisitos previos
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 no se dispone de un intérprete de Python adecuado, Visual Studio mostrará una advertencia.
Si instala un intérprete de Python mientras se está ejecutando Visual Studio, seleccione la opción Inicio en la barra de herramientas de 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.
Trabajar con 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 Cookiecutter Explorer, seleccione la opción Inicio en la barra de herramientas para ver las plantillas disponibles.
La página de inicio muestra una lista de plantillas para elegir, organizada en cuatro posibles grupos:
Agrupar 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 mantiene la fuente predeterminada. Para personalizar la fuente, siga los pasos descritos en Establecer opciones de Cookiecutter. GitHub Resultados de búsqueda de GitHub de 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. Personalizada Cualquier plantilla personalizada definida a través de Cookiecutter Explorer. Cuando se introduce una ubicación de plantilla personalizada en el cuadro de búsqueda de Cookiecutter Explorer, la ubicación aparece en este grupo. Para definir una plantilla personalizada, escriba la ruta completa al repositorio de Git o la ruta 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 situada 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 de 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 de la plantilla, ver la plantilla Wiki o buscar 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 elimina automáticamente y se instala y clona 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 de Cookiecutter Explorer y, a continuación, selecciona la plantilla, la plantilla seleccionada se clona e instala en el equipo local. - Ruta de acceso de carpeta: si escribe una ruta de acceso de carpeta personalizada en el cuadro de búsqueda y selecciona la plantilla, Visual Studio carga esa plantilla sin clonar. |
Importante
Las plantillas de Cookiecutter se clonan en una sola carpeta ~/.cookiecutters. Cada subcarpeta se nombra después del nombre del repositorio Git, que no incluye el nombre de usuario de GitHub. Pueden surgir conflictos si clona distintas plantillas con el mismo nombre que proceden de diferentes autores. En este caso, Cookiecutter le impide sobrescribir la plantilla existente con una plantilla diferente del mismo nombre. Para instalar la otra plantilla, primero debe eliminar la existente.
Establecimiento de opciones de plantilla
Después de instalar y clonar una plantilla localmente, Cookiecutter muestra la página Opciones. En esta página, puede especificar la configuración, como la ubicación de la ruta de acceso de 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, normalmente cuando es 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 ubicación de la ruta de acceso de la carpeta para los archivos generados por Cookiecutter.
A continuación, establezca otras opciones que desee para la plantilla, como:
- full_name: nombre completo que se va a aplicar a la plantilla.
- email: dirección de correo electrónico del autor de la plantilla.
- github_username: alias de GitHub del autor de la plantilla.
- python_version: versión de Python de destino para las aplicaciones web creadas a partir de la plantilla.
Establecer los 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 en la documentación de Cookiecutter.
No participar en las tareas especificadas
Algunas plantillas identifican tareas específicas de Visual Studio que deben ejecutarse tras la generación del 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 terminar se agrega a la lista de opciones. Puede configurar esta opción para no participar en las tareas de Visual Studio especificadas.
Crear 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 la salida de la plantilla y no le importa sobrescribir los archivos, seleccione Aceptar para pasar por alto la advertencia.
En caso contrario, seleccione Cancelar, especifique una carpeta vacía y luego copie manualmente los archivos creados en la carpeta de salida que no está vacía.
Una vez que Cookiecutter crea correctamente los archivos, Visual Studio abre los archivos de proyecto de plantilla en el Explorador de soluciones.
Establecer 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) | La 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 de Cookiecutter. |
Optimización de plantillas de Cookiecutter para Visual Studio
La extensión Cookiecutter para Visual Studio admite plantillas creadas por 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):
- Cadena: el tipo de datos Cadena utiliza una etiqueta para el nombre de la variable, un cuadro de texto para introducir el valor y una marca de agua que muestra el valor predeterminado. Una información sobre herramientas en el cuadro de texto muestra el valor predeterminado.
- Lista: el tipo de datos Lista usa una etiqueta para el nombre de la variable y un cuadro combinado para seleccionar un valor. Una información sobre herramientas en el cuadro combinado muestra el valor predeterminado.
Es posible mejorar la representación mediante la especificación de metadatos adicionales en el archivo cookiecutter.json que es específico de Visual Studio (y la CLI de Cookiecutter lo omite). Todas las propiedades son opcionales:
| Property | Descripción |
|---|---|
label |
Especifica el texto que aparece encima del editor para la variable, en lugar del nombre de la variable. |
description |
Especifica la información sobre herramientas que se muestra en el control de edición, en lugar del valor predeterminado de esa variable. |
url |
Transforma la etiqueta en un hipervínculo, con una información sobre herramientas que muestra la URL. Al seleccionar el hipervínculo se abrirá el explorador predeterminado del usuario con esa dirección URL. |
selector |
Permite la personalización del editor de una variable. Actualmente se admiten los siguientes selectores: - string: cuadro de texto estándar, de forma predeterminada para las cadenas. - list: cuadro combinado estándar, de forma predeterminada para las listas. - yesno: cuadro combinado 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 las 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 presenta una característica llamada Post-Generate Hooks (Enlaces posteriores a la generación) que le permiten ejecutar código de Python arbitrario después de que se generan los archivos. Aunque la característica es flexible, no permite un acceso fácil 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 el Explorador de soluciones o después de agregar los archivos a un proyecto existente. (Nuevamente, el usuario puede optar por ejecutar las tareas si desactiva la opción de plantilla Ejecutar tareas adicionales al terminar).
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 traducido (en inglés) para que funcione en las instalaciones traducidas de Visual Studio. Puede probar y detectar nombres de comando en la ventana de comandos de Visual Studio.
Si desea pasar un solo argumento, especifique el argumento como una cadena, como se muestra para los metadatos name en el ejemplo anterior.
Si no necesita pasar un argumento, deje el valor como una cadena vacía u omítalo del archivo JSON:
"_visual_studio_post_cmds": [
{
"name": "View.WebBrowser"
}
]
Use una matriz para varios argumentos. Para los modificadores, divida el modificador y su valor en argumentos distintos y use el entrecomillado correcto, tal y 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 interna _output_folder_path 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 comando se procesa mediante el proyecto de Python en el Explorador de soluciones, y no hay ningún proyecto para recibir el mensaje mientras se 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
Puede que algunas plantillas usen tipos de datos no válidos, como booleanos, en el archivo cookiecutter.json. Para informar sobre estas instancias al autor de la plantilla, haga clic en el vínculo Problemas del panel de información de la 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, se producirá un error en los scripts que consultan la entrada del usuario por no tener una consola de terminal.
Script de enlace no admitido en Windows
Si el archivo de script posterior es .sh, puede que no esté asociado a una aplicación del equipo Windows. Es posible que vea un diálogo de Windows que le pide que busque una aplicación compatible en la Tienda Windows.
Plantillas con problemas conocidos
Puede averiguar si una plantilla tiene problemas conocidos mediante el vínculo Problemas del resumen de la plantilla en el Explorador de Cookiecutter:
El vínculo abre la página de problemas de GitHub para la plantilla:
