다음을 통해 공유

자습서: 항목 템플릿 만들기

  • 아티클

.NET을 사용하면 프로젝트, 파일 및 리소스를 만드는 템플릿을 만들고 배포할 수 있습니다. 이 자습서는 dotnet new 명령에 사용할 템플릿을 만들고 설치하고 제거하는 방법을 알려주는 시리즈의 1부입니다.

.NET 샘플 GitHub 리포지토리에서 완료된 템플릿을 볼 수 있습니다.

팁

항목 템플릿은 Visual Studio의 추가>새 항목 대화 상자에 표시되지 않습니다.

시리즈의 1부에서는 다음 방법에 대해 알아봅니다.

  • 항목 템플릿에 대한 클래스를 만듭니다.
  • 템플릿 구성 폴더 및 파일을 만듭니다.
  • 파일 경로에서 템플릿을 설치합니다.
  • 항목 템플릿을 테스트합니다.
  • 항목 템플릿을 제거합니다.

필수 조건

  • .NET SDK 7.0.100 이상 버전

    이 참조 문서에서는 템플릿에 대한 기본 사항과 템플릿을 취합하는 방법을 설명합니다. 이 정보 중 일부는 여기에 반복되어 있습니다.

  • 터미널을 열고 템플릿을 저장하고 테스트할 폴더로 이동합니다.

Important

이 문서는 .NET 7용으로 작성되었습니다. 그러나 이는 .NET 6 및 이전 버전에도 적용되지만 한 가지 차이점이 있습니다. 즉, dotnet new 구문이 다릅니다. list, search, install 및 uninstall 하위 명령은 각각 --list, --search, --install 및 --uninstall 옵션이어야 합니다.

예를 들어, .NET 7의 dotnet new install 명령은 .NET 6에서는 dotnet new --install이 됩니다. 모든 옵션 및 하위 명령 목록을 보려면 dotnet new --help 명령을 사용합니다.

필요한 폴더 만들기

이 시리즈에서는 템플릿 소스가 포함되는 “작업 폴더”와 템플릿을 테스트하는 데 사용되는 “테스트 폴더”를 사용합니다. 작업 폴더와 테스트 폴더는 동일한 부모 폴더 아래에 있어야 합니다.

먼저 부모 폴더를 만듭니다. 이름은 중요하지 않습니다. 그런 다음 working 및 test라는 두 개의 하위 폴더를 만듭니다. working 폴더 내에 content라는 하위 폴더를 만듭니다.

폴더 구조는 다음과 같이 표시됩니다.

parent_folder
├───test
└───working
    └───content

항목 템플릿 만들기

항목 템플릿은 하나 이상의 파일을 포함하는 특정 형식의 템플릿입니다. 이러한 형식의 템플릿은 이미 프로젝트가 있고 구성 파일이나 코드 파일과 같은 다른 파일을 생성하려는 경우에 유용합니다. 이 예제에서는 문자열 형식에 확장 메서드를 추가하는 클래스를 만듭니다.

터미널에서 working\content 폴더로 이동하여 extensions라는 새 하위 폴더를 만듭니다.

working
└───content
    └───extensions

extensions 폴더로 이동하여 StringExtensions.cs라는 새 파일을 만듭니다. 텍스트 편집기에서 파일을 엽니다. 이 클래스는 문자열의 내용을 반전하는 Reverse라는 확장 메서드를 제공합니다. 다음 코드를 붙여넣고 파일을 저장합니다.

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

이제 템플릿 콘텐츠가 완료되었으므로 다음 단계는 템플릿 구성을 만드는 것입니다.

템플릿 구성 만들기

자습서의 이 부분에서 템플릿 폴더는 working\content\extensions에 있습니다.

템플릿은 템플릿 폴더 루트에 특수 폴더와 구성 파일이 있기 때문에 .NET에서 인식됩니다.

먼저 .template.config라는 새 하위 폴더를 만들고 입력합니다. 그런 다음 template.json이라는 새 파일을 만듭니다. 폴더 구조는 다음과 같이 표시됩니다.

working
└───content
    └───extensions
        └───.template.config
                template.json

