[2026/8/14]

[Linux] Debian 12 + .NET 8 環境で Avalonia UI の空ウィンドウを出すまでに踏み抜いた全ハマりポイント

[Linux] Debian 12 + .NET 8 環境で Avalonia UI の空ウィンドウを出すまでに踏み抜いた全ハマりポイント

はじめに

WPFで作成したアセットマネージャーのLinux（Debian 12）移植を始めるにあたり、クロスプラットフォームUIフレームワークの Avalonia UI を試すことにした。

「.NET 8も入ってるし、dotnet new して dotnet run したら一発。🤯」

…と高をくくっていたのだが、ただの空ウィンドウを表示させるだけで怒涛のビルドエラーとバージョントラップに遭遇した。😞

同じように Linux 上で .NET 8 + Avalonia UI 環境の初期構築でハマった人のために、踏み抜いた全トラップと処方箋を残しておきます。

開発環境

  • OS: Debian GNU/Linux 12 (bookworm) x86_64
  • デスクトップ環境: XFCE4 + xrdp
  • Target Framework: .NET 8.0 (net8.0)

トラップ1: Debian 標準リポジトリに dotnet-sdk-8.0 が存在しない

まず環境構築のために apt から .NET 8 SDK を入れようとしたが、パッケージが見つからず爆死。

$ sudo apt install -y dotnet-sdk-8.0
E: パッケージ dotnet-sdk-8.0 が見つかりません

解決策：Microsoft公式リポジトリを追加する

Debian 12 (bookworm) の標準リポジトリには含まれていないため、Microsoft公式の .deb を適用してリポジトリを追加する必要がある。

wget [https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb](https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb) -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

sudo apt update
sudo apt install -y dotnet-sdk-8.0

これで dotnet --version が 8.0.424 等を返すようになれば準備完了。

トラップ2: テンプレート導入時の大量の赤字警告

Avaloniaのテンプレートをインストールした際、ターミナル一面に警告が出現。

$ dotnet new install Avalonia.Templates

Avalonia Window (avalonia.window) C#
  プロジェクトの可能性: パスにプロジェクトが見つかりませんでした: /home/lain/git。
  このテンプレートはプロジェクト内でのみ作成できます。
...

解決策：無視してOK（仕様）

一見「インスコ失敗か！？」と焦るが、これはテンプレート内に同梱されている「Window」や「UserControl」といった既存プロジェクト内に追加するパーツ用テンプレートが出している単なる確認注意書き。インストール自体は正常完了している。

トラップ3: 未来仕様（.NET 10）をターゲットにしようとして死ぬ (NETSDK1045)

アプリ作成コマンドを実行すると、ビルド復元時にエラー発生。

$ dotnet new avalonia.app -o model-explorer-linux
...
error NETSDK1045: 現在の .NET SDK は、ターゲットとする .NET 10.0 をサポートしていません。

解決策：フレームワークを -f net8.0 で明示指定する

最新の Avalonia.Templates はデフォルトで未来のターゲット (.NET 10 等) を見に行ってしまうことがあるため、インストール済みの .NET 8 を明示的に指定して作成する。

dotnet new avalonia.app -o model-explorer-linux -f net8.0

トラップ4: Roslynコンパイラ不整合による InitializeComponent 消失 (CS9057)

生成されたプロジェクトで dotnet run を実行すると、ソースコードはいじっていないのにコンパイルエラー。

CSC : warning CS9057: アナライザー アセンブリ '.../Avalonia.Analyzers.CSharp.dll' は、コンパイラのバージョン '4.14.0.0' を参照しています。これは、現在実行中のバージョン '4.11.0.0' よりも新しいバージョンです。

MainWindow.axaml.cs(9,9): error CS0103: 現在のコンテキストに 'InitializeComponent' という名前は存在しません

原因

NuGetが自動で最新の Avalonia（12.1.1 等）を取得した結果、.NET 8 SDK 同梱の C# コンパイラ（Roslyn 4.11.0）より高い要求を出してしまい、XAMLからC#コードを動的生成する Source Generator がサイレントスキップされた。その結果、XAML側で定義されている InitializeComponent() メソッドが存在しない扱いになってしまっていた。

トラップ5: パッケージのバージョン不整合・依存関係のバッティング (CS1705)

個別パッケージのバージョンを下げようと dotnet add package Avalonia --version 11.1.0 などを叩くと、間接依存で 11.2.0 や 12.x が混ざり込んでさらにカオスなアセンブリ競合が発生。

CSC : error CS1705: アセンブリ 'AvaloniaUI.DiagnosticsSupport.Avalonia' ... より新しいバージョンを含む 'Avalonia.Controls' Version=11.2.0.0 を使用します

解決策：.csproj で全 Avalonia 関連を 11.1.0 に統一固定する

CLIで追加・削除を繰り返すよりも、プロジェクトファイル（.csproj）を直接編集して .NET 8 と完全な互換性を持つ Avalonia 11.1.0 で統一するのが最も確実。

model-explorer-linux.csproj を以下のように書き換える：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <BuiltInComInteropSupport>true</BuiltInComInteropSupport>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Avalonia" Version="11.1.0"/>
    <PackageReference Include="Avalonia.Desktop" Version="11.1.0"/>
    <PackageReference Include="Avalonia.Themes.Fluent" Version="11.1.0"/>
    <PackageReference Include="Avalonia.Fonts.Inter" Version="11.1.0"/>
    <PackageReference Include="Avalonia.Diagnostics" Version="11.1.0"/>
  </ItemGroup>
</Project>

トラップ6: WithDeveloperTools メソッドが存在しない (CS1061)

ビルドを通そうとすると最後にダメ押しの1発。

Program.cs(20,14): error CS1061: 'AppBuilder' に 'WithDeveloperTools' の定義が含まれておらず...

解決策：Program.cs から不要なデバッグ行を削除する

バージョンを 11.1.0 に固定した際、自動生成されていたデバッグ用のメソッドが不整合を起こしているだけなので、Program.cs 内の該当行を削除する。

sed -i '/WithDeveloperTools/d' Program.cs

結末：Welcome to Avalonia!

キャッシュを掃除して再度実行。

rm -rf bin obj
dotnet run

リモートデスクトップの XFCE 画面上に、ぽーんと白背景の 「Welcome to Avalonia!」 ウィンドウが立ち上がった。

まとめ

  1. Debian 12 では Microsoft 公式リポジトリの追加が必要
  2. .NET 8 環境では Avalonia テンプレート作成時に -f net8.0 を明示する
  3. 最新パッケージ（12.x系）と Roslyn コンパイラのミスマッチに注意（.NET 8 では Avalonia 11.1.0 が安定）
  4. Source Generator エラー（InitializeComponent 消失）が出たらアセンブリのバージョン不整合を疑う

環境構築で摩擦係数 90% を使い果たしたが、一度この「素のウィンドウ」さえ出せてしまえば、あとは WPF 時代に蓄積した C# の解析ロジックと XAML の知識を流し込むだけで爆速開発が可能になる。

ここからが本番だ。🤯