Utilize a extensão Cookiecutter

Cookiecutter fornece uma interface gráfica do usuário para descobrir modelos, opções de modelo de entrada e criar projetos e arquivos. O Visual Studio 2017 e posterior inclui a extensão Cookiecutter. Ele pode ser instalado separadamente em versões anteriores do Visual Studio.

No Visual Studio, a extensão Cookiecutter está disponível em Ver>Cookiecutter Explorer:

Pré-requisitos

• Visual Studio. Para instalar o produto, siga as etapas em Instalar o Visual Studio.

• Python 3.3 ou posterior (32 bits ou 64 bits) ou Anaconda 3 4.2 ou posterior (32 bits ou 64 bits).

  • Se um interpretador Python adequado não estiver disponível, o Visual Studio exibirá um aviso.

  • Se você instalar um interpretador Python enquanto o Visual Studio estiver em execução, selecione a opção Home na barra de ferramentas Cookiecutter Explorer para detetar o interpretador recém-instalado. Para obter mais informações, consulte Criar e gerenciar ambientes Python no Visual Studio.

Trabalhar com o Cookiecutter Explorer

No Cookiecutter Explorer, você pode procurar e selecionar modelos, clonar modelos para seu computador local, definir opções de modelo e criar código a partir de modelos.

Procurar modelos

Você pode procurar modelos no Cookiecutter Explorer para ver o que já está instalado e o que está disponível.

1. No Cookiecutter Explorer, selecione a opção Home da barra de ferramentas para visualizar os modelos disponíveis.

   

   A página inicial exibe uma lista de modelos para escolher, organizados em quatro grupos possíveis:

   Grupo	Descrição	Observações
   Instalado	Modelos instalados no computador local. Quando um modelo online é usado, seu repositório é automaticamente clonado para uma subpasta de ~/.cookiecutters.	Você pode remover um modelo instalado do seu sistema selecionando Eliminar na barra de ferramentas Cookiecutter Explorer.
   Recomendado	Modelos carregados a partir do feed recomendado. A Microsoft faz a curadoria do feed padrão.	Você pode personalizar o feed seguindo as etapas em Definir opções do Cookiecutter.
   GitHub	Resultados de pesquisa do GitHub para a palavra-chave "cookiecutter". A lista de repositórios git é retornada em forma paginada.	Quando a lista de resultados exceder a exibição atual, você poderá selecionar a opção Carregar mais para mostrar o próximo conjunto de resultados paginados na lista.
   personalizados	Quaisquer modelos personalizados definidos através Cookiecutter Explorer. Quando um local de modelo personalizado é inserido na caixa de pesquisa Cookiecutter Explorer, o local aparece nesse grupo.	Você pode definir um modelo personalizado inserindo o caminho completo para o repositório git ou o caminho completo para uma pasta no disco local.

2. Para mostrar ou ocultar a lista de modelos disponíveis para uma categoria específica, selecione a seta ao lado da categoria.

Modelos de clonagem

Você pode trabalhar com modelos disponíveis no Cookiecutter Explorer para fazer cópias locais para trabalhar.

1. No Cookiecutter Explorer, selecione um modelo. As informações sobre o modelo selecionado são exibidas na parte inferior da página inicial do Cookiecutter Explorer.

   

   O resumo do modelo inclui links para obter mais informações sobre o modelo. Você pode ir para a página do repositório do GitHub para o modelo, visualizar o modelo Wiki ou encontrar problemas de relatados.

2. Para clonar o modelo selecionado, selecione Avançar. Cookiecutter faz uma cópia local do modelo.

O comportamento de clonagem depende do tipo de modelo selecionado:

Definir opções de modelo

Depois de instalar e clonar um modelo localmente, o Cookiecutter exibe a página Opções. Nesta página, você pode especificar configurações, como o local do caminho da pasta para os arquivos gerados:

Cada modelo Cookiecutter define seu próprio conjunto de opções. Quando um valor padrão está disponível para uma configuração, a página Opções mostra o texto sugerido no campo correspondente. Um valor padrão pode ser um trecho de código, geralmente quando é um valor dinâmico que usa outras opções.

Neste exemplo, o nome do modelo foi definido como cookiecutter-flask/cookiecutter-flask. Quando um valor de configuração pode ser alterado, o texto do campo fica disponível para edição.

1. No campo Criar para, insira o caminho da pasta para quaisquer arquivos gerados pelo Cookiecutter.

2. Em seguida, defina outras opções desejadas para o modelo, como:

   • full_name: O nome completo a ser aplicado ao modelo.
   • endereço de e-mail: O endereço de e-mail do autor do template.
   • github_username: O alias do GitHub do autor do modelo.
   • python_version: A versão Python de destino para aplicativos web criados a partir do modelo.

Definir padrões com um arquivo de configuração

Você pode personalizar valores padrão para opções específicas com um arquivo de configuração do usuário. Quando a extensão Cookiecutter deteta um arquivo de configuração do usuário, ela substitui os valores padrão do modelo pelos valores do arquivo de configuração. Para obter mais informações sobre esse comportamento, consulte a seção User Config da documentação do Cookiecutter.

Desativar tarefas especificadas

Alguns modelos identificam tarefas específicas do Visual Studio a serem executadas após a geração de código. As tarefas comuns incluem abrir um navegador da Web, abrir arquivos no editor e instalar dependências. Quando um modelo identifica tarefas específicas, a configuração Executar tarefas adicionais ao concluir é adicionada à lista de opções. Você pode definir essa configuração para desativar as tarefas especificadas do Visual Studio.

