Приложения на основе файлов

Эта статья относится к: ✔️ пакета SDK для .NET 10 и более поздних версий

Приложения на основе файлов позволяют создавать, запускать и публиковать приложения .NET из одного файла C# без создания традиционного файла проекта. Они предлагают упрощенную альтернативу традиционным проектам .NET. Этот подход упрощает разработку сценариев, служебных программ и небольших приложений. Пакет SDK для .NET автоматически создает необходимую конфигурацию проекта на основе директив в исходном файле.

Основные преимущества:

Сокращенный шаблон для простых приложений.
Автономные исходные файлы с внедренной конфигурацией.
Нативная публикация AOT включена по умолчанию.
Автоматическая упаковка в виде средств .NET.

В этой статье вы узнаете, как эффективно создавать, настраивать и работать с приложениями на основе файлов.

Поддерживаемые директивы

Приложения на основе файлов используют директивы, префиксированные с #:, для настройки сборки и запуска приложения. Поддерживаемые директивы: #:package, #:project, #:propertyи #:sdk. Поместите эти директивы в начало файла C#.

`#:package`

Добавляет ссылку на пакет NuGet в приложение.

#:package Newtonsoft.Json
#:package Serilog version="3.1.1"

`#:project`

Ссылается на другой файл проекта или каталог, содержащий файл проекта.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Задает значение свойства MSBuild.

#:property TargetFramework=net10.0
#:property PublishAot=false

`#:sdk`

Указывает используемый пакет SDK. По умолчанию — Microsoft.NET.Sdk.

#:sdk Microsoft.NET.Sdk.Web

Команды CLI

Интерфейс командной строки .NET обеспечивает полную поддержку файловых приложений с помощью знакомых команд.

Запуск приложений

Запустите приложение на основе файлов непосредственно с помощью dotnet run команды:

dotnet run file.cs

Или используйте сокращенный синтаксис:

dotnet file.cs

Передача аргументов

Передайте аргументы в ваше приложение несколькими способами:

dotnet run file.cs -- arg1 arg2

Аргументы после -- передаются вашему приложению. Без --аргументов перейдите к команде dotnet run :

dotnet run file.cs arg1 arg2

Однако при использовании краткого синтаксиса все аргументы отправляются в приложение:

dotnet file.cs arg1 arg2

Разработка приложений

Скомпилируйте приложение на основе файлов с помощью dotnet build команды:

dotnet build file.cs

Пакет SDK создает временный проект и создает приложение.

Очистка выходных данных сборки

Удалите артефакты сборки с помощью dotnet clean команды:

dotnet clean file.cs

Очистка всех файловых приложений в каталоге:

dotnet clean file-based-apps

Публикация приложений

Создайте пакет развертывания с помощью dotnet publish команды:

dotnet publish file.cs

Приложения на основе файлов включают собственную публикацию AOT по умолчанию, создавая оптимизированные, автономные исполняемые файлы.

Пакет как инструмент

Упаковайте приложение на основе файлов в виде средства .NET с помощью dotnet pack команды:

dotnet pack file.cs

Приложения на основе файлов, заданные PackAsTool=true по умолчанию.

Преобразование в проект

Преобразуйте приложение на основе файлов в традиционный проект с помощью dotnet project convert команды:

dotnet project convert file.cs

Эта команда создает файл с SDK и свойствами, эквивалентными .csproj. Все # директивы удаляются из .cs файла и превратятся в элементы в соответствующем .csproj файле.

Восстановить зависимости

Восстановите пакеты NuGet, на которые ссылается файл, с помощью dotnet restore команды:

dotnet restore file.cs

Восстановление выполняется неявно при сборке или запуске приложения.

Включенные элементы по умолчанию

Приложения на основе файлов автоматически включают определенные типы файлов для компиляции и упаковки.

По умолчанию включены следующие элементы:

Сам файл C#.
Файлы ресурсов ResX в одном каталоге.

Другие пакеты SDK включают другие типы файлов:

Microsoft.NET.Sdk.Web включает *.json файлы конфигурации.
Другие специализированные пакеты SDK могут включать другие шаблоны.

Публикация AOT в собственном коде

По умолчанию приложения на основе файлов обеспечивают нативную компиляцию заранее (AOT). Эта функция создает оптимизированные автономные исполняемые файлы с более быстрым запуском и меньшим объемом памяти.

Если необходимо отключить собственный AOT, используйте следующий параметр:

