자습서: 템플릿 패키지 만들기

아티클
12/20/2024

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

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

시리즈의 이 부분에서는 다음 방법을 알아봅니다.

Microsoft.TemplateEngine.Authoring.Templates NuGet 패키지를 사용하여 템플릿 패키지를 만듭니다.
NuGet 패키지 파일에서 템플릿 패키지를 설치합니다.
패키지 ID별로 템플릿 패키지를 제거합니다.

필수 구성 요소

이 자습서 시리즈의 1부 및 2부 완료합니다.

이 자습서에서는 이 자습서 시리즈의 처음 두 부분에서 만든 두 개의 템플릿을 사용합니다. working\content 폴더에 템플릿을 폴더로 복사하는 한 다른 템플릿을 사용할 수 있습니다.
터미널을 열고 작업 폴더로 이동합니다.
.NET 8 또는 .NET 9를 설치합니다.
NuGet 패키지 피드에서 Microsoft.TemplateEngine.Authoring.Templates 템플릿을 설치합니다.
- 터미널에서 dotnet new install Microsoft.TemplateEngine.Authoring.Templates 명령을 실행합니다.

템플릿 패키지 프로젝트 만들기

템플릿 패키지는 NuGet 패키지에 압축된 하나 이상의 템플릿입니다. 템플릿 패키지를 설치하거나 제거하면 패키지에 포함된 모든 템플릿이 각각 추가되거나 제거됩니다.

템플릿 패키지는 NuGet 패키지(.nupkg) 파일로 표시됩니다. 또한 NuGet 패키지와 마찬가지로 템플릿 패키지를 NuGet 피드에 업로드할 수 있습니다. dotnet new install 명령은 NuGet 패키지 피드, .nupkg 파일 또는 템플릿이 있는 디렉터리에서 템플릿 패키지 설치를 지원합니다.

일반적으로 C# 프로젝트 파일을 사용하여 코드를 컴파일하고 이진 파일을 생성합니다. 그러나 프로젝트를 사용하여 템플릿 패키지를 생성할 수도 있습니다. .csproj설정을 변경하여 코드를 컴파일하지 못하게 하고 대신 템플릿의 모든 자산을 리소스로 포함할 수 있습니다. 이 프로젝트가 빌드되면 템플릿 패키지 NuGet 패키지를 생성합니다.

생성하려는 패키지에는 이전에 만든 항목 및 프로젝트 템플릿이 포함됩니다.

Microsoft.TemplateEngine.Authoring.Templates 패키지는 템플릿 작성에 유용한 템플릿이 포함되어 있습니다. 이 패키지를 설치하려면 nuget.org 작업 디렉터리에서 NuGet 피드로 사용할 수 있어야 합니다.

작업 폴더에서 다음 명령을 실행하여 템플릿 패키지를 만듭니다.

dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

-n 매개 변수는 프로젝트 파일 이름을 AdatumCorporation.Utility.Templates.csproj로 설정합니다. 다음 출력과 유사한 결과가 표시됩니다.

The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

다음으로, 코드 편집기에서 AdatumCorporation.Utility.Templates.csproj 파일을 열고 템플릿의 힌트에 따라 채웁니다.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

프로젝트 XML에 대한 설명

XML 코드 조각의 <PropertyGroup> 아래 설정은 두 그룹으로 나뉩니다.

첫 번째 그룹은 NuGet 패키지에 필요한 속성을 다룹니다. NuGet 피드에서 패키지를 식별하는 NuGet 패키지 속성과 관련된 네 가지 <Package*> 설정이 있습니다. NuGet에서 사용하는 동안 <PackageId> 값은 템플릿 패키지를 제거하는 데도 사용됩니다. <Title> 및 <PackageTags>같은 나머지 설정은 NuGet 피드 및 .NET 패키지 관리자에 표시되는 메타데이터와 관련이 있습니다. NuGet 설정에 대한 자세한 내용은 NuGet 및 MSBuild 속성참조하세요.

메모

템플릿 패키지가 dotnet new search 결과에 표시되도록 하려면 <PackageType>을(를) Template로 설정해야 합니다.

