Cookiecutter 확장 사용Using the Cookiecutter extension

Cookiecutter는 템플릿을 검색하고, 템플릿 옵션을 입력하며, 프로젝트와 파일을 만들 수 있는 그래픽 사용자 인터페이스를 제공합니다.Cookiecutter provides a graphical user interface to discover templates, input template options, and create projects and files. Visual Studio 2017에 포함되어 있으며, 이전 버전의 Visual Studio에서는 개별적으로 설치할 수 있습니다.It's included with Visual Studio 2017 and can be installed separately in earlier versions of Visual Studio.

Cookiecutter에는 Python 3.3 이상(32비트 또는 64비트) 또는 Anaconda 3 4.2 이상(32비트 또는 64비트)이 필요합니다.Cookiecutter requires Python 3.3 or later (32-bit or 64-bit) or Anaconda 3 4.2 or later (32-bit or 64-bit). 적합한 Python 인터프리터를 사용할 수 없는 경우 Visual Studio에서 경고가 표시됩니다.If a suitable Python interpreter isn't available, Visual Studio displays a warning. Visual Studio를 실행하는 중에 Python 인터프리터를 설치하는 경우 Cookiecutter 도구 모음에서 [홈] 단추를 클릭하여 새로 설치된 인터프리터를 검색합니다.If you install a Python interpreter while Visual Studio is running, click the Home button on the Cookiecutter toolbar to detect the newly installed interpreter. (일반적으로 환경에 대한 자세한 내용은 Python 환경을 참조하세요.)(See Python environments for more about environments in general.)

설치되면 보기 > Cookiecutter 탐색기를 선택하여 다음 창을 엽니다.Once installed, select View > Cookiecutter Explorer to open its window:

Cookiecutter 주 창

Cookiecutter 워크플로Cookiecutter workflow

Cookiecutter 작업은 다음 섹션에서 설명한 대로 템플릿을 검색하여 선택하고, 로컬 컴퓨터에 복제하고, 옵션을 설정한 다음 해당 템플릿에서 코드를 만드는 프로세스입니다.Working with Cookiecutter is a process of browsing and selecting a template, cloning it to your local machine, setting options, then creating code from that template, as described in the sections that follow.

템플릿 찾아보기Browsing templates

Cookiecutter 홈페이지에는 선택하여 다음과 같은 그룹으로 구성할 수 있는 템플릿 목록이 표시됩니다.The Cookiecutter home page displays a list of templates to choose from, organized into the following groups:

그룹화Group 설명Description
설치됨Installed 로컬 컴퓨터에 설치된 템플릿입니다.Templates that have been installed to your local machine. 온라인 템플릿을 사용하면 리포지토리가 ~/.cookiecutters의 하위 폴더에 자동으로 복제됩니다.When an online template is used, its repository is automatically cloned to a subfolder of ~/.cookiecutters. Del 키를 눌러 선택한 설치된 템플릿을 삭제할 수 있습니다.You can delete a selected installed template by pressing Del.
권장Recommended 권장 피드에서 로드된 템플릿입니다.Templates loaded from the recommended feed. 기본 피드는 Microsoft에서 큐레이트합니다.The default feed is curated by Microsoft. 피드 사용자 지정에 대한 자세한 내용은 Cookiecutter 옵션을 참조하세요.See Cookiecutter options below for details on customizing the feed.
GitHubGitHub cookiecutter 키워드에 대한 GitHub 검색 결과입니다.GitHub search results for the cookiecutter keyword. GitHub의 결과는 페이지가 매겨져 다시 표시됩니다. 더 많은 결과를 사용할 수 있는 경우 목록 끝에 추가 로드가 표시되어 있습니다.Results from GitHub come back paginated, if more results are available, Load More appears at the end of the list.
사용자 지정Custom 검색 창에 사용자 지정 검색 위치를 입력하면 이 그룹에 표시됩니다.When a custom location is entered in the search box, it appears in this group. GitHub 리포지토리의 전체 경로 또는 로컬 디스크의 폴더에 대한 전체 경로를 입력할 수 있습니다.You can either type in a full path to the GitHub repository, or the full path to a folder on your local disk.

