Обучение
Модуль
Создание проекта .NET Aspire - Training
Узнайте, как создавать облачные приложения с нуля или добавлять оркестрацию в существующее приложение с помощью стека .NET Aspire в .NET 8.
Этот браузер больше не поддерживается.
Выполните обновление до Microsoft Edge, чтобы воспользоваться новейшими функциями, обновлениями для системы безопасности и технической поддержкой.
В состав пакета SDK для .NET входит множество шаблонов, которые уже установлены и готовы к использованию. Команда dotnet new
позволяет не только использовать шаблоны, но и устанавливать и удалять их. Можно создавать собственные шаблоны для проектов любого типа, например приложений, служб, средств или библиотек классов. Можно также создать шаблон, формирующий один или несколько отдельных файлов, например файл конфигурации.
Устанавливать пользовательские шаблоны из пакета NuGet можно в любом веб-канале NuGet, указывая прямую ссылку на файл NUPKG для NuGet или каталог в файловой системе, который содержит нужный шаблон. Модуль шаблонов предоставляет возможности, которые позволяют заменять значения, включать и исключать файлы, а также выполнять пользовательские операции обработки при использовании шаблона.
Модуль шаблонов имеет открытый код. Репозиторий кода в Интернете — dotnet/templating в GitHub. Дополнительные шаблоны, в том числе шаблоны сторонних поставщиков, можно найти с помощью dotnet new search
. Дополнительные сведения о создании и использовании пользовательских шаблонов см. в записи блога Создание собственных шаблонов для команды dotnet new и на вики-сайте, посвященном репозиторию dotnet/templating в GitHub.
Примечание
Примеры шаблонов доступны в репозитории dotnet/templating GitHub.
Пошаговое руководство по созданию шаблона см. в учебнике Создание пользовательского шаблона для команды dotnet new.
При установке пакета SDK для .NET вы получаете более десяти встроенных шаблонов для создания проектов и файлов, включая консольные приложения, библиотеки классов, проекты модульных тестов, приложения ASP.NET Core (в том числе проекты Angular и React) и файлы конфигурации. Чтобы получить список встроенных шаблонов, выполните dotnet new list
команду:
dotnet new list
Шаблон состоит из следующих частей:
К исходным файлам и папкам относятся все файлы и папки, которые должен использовать модуль шаблонов при выполнении команды dotnet new <TEMPLATE>
. Модуль шаблонов предполагает использование запускаемых проектов в качестве исходного кода для создания проектов. Это дает ряд преимуществ.
Файлы и папки, которые могут храниться в шаблоне, не ограничены формальными типами проектов .NET. Исходные файлы и папки могут включать в себя любое содержимое, которое требуется создавать при использовании шаблона, даже если модуль шаблонов создает только один файл в качестве выходного.
Создаваемые шаблоном файлы можно изменять с помощью логики и параметров, которые предоставляются в файле конфигурации template.json. Пользователь может переопределять эти параметры, передавая их в команду dotnet new <TEMPLATE>
. Типичный пример пользовательской логики — определение имени класса или переменной в файле кода, который развернут с помощью шаблона.
Файл template.json размещается в папке .template.config в корневом каталоге шаблона. Он предоставляет сведения о конфигурации модулю шаблонов. В приведенной ниже таблице приведены элементы конфигурации, которые необходимы и достаточны для создания работающего шаблона.
Элемент | Тип | Описание |
---|---|---|
$schema |
URI-адрес | Схема JSON для файла template.json. Редакторы, поддерживающие схемы JSON, обеспечивают возможности редактирования JSON при указании схемы. Например, в Visual Studio Code требуется, чтобы этот элемент включал поддержку IntelliSense. Используйте значение http://json.schemastore.org/template . |
author |
строка | Автор шаблона. |
classifications |
array(string) | Ноль или более характеристик шаблона, по которым пользователь может найти его. Если шаблон присутствует в списке шаблонов, созданных с помощью команды dotnet new list , классификации также приводятся в столбце Теги. |
identity |
строка | Уникальное имя шаблона. |
name |
строка | Имя шаблона, которое видят пользователи. |
shortName |
строка | Сокращенное имя по умолчанию для выбора шаблона, которое используется во всех средах, где имя шаблона указывается пользователем, а не выбирается в графическом пользовательском интерфейсе. Например, короткое имя полезно при использовании шаблонов из командной строки с помощью команд CLI. |
sourceName |
строка | Имя в исходном дереве, заменяемое именем, которое указывает пользователь. Обработчик шаблонов будет искать любое вхождение sourceName , упомянутого в файле конфигурации, и заменять его именами и содержимым файлов. Значение, которое нужно изменить, может быть задано с помощью параметров -n или --name при выполнении шаблона. Если имя не указано, используется текущий каталог. |
preferNameDirectory |
Логический | Указывает, следует ли создать каталог для шаблона, если указано имя, но выходной каталог не задан (вместо создания содержимого непосредственно в текущем каталоге). По умолчанию используется значение false. |
Полная схема файла template.json находится в хранилище схем JSON. Дополнительные сведения о файле template.json см. на вики-сайте о шаблонах dotnet. Более подробные примеры и сведения о том, как сделать шаблоны видимыми в Visual Studio, проверка из ресурсов, созданных Сайеed Hashimi.
Например, вот папка шаблона, содержащая два файла содержимого: console.cs и readme.txt. Существует также требуемая папка с именем .template.config , содержащая файл template.json .
└───mytemplate
│ console.cs
│ readme.txt
│
└───.template.config
template.json
Файл template.json выглядит примерно так:
{
"$schema": "http://json.schemastore.org/template",
"author": "Travis Chau",
"classifications": [ "Common", "Console" ],
"identity": "AdatumCorporation.ConsoleTemplate.CSharp",
"name": "Adatum Corporation Console Application",
"shortName": "adatumconsole"
}
Папка mytemplate представляет собой устанавливаемый пакет шаблонов. После установки этого пакета вы сможете использовать shortName
с командой dotnet new
. Например, dotnet new adatumconsole
будет выводить файлы console.cs
и readme.txt
в текущую папку.
Шаблоны .NET можно локализуть. Если шаблон локализован для языка, соответствующего текущему языковому стандарту, его элементы отображаются на том же языке, что и интерфейс командной строки. Локализация является необязательной при создании новых шаблонов.
Локализуемые элементы шаблона:
Файлы локализации имеют формат JSON, и должен существовать только один файл для каждого языка и региональных параметров. Соглашение об именовании: templatestrings.<lang code>.json
где lang code
соответствует одному из параметров CultureInfo . Все файлы локализации должны находиться в папке .template-config\localize
.
Код JSON локализации состоит из пар "ключевое значение":
template.json
. Если элемент является дочерним, используйте полный путь с /
разделителем.Дополнительные сведения о локализации шаблонов см. на странице локализации dotnet.
Например, вот template.json файл с некоторыми локализуемыми полями:
{
"$schema": "http://json.schemastore.org/template",
"author": "Microsoft",
"classifications": "Config",
"name": "EditorConfig file",
"description": "Creates an .editorconfig file for configuring code style preferences.",
"symbols": {
"Empty": {
"type": "parameter",
"datatype": "bool",
"defaultValue": "false",
"displayName": "Empty",
"description": "Creates empty .editorconfig instead of the defaults for .NET."
}
}
}
И некоторые поля должны быть локализованы в бразильском португальском языке. Имя файла будет templatestrings.pt-BR.json
соответствовать языку и региональным параметрам и выглядеть следующим образом:
{
"author": "Microsoft",
"name": "Arquivo EditorConfig",
"description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
"symbols/Empty/displayName": "Vazio",
"symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}
Пользовательский шаблон упаковывается с помощью команды dotnet pack и файла .csproj. Вместо этого можно применить NuGet с помощью команды nuget pack и файла .nuspec. Но для работы NuGet требуется платформа .NET Framework в ОС Windows или Mono в ОС Linux и macOS.
Этот файл .csproj несколько отличается от традиционных файлов .csproj в проектах кода. Обратите внимание на следующие параметры.
<PackageType>
со значением Template
.<PackageVersion>
со значением допустимой версии NuGet.<PackageId>
со значением уникального идентификатора. Этот идентификатор используется для удаления пакета шаблона, а также в веб-каналах NuGet для регистрации пакета шаблонов.<Title>
, <Authors>
, <Description>
и <PackageTags>
.<TargetFramework>
, даже если не используется созданный процессом шаблона двоичный файл. В приведенном ниже примере он имеет значение netstandard2.0
.Чтобы использовать пакет шаблонов в формате пакета NuGet .nupkg, все шаблоны должны быть сохранены в папке content внутри пакета. Есть еще несколько параметров, которые нужно добавить в файл .csproj, чтобы созданный файл .nupkg можно было установить как пакет шаблонов:
<IncludeContentInPack>
получает значение true
, чтобы включить все файлы проекта, отмеченные в пакете NuGet как содержимое (content).<IncludeBuildOutput>
получает значение false
, чтобы исключить все бинарные файлы, созданные компилятором из пакета NuGet.<ContentTargetFolders>
получает значение content
. Это гарантирует, что указанные в качестве содержимого (content) файлы будут сохранены в папку content в пакете NuGet. Эта папка в пакете NuGet анализируется системой шаблонов dotnet.Вы можете легко исключить все файлы кода из компиляции с проектом шаблона, указав элемент <Compile Remove="**\*" />
в файле проекта, внутри элемента <ItemGroup>
.
Чтобы структурировать пакет шаблонов, можно поместить все шаблоны в отдельные папки, а сами эти папки шаблонов — в папку templates в том же каталоге, где расположен файл .csproj. Это позволит вам использовать один элемент проекта для включения всех файлов и папок из папки templates в качестве содержимого (content). Внутри элемента <ItemGroup>
создайте элемент <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
.
Ниже приведен пример CSPROJ-файла , который следует всем этим рекомендациям. Он упаковывает дочернюю папку templates в папку пакета content и исключает из компиляции все файлы кода.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<PackageType>Template</PackageType>
<PackageVersion>1.0</PackageVersion>
<PackageId>AdatumCorporation.Utility.Templates</PackageId>
<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>
<TargetFramework>netstandard2.0</TargetFramework>
<IncludeContentInPack>true</IncludeContentInPack>
<IncludeBuildOutput>false</IncludeBuildOutput>
<ContentTargetFolders>content</ContentTargetFolders>
</PropertyGroup>
<ItemGroup>
<Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
<Compile Remove="**\*" />
</ItemGroup>
</Project>
В следующем примере демонстрируется структура файлов и папок с помощью CSPROJ для создания пакета шаблона. Файл MyDotnetTemplates.csproj и папка templates размещаются в корневом каталоге с именем project_folder. Папка templates содержит два шаблона с именами mytemplate1 и mytemplate2. Каждый шаблон включает файлы содержимого и папку .template.config с файлом конфигурации template.json.
project_folder
│ MyDotnetTemplates.csproj
│
└───templates
├───mytemplate1
│ │ console.cs
│ │ readme.txt
│ │
│ └───.template.config
│ template.json
│
└───mytemplate2
│ otherfile.cs
│
└───.template.config
template.json
Примечание
Чтобы пакет шаблона отображался в результате dotnet new search
, для типа пакета NuGet задайте значение Template
.
Используйте команду dotnet new install для установки пакета шаблона.
Для установки пакета шаблонов используйте идентификатор пакета NuGet.
dotnet new install <NUGET_PACKAGE_ID>
Укажите пользовательский источник NuGet (например, https://api.my-custom-nuget.com/v3/index.json
).
dotnet new install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>
Укажите путь к файлу .nupkg пакета NuGet.
dotnet new install <PATH_TO_NUPKG_FILE>
Шаблоны можно установить из папки шаблона, например папку mytemplate1 из предыдущего примера. Укажите путь к папке .template.config. Путь к каталогу шаблона не должен быть абсолютным.
dotnet new install <FILE_SYSTEM_DIRECTORY>
Команда удаления без других параметров выводит список всех установленных пакетов шаблонов и включенных шаблонов.
dotnet new uninstall
Эта команда возвращает примерно следующие выходные данные:
Currently installed items:
Microsoft.Azure.WebJobs.ProjectTemplates
Version: 4.0.1942
Details:
Author: Microsoft
NuGetSource: https://api.nuget.org/v3/index.json
Templates:
Azure Functions (func) C#
Azure Functions (func) F#
Uninstall Command:
dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...
На первом уровне элементов под Currently installed items:
расположены идентификаторы, используемые для удаления пакета шаблонов. В предыдущем примере Microsoft.Azure.WebJobs.ProjectTemplates
перечислены. Если пакет шаблона был установлен с помощью пути к файловой системе, этот идентификатор — это путь к папке .template.config . В списке отображаются только установленные dotnet new install
пакеты шаблонов. Пакеты шаблонов, встроенные в пакет SDK для .NET, не отображаются.
Используйте команду dotnet new uninstall для удаления пакета шаблона.
Если пакет был установлен веб-каналом NuGet или напрямую из файла .nupkg, вам нужно предоставить идентификатор для него.
dotnet new uninstall <NUGET_PACKAGE_ID>
Если пакет был установлен указанием пути к папке .template.config, используйте тот же путь для удаления пакета. Абсолютный путь к пакету шаблонов можно найти в выходных данных команды dotnet new uninstall
. Дополнительные сведения см. в разделе "Получение списка установленных шаблонов ".
dotnet new uninstall <FILE_SYSTEM_DIRECTORY>
После установки шаблона используйте шаблон, выполнив dotnet new <TEMPLATE>
команду, как и любой другой предварительно установленный шаблон. Кроме того, можно указать параметры для команды dotnet new
, в том числе относящиеся к шаблону параметры, заданные в настройках шаблона. Укажите короткое имя шаблона непосредственно в команде.
dotnet new <TEMPLATE>
Отзыв о .NET
.NET — это проект с открытым исходным кодом. Выберите ссылку, чтобы оставить отзыв:
Обучение
Модуль
Создание проекта .NET Aspire - Training
Узнайте, как создавать облачные приложения с нуля или добавлять оркестрацию в существующее приложение с помощью стека .NET Aspire в .NET 8.