Использование интерфейса командной строки winapp с .NET

Это руководство должно работать для большинства типов проектов .NET. Шаги были протестированы с помощью консольных и пользовательских проектов, таких как WPF. Примеры работы см. в примерах dotnet-app (консоль) и wpf-app (WPF) в папке примеров.

В этом руководстве показано, как использовать интерфейс командной строки winapp с приложением .NET для отладки с помощью удостоверения пакета и упаковки приложения в виде MSIX.

Идентификатор пакета — это основная концепция модели приложений Windows. Это позволяет приложению получать доступ к определенным API-интерфейсам Windows (например, уведомлениям, безопасности, API ИИ и т. д.), иметь чистый интерфейс установки и удаления и многое другое.

Стандартный исполняемый файл (например, созданный с dotnet build) не имеет удостоверения пакета. В этом руководстве показано, как добавить его для отладки, а затем упаковать его для распространения.

Необходимые условия

пакет SDK .NET: установите пакет SDK .NET (требуется перезапуск после установки):
```
winget install Microsoft.DotNet.SDK.10 --source winget
```
winapp CLI: установите winapp средство с помощью winget (или обновите, если оно уже установлено):
```
winget install Microsoft.winappcli --source winget
```

1. Создание нового приложения .NET

Начните с создания простого консольного приложения .NET:

dotnet new console -n dotnet-app
cd dotnet-app

Запустите его, чтобы убедиться, что все работает:

dotnet run

Выходные данные должны быть "Hello, World!"

2. Обновление кода для проверки удостоверения

Мы обновим приложение, чтобы проверить, работает ли оно с идентификацией пакета. Мы будем использовать API среда выполнения Windows для доступа к API пакетов.

Сначала обновите файл project, чтобы выбрать определенную версию пакета SDK для Windows. Откройте dotnet-app.csproj и измените TargetFramework, чтобы включить версию пакета SDK Windows:

  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

Это дает доступ к среда выполнения Windows API без необходимости использования дополнительных пакетов.

Теперь замените содержимое Program.cs следующим кодом. Этот код пытается получить текущее удостоверение пакета с помощью API среда выполнения Windows. Если он успешно выполнен, он выводит имя семейства пакетов; в противном случае он выводит сообщение "Не упакованно".

using Windows.ApplicationModel;

try
{
    var package = Package.Current;
    var familyName = package.Id.FamilyName;
    Console.WriteLine($"Package Family Name: {familyName}");
}
catch (InvalidOperationException)
{
    // Thrown when app doesn't have package identity
    Console.WriteLine("Not packaged");
}

3. Запуск без идентификации

Теперь запустите приложение как обычно:

dotnet run

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

4. Инициализируйте проект с помощью winapp CLI

Команда winapp init автоматически обнаруживает файлы .csproj и запускает программу установки .NET. Он настраивает все, что вам нужно за один раз: проверяет ваши TargetFramework, добавляет необходимые пакеты NuGet, создает манифест приложения и ресурсы приложения.

Выполните следующую команду и следуйте подсказкам.

winapp init

Когда появится запрос:

Имя пакета: нажмите клавишу Enter, чтобы принять значение по умолчанию (dotnet-app)
Имя издателя: нажмите клавишу Enter, чтобы принять значение по умолчанию или введите своё имя.
Версия: нажмите клавишу ВВОД, чтобы принять 1.0.0.0
Description: нажмите Enter, чтобы принять описание по умолчанию (приложение Windows) или введите собственное описание.
настройка Windows App SDK: выбор стабильной, предварительной версии или экспериментальной версии (определяет, какая версия добавлена Windows App SDK)
TargetFramework update: если TargetFramework не содержит поддерживаемую версию пакета SDK Windows, вам будет предложено обновить его (например, net10.0-windows10.0.26100.0)
Режим разработчика: если появится запрос на "Режим разработчика", его можно включить, если вы хотите, но помните, что для него требуются права администратора.

Эта команда выполнит следующее действие:

Обновите TargetFramework в .csproj на поддерживаемый Windows TFM (при необходимости)
Добавьте Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools и Microsoft.Windows.SDK.BuildTools.WinApp ссылки на пакет NuGet в .csproj
Создайте папки Package.appxmanifest и Assets для удостоверения приложения

Замечание

В отличие от проектов на native/C++, поток .NET не создает файл winapp.yaml. Пакеты NuGet управляются непосредственно с помощью вашего .csprojприложения. Используется dotnet restore для восстановления пакетов после клонирования.

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

Чтобы убедиться, что пакеты были добавлены в ваш проект:

dotnet list package

В выходных данных должны отображаться Microsoft.WindowsAppSDK и Microsoft.Windows.SDK.BuildTools.

Добавление псевдонима запуска (для консольных приложений)

Так как мы создадим консольное приложение, необходимо убедиться dotnet run , что выходные данные консоли хранятся в текущем терминале. По умолчанию dotnet run запускает упаковаемое приложение с помощью активации AUMID, которое открывает новое окно, и окно закрывается сразу после завершения консольного приложения, проглотив все выходные данные.

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