복제 비교Cloning

템플릿을 선택한 후 다음을 선택하면 Cookiecutter에서 작업할 로컬 복사본을 만듭니다.When you select a template followed by Next, Cookiecutter makes a local copy to work from.

권장 또는 GitHub 그룹에서 템플릿을 선택하거나 검색 상자에 사용자 지정 URL을 입력하고 템플릿을 선택하면 해당 템플릿이 복제되어 로컬 컴퓨터에 설치됩니다.If you select a template from the Recommended or GitHub groups, or enter a custom URL into the search box and select that template, it's cloned and installed on your local machine. 해당 템플릿이 Visual Studio의 이전 세션에 설치되는 경우 이전 버전이 자동으로 삭제되고 최신 버전이 복제됩니다.If that template was installed in a previous session of Visual Studio, it's automatically deleted and the latest version is cloned.

설치됨 그룹에서 템플릿을 선택하거나 검색 상자에 사용자 지정 폴더 경로를 입력하고 템플릿을 선택하면 Visual Studio에서 해당 템플릿을 복제하지 않고 로드합니다.If you select a template from the Installed group, or enter a custom folder path into the search box and select that template, Visual Studio loads that template without cloning.

중요

Cookiecutter 템플릿은 ~/.cookiecutters 단일 폴더 아래에 복제됩니다.Cookiecutter templates are cloned under a single folder ~/.cookiecutters. 각 하위 폴더의 이름은 GitHub 사용자 이름을 포함하지 않은 Git 리포지토리 이름 뒤에 지정됩니다.Each subfolder is named after the git repository name, which does not include the GitHub user name. 여러 작성자의 이름이 동일한 템플릿을 여러 개 복제하면 충돌이 발생할 수 있습니다.Conflicts can arise if you clone different templates with the same name that come from different authors. 이 경우 Cookiecutter는 기존 템플릿을 동일한 이름의 다른 템플릿으로 덮어쓰지 못하게 합니다.In this case, Cookiecutter prevents you from overwriting the existing template with a different template of the same name. 다른 템플릿을 설치하려면 먼저 기존 템플릿을 삭제해야 합니다.To install the other template, you must first delete the existing one.

템플릿 옵션 설정Setting template options

템플릿을 로컬로 설치하면 Cookiecutter에서 옵션 페이지를 표시합니다. 이 페이지에서 Cookiecutter를 통해 다른 옵션과 함께 파일을 생성하려는 위치를 지정할 수 있습니다.After the template is installed locally, Cookiecutter displays an options page where you can specify where you want Cookiecutter to generate files along with other options:

Cookiecutter 옵션 페이지

각 Cookiecutter 템플릿마다 고유한 옵션 집합을 정의하고 각 옵션에 대해 기본값(각 입력 필드에 제안된 텍스트로 표시됨)을 지정합니다.Each Cookiecutter template defines its own set of options, and specifies a default value for each one (displayed as the suggested text in each entry field). 기본값은 종종 다른 옵션을 사용하는 동적 값인 경우 코드 조각일 수 있습니다.A default value may be a code snippet, often when it's a dynamic value that uses other options.

사용자 구성 파일을 사용하여 특정 옵션에 대한 기본값을 사용자 지정할 수 있습니다.It's possible to customize default values for specific options with a user configuration file. Cookiecutter 확장에서 사용자 구성 파일을 감지하면 템플릿의 기본값을 사용자 구성 파일의 기본값으로 덮어씁니다.When the Cookiecutter extension detects a user configuration file, it overwrites the template's default values with the user config's default values. 이 동작에 대해서는 Cookiecutter 설명서의 User Config(사용자 구성) 섹션에서 설명합니다.This behavior is discussed in the User Config section of the Cookiecutter documentation.

템플릿에서 코드 생성 후 실행할 특정 Visual Studio 작업을 지정하면 이러한 작업을 건너뛰도록 선택할 수 있는 완성 시 추가 작업 실행 추가 옵션이 표시됩니다.If the template specifies specific Visual Studio tasks to run after code generation, an additional Run additional tasks on completion option appears that allows you to opt out of those tasks. 가장 일반적으로 사용되는 작업은 웹 브라우저를 열고, 편집기에서 파일을 열고, 종속성을 설치하는 등입니다.The most common use of tasks is to open a web browser, open files in the editor, install dependencies, and so on.

