.NET ファイル ベースのアプリでの winapp CLI の使用

作業例については、 dotnet-file-app サンプルを参照してください。 完全なリファレンスについては、CLI リファレンスの単一ファイル モードを参照してください。

.NET 10 では、プロジェクト ファイルなしで 1 つの.cs ファイルを実行できます。 このガイドでは、winapp runを使用してパッケージ ID でそのファイルを実行する方法について説明します。これにより、Windows.ApplicationModel.Package.Current、アプリ通知、デバイス上の AI などの API が機能します。 マニフェストまたはイメージアセットを自分で作成する必要はありません。winapp が生成します。

パッケージ ID は、Windows app モデルの主要な概念です。 これにより、アプリケーションは特定のWindows API にアクセスしたり、クリーン インストール/アンインストール エクスペリエンスを利用したりすることができます。 dotnet runで実行されるファイル ベースのアプリには、パッケージ ID がありません。

Prerequisites

  1. .NET SDK 10.0.300 以降: .NET 10 SDK をインストールします (インストール後に再起動が必要)。

    winget install Microsoft.DotNet.SDK.10 --source winget
    
  2. winapp CLI: winget を使用して winapp ツールをインストールします (既にインストールされている場合は更新します)。

    winget install Microsoft.winappcli --source winget
    

1. ファイルベースのアプリを作成する

hello.cs という名前のファイルを含むフォルダーを作成します:

#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

using Windows.ApplicationModel;

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

#:property 行は、.csproj が行うのと同じようにアプリを構成します。 Windows TargetFramework では、Package などの Windows ランタイム API へのアクセスが可能になります。

dotnet runで実行してください:

dotnet run hello.cs

出力は Not packaged:アプリはパッケージ ID なしで実行されます。

2. パッケージ ID を使用して実行する

winapp で同じファイルを実行:

winapp run hello.cs

winapp はアプリをビルドし、ビルド出力でマニフェストと既定のイメージ資産を生成し、アプリをパッケージとして登録して起動します。 出力には、パッケージ ID が表示されます。

Package Family Name: hello-<hash>_<publisher-hash>

ソース フォルダーにはまだ hello.csのみが含まれます。 これはコンソール アプリ (OutputType=Exe) であるため、winapp は実行エイリアスを介してこれを起動するため、出力がターミナルに表示されます。

登録はアプリの終了後も維持されるため、winapp run hello.cs を再度実行すると、同じ ID が再利用されます。 手順 5 で削除します。

3. パッケージに名前を付けます

既定では、パッケージ名はファイル名にファイルのパスの短いハッシュを加えたものです。 独自の名前を選択するには、まず現在のパッケージの登録を解除してください。これは新しい名前を登録すると、新しいパッケージが登録されるためです。

winapp unregister hello.cs

次に、 #:property ディレクティブを hello.csの先頭に追加します。

#:property WinAppPackageName=com.contoso.hello
#:property WinAppDisplayName=Contoso Hello
#:property Version=1.0.0

もう一度実行します:

winapp run hello.cs

出力には、新しい名前が表示されます。例えば Package Family Name: com.contoso.hello_<publisher-hash> です。 アプリは、[スタート] メニューにも Contoso Hello として表示されます。

すべての ID プロパティとその既定値については、「マニフェストのプロパティ」を参照してください。

4. 次のコマンドを使用して実行します。 dotnet run

単純な dotnet run から同じパッケージ化された起動を行うには、hello.cs の先頭で Microsoft.Windows.SDK.BuildTools.WinApp パッケージを参照します。

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
dotnet run hello.cs

出力には、 winapp runと同じパッケージ ID が表示されます。 dotnet run は別の出力フォルダーにビルドされるため、別の場所からインストールされた既存の登録情報を上書きする旨の警告が表示されます。 これは想定されており、無視してもかまいません。

このパッケージでは、アプリにプレースホルダー ウィンドウ アイコンも提供されるため、ウィンドウ化されたアプリのタイトル バーにアイコンが表示されます。 独自のものを使用するには、ApplicationIcon を .ico ファイルに指定します。

#:property ApplicationIcon=Assets\MyApp.ico

この起動を制御するためのプロパティについては、「dotnet runでの実行」を参照してください。

5. クリーンアップ

.cs ファイルをwinapp unregisterに渡して、登録を解除します。

winapp unregister hello.cs

機能またはカスタム マニフェストを追加する

一部の API には、宣言されたケーパビリティが必要です。 たとえば、Windows AI API には次のものが必要ですsystemAIModels:

#:property WinAppCapabilities=systemAIModels

winapp は、各機能を正しいマニフェスト要素に書き込みます。 完全な一覧と名前付け規則については、「 機能 」を参照してください。

プロトコル ハンドラー、ファイルの関連付け、およびその他のシェル統合には、明示的に定義されたマニフェストが必要です。 hello.csの横にhello.appxmanifestを配置すると、winapp は新たに生成する代わりにそれを使用します。 詳細は、自分のマニフェストを持ち込むの参照してください。

次のステップ

  • 配布用パッケージ: winapp run は、開発目的でのみアプリを登録します。 配布可能な MSIX を作成するには、コードをプロジェクトに移動し、.NET ガイドの MSIX によるパッケージ化の手順に従ってください。
  • Explore Windows API: パッケージ ID を使用して、 これで、Notifications、on-device AI、およびその他の identity 依存 API