Criar código a partir de modelos

Depois de definir as opções de modelo, você estará pronto para o Cookiecutter criar os arquivos de projeto e gerar o código.

A caixa de diálogo exibe um botão após a lista de opções. O texto do botão depende do modelo. Poderá ver Criar e Abrir pasta, Adicionar à Soluçãoe assim por diante.

1. Na página Opções, selecione o botão que segue a lista de opções, como Criar e Abrir pasta ou Adicionar à Solução.

   

   Cookiecutter gera o código. Se a pasta de saída não estiver vazia, será exibido um aviso.

   • Se estiveres familiarizado com a saída do modelo e não te importares em substituir ficheiros, seleciona OK para ignorar o aviso.

   • Caso contrário, selecione Cancelar, especifique uma pasta vazia e copie manualmente os arquivos criados para a pasta de saída não vazia.

2. Depois que o Cookiecutter cria os arquivos com êxito, o Visual Studio abre os arquivos de projeto de modelo no Gerenciador de Soluções .

Definir opções de Cookiecutter

As opções do Cookiecutter estão disponíveis através do Tools>Options>Cookiecutter:

Otimizar modelos de Cookiecutter para Visual Studio

A extensão Cookiecutter para Visual Studio suporta modelos criados para Cookiecutter v1.4. Para obter mais informações sobre como criar modelos de Cookiecutter, consulte a documentação do Cookiecutter.

A renderização padrão de variáveis de modelo depende do tipo de dados (cadeia de caracteres ou lista):

• String: O tipo de dados String usa um rótulo para o nome da variável, uma caixa de texto para inserir o valor e uma marca d'água que mostra o valor padrão. Uma dica de ferramenta na caixa de texto mostra o valor padrão.
• Lista: O tipo de dados Lista utiliza um rótulo para o nome da variável e uma caixa de combinação para selecionar um valor. Uma dica de ferramenta na caixa de combinação mostra o valor padrão.

Você pode melhorar a renderização especificando outros metadados em seu arquivo de cookiecutter.json que são específicos do Visual Studio (e ignorados pela CLI do Cookiecutter). Todas as propriedades são opcionais:

O exemplo a seguir mostra como definir propriedades de renderização:

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

Executar tarefas do Visual Studio

Cookiecutter tem um recurso chamado Post-Generate Hooks que permite executar código Python arbitrário depois que os arquivos são gerados. Embora o recurso seja flexível, ele não permite acesso fácil ao Visual Studio.

Você pode usar esse recurso para abrir um arquivo no editor do Visual Studio ou em seu navegador da Web. Você também pode acionar a interface do usuário do Visual Studio que solicita que o usuário crie um ambiente virtual e instale os requisitos do pacote.

Para permitir esses cenários, o Visual Studio procura metadados estendidos no arquivo cookiecutter.json. Ele procura os comandos a serem executados depois que o usuário abre os arquivos gerados no Gerenciador de Soluções ou depois que os arquivos são adicionados a um projeto existente. (Novamente, o utilizador pode optar por não executar as tarefas desmarcando a opção Executar tarefas adicionais ao concluir no modelo.)

O exemplo a seguir mostra como definir metadados estendidos no arquivo cookiecutter.json:

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

Especifique os comandos por nome e use o nome não localizado (inglês) para trabalhar em instalações localizadas do Visual Studio. Você pode testar e descobrir nomes de comando na janela Visual Studio Command.

Se você quiser passar um único argumento, especifique o argumento como uma cadeia de caracteres, conforme mostrado para os metadados name no exemplo anterior.

Se você não precisar passar um argumento, deixe o valor como uma cadeia de caracteres vazia ou omita-o do arquivo JSON:

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

Para vários argumentos, use uma matriz. Para interruptores, divida o interruptor e o seu valor em argumentos separados e utilize cotações adequadas, como mostrado neste exemplo:

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

Os argumentos podem referir-se a outras variáveis do Cookiecutter. No exemplo anterior, a variável _output_folder_path interna é usada para formar um caminho absoluto para gerar arquivos.

O comando Python.InstallProjectRequirements funciona somente ao adicionar arquivos a um projeto existente. Essa limitação existe porque o comando é processado pelo projeto Python no Gerenciador de Soluções e não há nenhum projeto para receber a mensagem enquanto estiver no Gerenciador de Soluções - Exibição de Pasta.

Solucionar problemas de modelo

Analise as seções a seguir para obter dicas sobre como solucionar problemas de seu ambiente Python e código ao trabalhar com o Cookiecutter.

Erro ao carregar modelo

Alguns modelos podem usar tipos de dados inválidos em seus arquivos cookiecutter.json, como booleano. Você pode relatar essas instâncias ao autor do modelo selecionando o link Problemas no painel de informações do modelo.

Falha no script de gancho

Alguns modelos podem usar scripts de pós-geração que não são compatíveis com a interface do usuário do Cookiecutter. Por exemplo, os scripts que consultam o usuário para entrada podem falhar devido à falta de um console de terminal.

Script de hook não suportado no Windows

Se o arquivo de script de postagem estiver .sh, ele pode não estar associado a um aplicativo no seu computador Windows. Poderá ver uma mensagem de diálogo do Windows para encontrar uma aplicação compatível na loja do Windows.

Modelos com problemas conhecidos

Você pode descobrir se um modelo tem problemas conhecidos usando o link Problemas no resumo do modelo em Cookiecutter Explorer:

O link abre a página de problemas do GitHub para o modelo:

Conteúdo relacionado

• Referência de modelos de item Python
• Cookiecutter: Melhores modelos de projeto