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

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

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

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

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

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

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

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

`#:package`

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

#:package Newtonsoft.Json
#:package Serilog@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
#:sdk Aspire.AppHost.Sdk@13.0.2

Команды CLI

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

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

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

dotnet run --file file.cs

Или используйте dotnet run команду, за которой следует имя файла:

dotnet run file.cs

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

dotnet file.cs

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

Передайте аргументы в приложение, разместив их после --:

dotnet run file.cs -- arg1 arg2

Без --аргументов перейдите к команде dotnet run :

dotnet run file.cs arg1 arg2

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

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

dotnet build file.cs

Пакет SDK создает виртуальный проект и создает приложение. По умолчанию выходные данные сборки переходят во временный каталог системы под <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

--output Используйте параметр с командойdotnet build, чтобы указать другой путь. Чтобы определить новый выходной путь по умолчанию, задайте OutputPath свойство в верхней части файла с помощью директивы: #:property OutputPath=./output

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

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

dotnet clean file.cs

Удаление кэша для приложений на основе файлов в каталоге:

dotnet clean file-based-apps

Используйте параметр --days вместе с предыдущей командой, чтобы указать, сколько дней нужно, чтобы папка артефактов оставалась неиспользованной перед удалением. Число дней по умолчанию — 30.

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

Приложения на основе файлов включают собственную публикацию AOT по умолчанию, создавая оптимизированные, автономные исполняемые файлы. Отключите эту функцию, добавив #:property PublishAot=false в начало файла.

dotnet publish Используйте команду для создания независимого исполняемого файла:

dotnet publish file.cs

Расположение исполняемого файла по умолчанию — это каталог рядом artifacts.cs с файлом с подкаталогом с именем приложения. Используйте параметр --output с командой dotnet publish, чтобы указать другой путь.

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

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

dotnet pack file.cs

Приложения на основе файлов, заданные PackAsTool=true по умолчанию. Отключите этот параметр, добавив #:property PackAsTool=false в начало файла.

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

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

dotnet project convert file.cs

Эта команда создает копию .cs файла и создает .csproj файл с эквивалентными элементами пакета SDK, свойствами и ссылками на пакеты на основе директив исходного файла #: . Оба файла помещаются в каталог с именем приложения рядом с исходным .cs файлом, который остается незамеченным.

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

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

dotnet restore file.cs

По умолчанию восстановление выполняется неявно при сборке или запуске приложения. Однако можно передать --no-restore командам dotnet build и dotnet run для сборки или запуска без необходимости восстановить.

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

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

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

Сам файл 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" --file file.cs

Список пользовательских секретов для файловых приложений:

dotnet user-secrets list --file file.cs

Команда dotnet user-secrets list выводит значение секретов. Не помещайте эту команду в скрипты, которые выполняются в общедоступных контекстах.

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

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

Приложения на основе файлов поддерживают профили запуска для настройки работы приложения во время разработки. Вместо размещения профилей запуска в 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

Замечание

Используйте окончания строки LF вместо CRLF при добавлении шебанга. Не включайте BOM в файл.

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

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

`Directory.Build.props`

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

`Directory.Build.targets`

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

`Directory.Packages.props`

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

`nuget.config`

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

`global.json`

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

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

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

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

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

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

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

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

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

Очистите кэш артефактов для приложений на основе файлов с помощью следующей команды:

dotnet clean file-based-apps

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

См. также

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2025-12-19