두 번째 그룹에서 <TargetFramework> 설정은 팩 명령을 실행하여 프로젝트를 컴파일하고 압축할 때 MSBuild가 제대로 실행되도록 합니다. 또한 이 그룹에는 프로젝트를 만들 때 NuGet 패키지의 적절한 폴더에 템플릿을 포함하도록 프로젝트를 구성하는 것과 관련이 있는 설정도 포함됩니다.

<NoWarn> 설정은 템플릿 패키지 프로젝트에 적용되지 않는 경고 메시지를 표시하지 않습니다.
<NoDefaultExcludes> 설정은 . 시작하는 파일 및 폴더(예: .gitignore)가 템플릿의 일부인지 확인합니다. NuGet 패키지의 기본 동작은 해당 파일 및 폴더를 무시하는 것입니다.

<ItemGroup> 두 개의 항목을 포함합니다. 먼저 <Content> 항목에는 템플릿 폴더의 모든 항목이 콘텐츠로 포함됩니다. 또한 컴파일된 코드(템플릿을 테스트하고 컴파일한 경우)가 포함되지 않도록 bin 폴더 또는 obj 폴더를 제외하도록 설정됩니다. 둘째, <Compile> 항목은 어디에 있든 컴파일에서 모든 코드 파일을 제외합니다. 이 설정을 사용하면 템플릿 패키지를 만드는 데 사용되는 프로젝트가 템플릿 폴더 계층 구조의 코드를 컴파일하지 못하게 됩니다.

팁

NuGet 메타데이터 설정에 대한 자세한 내용은 템플릿을 NuGet 패키지(nupkg 파일)압축을 참조하세요.

만든 프로젝트 파일에는 MSBuild 작업 및 지역화 설정을 작성하는 템플릿이 포함됩니다.

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

중요하다

콘텐츠 콘텐츠 폴더에는 SampleTemplate 폴더가 포함되어 있습니다. 이 폴더는 작성 템플릿에 데모용으로 추가되었으므로 삭제하십시오.

이러한 MSBuild 작업은 템플릿의 기능에 대한 유효성 검사와 지역화 기능을 제공합니다. 지역화는 기본적으로 사용하지 않도록 설정됩니다. 지역화 파일을 만들 수 있도록 하려면 LocalizeTemplatestrue설정합니다.

압축 및 설치

프로젝트 파일을 저장합니다. 템플릿 패키지를 빌드하기 전에 폴더 구조가 올바른지 확인합니다. 압축하려는 모든 템플릿은 템플릿 폴더의 자체 폴더에 배치되어야 합니다. 폴더 구조는 다음 계층 구조와 유사해야 합니다.

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

콘텐츠 폴더에는 확장 및 consoleasync두 개의 폴더가 있습니다.

터미널의 작업 폴더에서 dotnet pack 명령을 실행합니다. 이 명령은 다음 출력에 표시된 대로 프로젝트를 빌드하고 working\bin\Release 폴더에 NuGet 패키지를 만듭니다.

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

다음으로, dotnet new install 명령을 사용하여 템플릿 패키지를 설치합니다. Windows에서:

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Linux 또는 macOS에서:

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

다음과 유사한 출력이 표시됩니다.

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

NuGet 패키지를 NuGet 피드에 업로드한 경우, dotnet new install <PACKAGE_ID> 명령을 사용할 수 있습니다. 여기서 <PACKAGE_ID>은 .csproj 파일의 <PackageId> 설정과 동일합니다.

템플릿 패키지 제거

.nupkg 파일을 직접 사용하거나 NuGet 피드를 사용하여 템플릿 패키지를 설치한 방법에 관계없이 템플릿 패키지를 제거하는 것은 동일합니다. 제거하려는 템플릿의 <PackageId>을 사용하세요. dotnet new uninstall 명령을 실행하여 설치된 템플릿 목록을 가져올 수 있습니다.

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

dotnet new uninstall AdatumCorporation.Utility.Templates 실행하여 템플릿 패키지를 제거합니다. 이 명령은 제거된 템플릿 패키지에 대한 정보를 출력합니다.

축하합니다! 템플릿 패키지를 설치하고 제거했습니다.

다음 단계

이미 배운 템플릿에 대한 자세한 내용은 dotnet 새 문서에 대한 사용자 지정 템플릿을 참조하세요.

다음을 통해 공유