만들기Create

옵션을 설정했으면 만들기를 선택하여 코드를 생성합니다(출력 폴더가 비어 있지 않은 경우 경고가 표시됨).Once you've set your options, select Create to generate code (a warning appears if the output folder isn't empty). 템플릿의 출력에 익숙하고 파일 덮어쓰기에 신경 쓰지 않는다면 경고를 해제할 수 있습니다.If you're familiar with the template's output and don't mind overwriting files, you can dismiss the warning. 그렇지 않으면 취소를 선택하고, 빈 출력 폴더를 지정한 다음, 이 출력 폴더에 만든 파일을 수동으로 복사합니다.Otherwise, select Cancel, specify an empty folder, and then manually copy the created files to your non-empty output folder.

파일이 성공적으로 만들어졌으면 Cookiecutter의 솔루션 탐색기에서 파일을 여는 옵션을 제공합니다.After the files are created successfully, Cookiecutter provides an option to open the files in Solution Explorer:

솔루션 탐색기 명령을 보여 주는 Cookiecutter

Cookiecutter 옵션Cookiecutter options

Cookiecutter 옵션은 도구 > 옵션 > Cookiecutter를 통해 사용할 수 있습니다.Cookiecutter options are available through Tools > Options > Cookiecutter:

Cookiecutter 옵션

옵션Option 설명Description
권장 피드 URLRecommended Feed URL 권장 템플릿 피드의 위치입니다.The location of the recommended templates feed. URL 또는 로컬 파일에 대한 경로일 수 있습니다.It can be a URL or a path to a local file. Microsoft에서 큐레이트하는 기본 피드를 사용하려면 URL을 비워 둡니다.Leave the URL empty to use the default Microsoft curated feed. 피드는 줄 바꿈 문자로 구분된 템플릿 위치의 간단한 목록을 제공합니다.The feed provides a simple list of template locations, separated by newlines. 큐레이트된 피드에 대한 변경을 요청하려면 GitHub 원본에 대한 끌어오기를 요청합니다.To request changes to the curated feed, make a pull request against the source on GitHub.
도움말 표시Show Help Cookiecutter 창 위쪽에 있는 도움말 정보 표시줄의 가시성을 제어합니다.Controls the visibility of the help information bar at the top of the Cookiecutter window.

Visual Studio용 Cookiecutter 템플릿 최적화Optimizing Cookiecutter templates for Visual Studio

Cookiecutter 템플릿 작성의 기본 사항은 Cookiecutter 설명서(영문)를 참조하세요.For the basics of authoring a Cookiecutter template, see the Cookiecutter documentation. Visual Studio용 Cookiecutter 확장은 Cookiecutter v1.4용으로 만들어진 템플릿을 지원합니다.The Cookiecutter extension for Visual Studio supports templates created for Cookiecutter v1.4.

템플릿 변수의 기본 렌더링은 다음과 같이 데이터 형식(문자열 또는 목록)에 따라 달라집니다.The default rendering of template variables depends on the type of data (string or list):

  • 문자열: 변수 이름의 레이블, 값 입력을 위한 텍스트 상자 및 기본값을 보여 주는 워터마크입니다.String: Label for variable name, text box for entering value, and a watermark showing the default value. 텍스트 상자의 도구 설명에는 기본값이 표시됩니다.Tooltip on the text box shows the default value.
  • 목록: 변수 이름의 레이블 및 값 선택을 위한 콤보 상자입니다.List: Label for variable name, combo box for selecting a value. 콤보 상자의 도구 설명에는 기본값이 표시됩니다.Tooltip on the combo box shows the default value.

Visual Studio와 관련된 cookiecutter.json 파일에 추가 메타데이터를 지정하여 이 렌더링에서 향상할 수 있습니다(Cookiecutter CLI에서는 무시됨).It's possible to improve on this rendering by specifying additional metadata in your cookiecutter.json file that's specific to Visual Studio (and ignored by the Cookiecutter CLI). 모든 속성은 선택적입니다.All properties are optional:

속성Property 설명Description
레이블Label 변수 이름 대신 변수의 편집기 위에 표시되는 항목을 지정합니다.Specifies what appears above the editor for the variable, instead of the name of the variable.
설명Description 해당 변수의 기본값 대신 편집 컨트롤에 표시되는 도구 설명을 지정합니다.Specifies the tooltip that appears on the edit control, instead of the default value for that variable.
URLURL URL을 표시하는 도구 설명을 사용하여 레이블을 하이퍼링크로 변경합니다.Changes the label into a hyperlink, with a tooltip that shows the URL. 하이퍼링크를 클릭하면 사용자의 기본 브라우저를 해당 URL로 엽니다.Clicking on the hyperlink opens the user's default browser to that URL.
선택기Selector 변수에 대한 편집기의 사용자 지정을 허용합니다.Allows customization of the editor for a variable. 현재 지원되는 선택기는 다음과 같습니다.The following selectors are currently supported:
  • string: 문자열에 대한 기본 표준 텍스트 상자입니다.string: Standard text box, default for strings.
  • list: 목록에 대한 기본 표준 콤보 상자입니다.list: Standard combo box, default for lists.
  • yesno: 문자열에 대해 yn 중에서 선택하는 콤보 상자입니다.yesno: Combo box to choose between y and n, for strings.
  • odbcConnection: 데이터베이스 연결 대화 상자를 호출하는 "..." 단추가 있는 텍스트 상자입니다.odbcConnection: Text box with a "..." button that brings up a database connection dialog.

예제:Example:

{
    "site_name": "web-app",
    "python_version": ["3.5.2", "2.7.12"],
    "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 작업 실행Running Visual Studio tasks

Cookiecutter에는 생성 후 후크라는 기능이 있으므로 파일을 생성한 후에 임의의 Python 코드를 실행할 수 있습니다.Cookiecutter has a feature called Post-Generate Hooks that allows for running arbitrary Python code after the files are generated. 이 기능은 유연하지만 Visual Studio에 쉽게 액세스할 수 없습니다.Although flexible, it doesn't allow easy access to Visual Studio.

예를 들어 Visual Studio 편집기 또는 웹 브라우저에서 파일을 열거나, 가상 환경을 만들고 패키지 요구 사항을 설치하도록 사용자에게 요청하는 Visual Studio UI를 트리거할 수 있습니다.For example, you may want to open a file in the Visual Studio editor, or in its web browser, or trigger the Visual Studio UI that prompts the user to create a virtual environment and install package requirements.

이러한 시나리오를 허용하기 위해 Visual Studio에서는 사용자가 [솔루션 탐색기]에서 생성된 파일을 열거나 파일이 기존 프로젝트에 추가된 후에 실행할 명령을 설명하는 확장 메타데이터를 cookiecutter.json에서 찾습니다.To allow these scenarios, Visual Studio looks for extended metadata in cookiecutter.json that describes the commands to run after the user opens the generated files in Solution Explorer or after the files are added to an existing project. (사용자는 다시 한번 템플릿 옵션에서 완성 시 추가 작업 실행을 선택 취소하여 작업 실행을 옵트아웃(opt out)할 수 있습니다.)(Again, the user can opt out of running the tasks by clearing Run additional tasks on completion in the template options.)

예제:Example:

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

명령은 이름으로 지정되므로 지역화되지 않은 이름(영문)을 사용하여 Visual Studio의 지역화된 설치에서 작동해야 합니다.Commands are specified by name, and should use the non-localized (English) name to work on localized installs of Visual Studio. Visual Studio 명령 창에서 명령 이름을 테스트하고 검색할 수 있습니다.You can test and discover command names in the Visual Studio Command Window.

단일 인수를 전달하려면 앞의 예제와 같이 해당 인수를 문자열로 지정합니다.If you want to pass a single argument, specify it as a string like in the previous example.

인수를 전달할 필요가 없으면 빈 문자열로 남겨 두거나 JSON에서 생략합니다.If you don't need to pass an argument, leave it an empty string or omit it from the JSON:

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

여러 인수에 대해서는 배열을 사용합니다.Use an array for multiple arguments. 스위치의 경우 스위치와 해당 값을 별도의 인수로 분할하고 적절한 따옴표로 묶습니다.For switches, split the switch and its value into separate arguments and use proper quoting. 예:For example:

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

인수는 다른 Cookiecutter 변수를 참조할 수 있습니다.Arguments can refer to other Cookiecutter variables. 위의 예제에서 내부 _output_folder_path 변수는 생성된 파일의 절대 경로를 구성하는 데 사용됩니다.In the examples above, the internal _output_folder_path variable is used to form an absolute path to generated files.

Python.InstallProjectRequirements 명령은 기존 프로젝트에 파일을 추가할 때만 작동합니다.Note that the Python.InstallProjectRequirements command works only when adding files to an existing project. 이 제한은 명령이 솔루션 탐색기에서 Python 프로젝트로 처리되고, 솔루션 탐색기 - 폴더 보기에서 메시지를 받을 프로젝트가 없기 때문에 발생합니다.This limitation exists because the command is processed by the Python project in Solution Explorer, and there's no project to receive the message while in Solution Explorer - Folder View. 향후 릴리스에서는 이 제한 사항을 해결하고 전반적으로 더 나은 폴더 보기를 지원하겠습니다.We hope to remove the limitation win a future release (and provide better Folder View support in general).

문제 해결Troubleshooting

템플릿 로드 중 오류Error loading template

일부 템플릿에서 부울과 같은 잘못된 cookiecutter.json 데이터 형식을 사용할 수도 있습니다.Some templates may be using invalid data types, such as boolean, in their cookiecutter.json. 템플릿 정보 창에서 문제 링크를 선택하여 이러한 인스턴스를 템플릿 작성자에게 보고합니다.Report such instances to the template author by selecting the Issues link in the template information pane.

후크 스크립트 실패Hook script failed

일부 템플릿에서 Cookiecutter UI와 호환되지 않는 생성 후 스크립트를 사용할 수도 있습니다.Some templates may use post-generation scripts that are not compatible with the Cookiecutter UI. 예를 들어 터미널 콘솔을 사용하지 않기 때문에 사용자에게 입력을 쿼리하는 스크립트는 실패합니다.For example, scripts that query the user for input fails due to not having a terminal console.

Windows에서 지원하지 않는 후크 스크립트Hook script not supported on Windows

게시 스크립트가 .sh인 경우 Windows 컴퓨터의 응용 프로그램과 연결되지 않을 수도 있습니다.If the post script is .sh, then it may not be associated with an application on your Windows machine. Windows 스토어에서 호환되는 응용 프로그램을 찾도록 요청하는 Windows 대화 상자가 나타날 수 있습니다.You may see a Windows dialog asking you to find a compatible application in the Windows store.

알려진 문제점이 있는 템플릿Templates with known issues

복제 실패:Clone failures:

  • wildfish/cookiecutter-django-crud(하위 폴더 이름에 잘못된 | 문자)wildfish/cookiecutter-django-crud (invalid character | in subfolder name)
  • cookiecutter-pyvanguard(하위 폴더 이름에 잘못된 | 문자)cookiecutter-pyvanguard (invalid character | in subfolder name)

로드 실패:Load failures:

  • chrisdev/wagtail-cookiecutter-foundation(cookiecutter.json에서 부울 형식 사용)chrisdev/wagtail-cookiecutter-foundation (uses a boolean type in cookiecutter.json)
  • quintoandar/cookiecutter-android(템플릿 폴더 없음)quintoandar/cookiecutter-android (no template folder)

실행 실패:Run failures:

  • iknite/cookiecutter-ansible-role(사후 후크 스크립트에 콘솔 입력 필요)iknite/cookiecutter-ansible-role (post hook script requires console input)
  • benregn/cookiecutter-django-ansible(Jinja 오류)benregn/cookiecutter-django-ansible (Jinja error)

bash 사용(치명적이지 않음):Uses bash (not fatal):

  • openstack-dev/cookiecutteropenstack-dev/cookiecutter