Skip этот шаг, если вы создаете приложение пользовательского интерфейса (WPF, WinForms, WinUI). Эти приложения отрисовывают собственное окно, поэтому запуск AUMID по умолчанию — именно то, что вам нужно.

Добавьте псевдоним выполнения в манифест:
```
winapp manifest add-alias
```
Это добавляет uap5:ExecutionAlias к Package.appxmanifest (по умолчанию, имя exe вашего проекта), чтобы приложение можно было запускать по имени из терминала.
Укажите dotnet run интеграции использовать псевдоним. Откройте dotnet-app.csproj и добавьте следующие элементы внутри любого <PropertyGroup> (или создайте новый <PropertyGroup> при необходимости):
```
<WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
```
При использовании этого набора dotnet run свойств запускает приложение с помощью псевдонима выполнения и наследует текущий stdin/stdout/stderr текущего терминала, чтобы вы могли видеть встроенные выходные данные консоли.

5. Отладка с помощью идентификации

Так как winapp init добавлен пакет NuGet Microsoft.Windows.SDK.BuildTools.WinApp в проект, можно просто запустить:

dotnet run

При этом автоматически вызывается winapp run под капотом — создание гибкого пакета макета, регистрация его в Windows и запуск приложения с полными правами пакета.

Замечание

Вы можете увидеть предупреждения об уязвимостях NuGet (NU1900) о источниках пакетов. Это безопасно игнорировать. Они не влияют на сборочный процесс.

Выходные данные должны выглядеть примерно так:

Package Family Name: dotnet-app_12345abcde

Это подтверждает, что ваше приложение работает с действительным удостоверением пакета!

Альтернатива: вручную `winapp run`

Если вы не использовали winapp init (или удалили пакет NuGet), можно создать и запустить вручную:

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Чтобы добавить пакет NuGet обратно: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Подсказка

Чтобы отключить автоматическую dotnet run интеграцию, добавьте <EnableWinAppRunSupport>false</EnableWinAppRunSupport> в .csproj. Дополнительные сведения о параметрах настройки см. в документации по поддержке dotnet run .

Альтернатива: упрощённая идентификация пакета

Если вам нужен именно разреженный режим работы пакета (идентичность без копирования файлов), можно использовать create-debug-identity вместо этого. Это регистрирует разреженный пакет, указывающий на exe, а не создание свободного макета:

winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Затем запустите исполняемый файл напрямую (не используйте dotnet run, так как он может перестроить или перезаписать файл):

.\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Альтернатива: целевой объект MSBuild вручную

Если вы предпочитаете не использовать пакет NuGet, можно добавить пользовательскую цель MSBuild, которая выполняется после отладочной сборки create-debug-identity. Добавьте это в файл .csproj в конце, непосредственно перед закрывающим тегом </Project>:

  <!-- Automatically apply debug identity after Debug builds -->
  <Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

С помощью этой конфигурации dotnet build применяется идентификатор отладки, и вы можете запустить исполняемый файл напрямую. Обратите внимание, что dotnet run может привести к перестройке и перезаписи идентификатора, поэтому запустите exe вручную после сборки.

Подсказка

Дополнительные рабочие процессы отладки (присоединение отладчиков, настройка интегрированной среды разработки, отладка запуска) см. в руководстве по отладке.

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

6. Использование Windows App SDK (необязательно)

Windows App SDK предоставляет доступ к современным API-интерфейсам Windows за пределами того, что предоставляет базовый пакет SDK для Windows , такие как система уведомлений, интерфейсы API окна, управление жизненным циклом приложений и ИИ на устройстве. Если ваше приложение нуждается в любой из этих возможностей, этот шаг предназначен для вас. Если вам просто нужен идентификатор пакета для распространения, можно перейти к шагу 7.

Если вы выполнили winapp init (шаг 4), Microsoft.WindowsAppSDK уже добавлен в качестве ссылки на пакет NuGet для .csproj. Вы можете проверить с помощью dotnet list package. Если вы пропустили программу установки пакета SDK во время инициализации или необходимо добавить ее вручную, выполните следующую команду:

dotnet add package Microsoft.WindowsAppSDK

Обновите Program.cs

Замените все содержимое Program.cs следующим кодом, который добавляет проверку версии среды выполнения приложение для Windows:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");
            
            // Get Windows App Runtime version using the API
            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            // Thrown when app doesn't have package identity
            Console.WriteLine("Not packaged");
        }
    }
}

Сборка и запуск

Перестройте и запустите приложение с помощью Windows App SDK. Так как мы добавили WinAppSDK, необходимо повторно зарегистрироваться с идентификатором, чтобы winapp добавить зависимость среды выполнения. Если вы добавили пакет NuGet WinApp (рекомендуется), просто запустите dotnet run. В противном случае (замените dotnet-app на имя вашего проекта):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Теперь вы увидите такие выходные данные:

Package Family Name: dotnet-app.debug_12345abcde
Windows App Runtime Version: 8000.770.947.0

Пакет NuGet Windows App SDK включает все необходимые сборки для доступа к современным API Windows, включая:

Уведомления и активные плитки
Жизненный цикл окон и приложений
Push-уведомления
И многие другие Windows App SDK компоненты

Дополнительные сведения об использовании Windows App SDK см. в документации Windows App SDK.

7. Пакет с MSIX

Когда вы будете готовы к распространению приложения, его можно упаковать как MSIX с помощью того же манифеста.

Сборка для релиза

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

dotnet build -c Release

Замечание

Вы можете увидеть предупреждения об уязвимостях NuGet (NU1900). Это можно безопасно игнорировать, они не влияют на данные выхода сборки.

Создание сертификата разработки

Перед упаковкой требуется сертификат разработчика для подписи. Создайте его, если вы еще не сделали:

winapp cert generate --if-exists skip

Подписание и упаковка

Теперь вы можете упаковывать и подписывать. Укажите команду пакета в выходную папку сборки (замените dotnet-app и путь TFM со значениями проекта):

# package and sign the app with the generated certificate
winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --cert .\devcert.pfx

Примечание. Команда pack автоматически использует Package.appxmanifest из текущего каталога и копирует ее в целевую папку перед упаковкой. Созданный MSIX-файл будет находиться в текущем каталоге.

Установка сертификата

Прежде чем установить пакет MSIX, необходимо установить сертификат разработки. Выполните следующую команду от имени администратора:

winapp cert install .\devcert.pfx

Установка и запуск

Установите пакет, дважды щелкнув созданный файл *.msix.

Теперь вы можете запустить приложение из любого места в терминале, введя следующее:

dotnet-app

Вы должны увидеть вывод "Package Family Name", подтверждающий его установку и запуск с удостоверением.

Подсказка

Если вам нужно перепаковать приложение (например, после изменения кода), увеличьте Version в вашем Package.appxmanifest перед выполнением winapp pack еще раз. Windows требуется более высокий номер версии для обновления установленного пакета.

Tips

После подготовки к распространению вы можете подписать MSIX с помощью сертификата подписи кода из центра сертификации, чтобы пользователи не должны устанавливать самозаверяющий сертификат.
Microsoft Store подпишет MSIX за вас, так что нет необходимости подписывать его перед отправкой.
Может потребоваться создать несколько пакетов MSIX, по одному для каждой поддерживаемой архитектуры (x64, Arm64). Используйте флаг -r с dotnet build для нацеливания на конкретные архитектуры: dotnet build -c Release -r win-x64 или dotnet build -c Release -r win-arm64.

Автоматизация упаковки MSIX (необязательно)

Чтобы автоматизировать упаковку MSIX в рамках сборок выпуска, добавьте этот целевой элемент в .csproj файл (его можно добавить вместе с целевым элементом отладки).

  <!-- Automatically package as MSIX after Release builds -->
  <Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <!-- Package and sign directly from build output -->
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

С этой конфигурацией:

Создание в режиме выпуска (dotnet build -c Release) автоматически создаст пакет MSIX
MSIX упакован и подписан вашим сертификатом разработки.
Окончательный .msix файл будет находиться в корневом каталоге проекта.

Вы также можете создать настраиваемую конфигурацию (например, PackagedRelease), изменив условие '$(Configuration)' == 'PackagedRelease'на .

Дальнейшие шаги

Распространите с помощью winget: отправьте MSIX в репозиторий сообщества Windows диспетчер пакетов
Опубликовать в Microsoft Store: используйте winapp store для отправки пакета.
Set up CI/CD. Используйте действие setup-WinAppCli GitHub для автоматизации упаковки в конвейере.
Ознакомьтесь с Windows API: Теперь, с удостоверением пакета, вы можете использовать Уведомления, встроенный ИИ, и другие API-интерфейсы, зависящие от удостоверения

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

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

Last updated on 2026-05-12

Использование интерфейса командной строки winapp с .NET

Необходимые условия

1. Создание нового приложения .NET

2. Обновление кода для проверки удостоверения

3. Запуск без идентификации

4. Инициализируйте проект с помощью winapp CLI

Добавление псевдонима запуска (для консольных приложений)

5. Отладка с помощью идентификации

Альтернатива: вручную winapp run

Альтернатива: упрощённая идентификация пакета

Альтернатива: целевой объект MSBuild вручную

6. Использование Windows App SDK (необязательно)

Обновите Program.cs

Сборка и запуск

7. Пакет с MSIX

Сборка для релиза

Создание сертификата разработки

Подписание и упаковка

Установка сертификата

Установка и запуск

Tips

Автоматизация упаковки MSIX (необязательно)

Дальнейшие шаги

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

Дополнительные ресурсы

Альтернатива: вручную `winapp run`