원하는 텍스트 편집기에서 template.json을 열고 다음 JSON 코드를 붙여넣고 저장합니다.

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Me",
    "classifications": [ "Common", "Code" ],
    "identity": "ExampleTemplate.StringExtensions",
    "name": "Example templates: string extensions",
    "shortName": "stringext",
    "tags": {
      "language": "C#",
      "type": "item"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

이 구성 파일에는 템플릿에 대한 모든 설정이 포함되어 있습니다. 기본 설정(예: name 및 shortName)도 확인할 수 있지만 item으로 설정된 tags/type 값도 있습니다. 이 값에 따라, 만든 템플릿이 "항목" 템플릿으로 분류됩니다. 만드는 템플릿 형식에 대한 제한은 없습니다. item 및 project 값은 사용자가 검색 중인 템플릿 형식을 쉽게 필터링할 수 있도록 .NET에서 권장하는 일반적인 이름입니다.

classifications 항목은 dotnet new를 실행할 때 표시되고 템플릿 목록을 가져오는 태그 열을 나타냅니다. 사용자는 분류 태그를 기준으로 검색할 수도 있습니다. template.json 파일의 tags 속성을 classifications 태그 목록과 혼동하지 마세요. 불행히도 이름이 같은 두 가지 다른 개념입니다. template.json 파일의 전체 스키마는 JSON 스키마 저장소에 있으며 template.json 참조에 설명되어 있습니다. template.json 파일에 대한 자세한 내용은 dotnet 템플릿 wiki를 참조하세요.

이 JSON 개체의 symbols 부분은 템플릿에서 사용할 수 있는 매개 변수를 정의하는 데 사용됩니다. 이 경우에는 ClassName이라는 하나의 매개 변수가 정의되어 있습니다. 정의된 매개 변수에는 다음 설정이 포함됩니다.

  • type - 이는 필수 설정이며 parameter로 설정되어야 합니다.
  • description - 템플릿 도움말에 인쇄되는 매개 변수에 대한 설명입니다.
  • datatype - 매개 변수가 사용될 때 매개 변수 값의 데이터 형식입니다.
  • replaces - 모든 템플릿 파일에서 매개 변수 값으로 바뀌어야 하는 텍스트 값을 지정합니다.
  • fileRename - replaces와 유사하며 모든 템플릿 파일의 이름에서 매개 변수 값으로 바뀌는 텍스트 값을 지정합니다.
  • defaultValue - 사용자가 매개 변수를 지정하지 않은 경우 이 매개 변수의 기본값입니다.

템플릿이 사용될 때 사용자는 ClassName 매개 변수에 대한 값을 제공할 수 있으며 이 값은 StringExtensions의 모든 발생 수를 바꿉니다. 값이 제공되지 않으면 defaultValue가 사용됩니다. 이 템플릿에는 StringExtensions.cs 파일과 StringExtensions 클래스라는 두 가지 StringExtensions 항목이 있습니다. 매개 변수의 defaultValue가 StringExtensions이므로 템플릿 사용 시 매개 변수를 지정하지 않으면 파일 이름과 클래스 이름이 변경되지 않습니다. 값이 지정되면(예: dotnet new stringext -ClassName MyExts) 파일 이름이 MyExts.cs로 바뀌고 클래스 이름이 MyExts로 변경됩니다.

템플릿에 사용할 수 있는 매개 변수를 보려면 템플릿 이름과 함께 -? 매개 변수를 사용합니다.

dotnet new stringext -?

다음과 같은 출력이 생성됩니다.

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

유효한 .template.config/template.json 파일이 있으므로 이제 템플릿을 설치할 준비가 되었습니다. 터미널에서 extensions 폴더로 이동하고 다음 명령을 실행하여 현재 폴더에 있는 템플릿을 설치합니다.

  • Windows: dotnet new install .\
  • Linux 또는 macOS: dotnet new install ./

이 명령은 사용자 템플릿을 포함하여 설치된 템플릿 목록을 출력합니다.

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

항목 템플릿 테스트

항목 템플릿을 설치했으므로 이제 템플릿을 테스트합니다.

  1. test 폴더로 이동합니다.

  2. dotnet run 명령으로 쉽게 테스트할 수 있는 작업 프로젝트를 만드는 dotnet new console을 사용하여 새 콘솔 애플리케이션을 만듭니다.

    dotnet new console

    그러면 다음과 같은 출력이 표시됩니다.

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
  Restore completed in 54.82 ms for C:\test\test.csproj.

Restore succeeded.

  3. 다음 명령을 사용하여 프로젝트를 실행합니다.

    dotnet run

    다음과 같은 출력을 얻습니다.

    Hello, World!

  4. dotnet new stringext를 실행하여 템플릿에서 StringExtensions.cs 파일을 생성합니다.

    dotnet new stringext

    다음과 같은 출력을 얻습니다.

    The template "Example templates: string extensions" was created successfully.

  5. 템플릿에 제공된 확장 메서드를 사용하여 "Hello, World!" 문자열을 반전하도록 Program.cs에서 코드를 변경합니다.

    Console.WriteLine("Hello, World!".Reverse());

    프로그램을 다시 실행하면 결과가 반전된 것을 알 수 있습니다.

    dotnet run

    다음과 같은 출력을 얻습니다.

    !dlroW ,olleH

축하합니다! .NET을 사용하여 항목 템플릿을 만들고 배포했습니다. 이 자습서 시리즈의 다음 부분을 준비하기 위해 만든 템플릿을 제거합니다. test 폴더에 있는 모든 파일과 폴더도 삭제해야 합니다. 이렇게 하면 이 자습서 시리즈의 다음 부분을 준비할 수 있는 정리 상태로 돌아갑니다.

템플릿 제거

터미널에서 확장 폴더로 이동하고 다음 명령을 실행하여 현재 폴더에 있는 템플릿을 제거합니다.

  • Windows: dotnet new uninstall .\
  • Linux 또는 macOS: dotnet new uninstall ./

이 명령은 제거된 템플릿 목록을 출력합니다. 여기에는 사용자의 템플릿이 포함되어야 합니다.

Success: <root path>\working\content\extensions was uninstalled.

언제든지 dotnet new uninstall을 사용하여 각 템플릿 패키지를 제거하는 명령을 포함하여 설치된 템플릿 패키지 목록을 볼 수 있습니다.

다음 단계

이 자습서에서는 항목 템플릿을 만들었습니다. 프로젝트 템플릿을 만드는 방법을 알아보려면 이 자습서 시리즈를 계속 진행하세요.

프로젝트 템플릿 만들기