#:property PublishAot=false

Для получения дополнительной информации о родном развертывании AOT см. раздел Родное развертывание AOT.

Секреты пользователя.

Приложения на основе файлов создают стабильный идентификатор секретов пользователя на основе хэша полного пути к файлу. Этот идентификатор позволяет хранить конфиденциальную конфигурацию отдельно от исходного кода.

Доступ к секретам пользователей так же, как и к традиционным проектам:

dotnet user-secrets set "ApiKey" "your-secret-value" --project file.cs

Дополнительные сведения см. в статье "Безопасное хранилище секретов приложений в разработке".

Профили запуска

Приложения на основе файлов поддерживают профили запуска для настройки работы приложения во время разработки. Вместо размещения профилей запуска в Properties/launchSettings.jsonфайловых приложениях можно использовать файл параметров запуска с неструктурированным именем [ApplicationName].run.json в том же каталоге, что и исходный файл.

Файл параметров неструктурированного запуска

Создайте файл параметров запуска с именем приложения. Например, если приложение на основе файлов является app.cs, создайте app.run.json в том же каталоге:

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Несколько приложений на основе файлов

При наличии нескольких файловых приложений в одном каталоге каждый из них может иметь собственный файл параметров запуска:

📁 myapps/
├── foo.cs
├── foo.run.json
├── bar.cs
└── bar.run.json

Выбор профиля

Интерфейс командной строки .NET выбирает профили запуска с помощью следующего приоритета:

Профиль, указанный параметром --launch-profile .
Профиль, указанный переменной DOTNET_LAUNCH_PROFILE среды.
Первый профиль, определенный в файле параметров запуска.

Чтобы запуститься с определенным профилем, выполните указанные действия.

dotnet run app.cs --launch-profile https

Традиционные параметры запуска

Приложения на основе файлов также поддерживают традиционный Properties/launchSettings.json файл. Если оба файла существуют, традиционное расположение имеет приоритет. Если оба файла присутствуют, интерфейс командной строки .NET записывает предупреждение, чтобы уточнить, какой файл используется.

Выполнение команд в оболочке

Включите прямое выполнение приложений, основанных на файлах, на системах, подобных Unix, с помощью строки shebang и разрешений исполняемого файла.

Добавьте shebang в начало файла:

#!/usr/bin/env dotnet
#:package Spectre.Console

using Spectre.Console;

AnsiConsole.MarkupLine("[green]Hello, World![/]");

Сделайте исполняемый файл:

chmod +x file.cs

Запустите напрямую:

./file.cs

Неявные файлы сборки

Приложения на основе файлов учитывают файлы конфигурации MSBuild и NuGet в одном каталоге или родительских каталогах. Эти файлы влияют на процесс сборки вашего приложения с помощью SDK. Помните об этих файлах при организации файловых приложений.

`Directory.Build.props`

Определяет свойства MSBuild, которые применяются ко всем проектам в дереве каталогов. Приложения на основе файлов наследуют эти свойства.

`Directory.Build.targets`

Определяет целевые объекты MSBuild и настраиваемую логику сборки. Приложения на основе файлов выполняют эти целевые объекты во время сборки.

`Directory.Packages.props`

Включает централизованное управление пакетами для зависимостей NuGet. Приложения на основе файлов могут использовать централизованно управляемые версии пакетов.

`nuget.config`

Настраивает источники и параметры пакета NuGet. Приложения на основе файлов используют эти конфигурации при восстановлении пакетов.

`global.json`

Указывает используемую версию пакета SDK для .NET. Приложения на основе файлов учитывают этот выбор версии.

Кэширование сборки

Пакет SDK для .NET кэширует выходные данные сборки для повышения производительности последующих сборок. Приложения на основе файлов участвуют в этой системе кэширования.

Поведение кэша

Кэш пакета SDK кэширует выходные данные сборки на основе следующих данных:

Содержимое исходного файла.
Конфигурация директив.
Версия пакета SDK.
Неявные файлы сборки.

Кэширование повышает производительность сборки, но может вызвать путаницу при:

Изменения в неявных файлах сборки не инициируют пересборку.
Перемещение файлов в разные каталоги не делает кэш недействительным.

Обходные пути

Выполните полную сборку с помощью флага --no-cache :
```
dotnet build file.cs --no-cache
```
Принудительное выполнение чистой сборки для обхода кэша:
```
dotnet clean file.cs
dotnet build file.cs
```

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-12-17