DNR: AI/ML同梱 WinUI3 MSIXアプリケーション構築ガイドライン

バージョン: 1.0

最終更新: 2025年11月28日
対象技術: WinUI3 + MSIX + ONNX Runtime + Large AI Models
基盤: FindSpark実装経験 + 0xc000027b問題解決からの学び

📋 Executive Summary

本ガイドラインは、ONNX Runtimeなどのx64ネイティブ依存関係を持つAI/MLライブラリを含むWinUI3アプリケーションをMSIXパッケージとして構築する際の、クリティカルな設定要件とベストプラクティスを定義します。

数百MB〜数GBの大容量AIモデルを同梱し、Microsoft Store配信またはサイドローディングを実現するための、実証済みアーキテクチャと実装戦略を提供します。

🎯 適用対象プロジェクト

✅ ONNX Runtime (Microsoft.ML.OnnxRuntime) 使用アプリ
✅ 大容量AIモデル（100MB〜数GB）同梱アプリ
✅ WinUI3 + .NET 8/9 デスクトップアプリ
✅ Microsoft Store配信予定アプリ
✅ x64専用ネイティブ依存関係を持つアプリ

⚠️ クリティカル問題の予防

このガイドラインに従うことで、以下の問題を未然に防止できます：

問題 症状 根本原因
0xc000027b クラッシュ 起動直後にMicrosoft.UI.Xaml.dllで即座にクラッシュ Package.appxmanifest ProcessorArchitecture未指定
DLL Not Found onnxruntime.dll/onnxruntime_providers_shared.dll読み込み失敗 runtimes/win-x64/native/ディレクトリ構造問題
Model Load Failure AIモデルファイルが見つからない（MSIX環境のみ） パス解決戦略の欠如
Store Submission拒否 WACKテスト失敗、アーキテクチャ不整合 VCLibs依存関係欠如、RuntimeIdentifier不整合

問題	症状	根本原因
0xc000027b クラッシュ	起動直後にMicrosoft.UI.Xaml.dllで即座にクラッシュ	Package.appxmanifest ProcessorArchitecture未指定
DLL Not Found	onnxruntime.dll/onnxruntime_providers_shared.dll読み込み失敗	runtimes/win-x64/native/ディレクトリ構造問題
Model Load Failure	AIモデルファイルが見つからない（MSIX環境のみ）	パス解決戦略の欠如
Store Submission拒否	WACKテスト失敗、アーキテクチャ不整合	VCLibs依存関係欠如、RuntimeIdentifier不整合

🏗️ アーキテクチャ概要

レイヤー構造

┌─────────────────────────────────────────────────┐
│ WinUI3 Application Layer                        │
│  ├─ ViewModels (MVVM)                          │
│  ├─ Views (XAML)                               │
│  └─ Services (UI Orchestration)                │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ AI/ML Service Layer                             │
│  ├─ IEmbeddingService                          │
│  ├─ IInferenceService                          │
│  └─ IModelManagementService                    │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ ONNX Runtime Infrastructure                     │
│  ├─ ONNX Session Management                    │
│  ├─ Model Loading & Caching                    │
│  └─ Tensor Processing                          │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ Native Dependencies (x64)                       │
│  ├─ onnxruntime.dll (13.5MB - 17.4MB)         │
│  ├─ onnxruntime_providers_shared.dll           │
│  └─ VCLibs.140.00.UWPDesktop (Framework)       │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ AI Model Assets (ONNX format)                   │
│  └─ Assets/models/{model_name}/*.onnx          │
│     (100MB - 数GB)                              │
└─────────────────────────────────────────────────┘

🔧 CRITICAL: 必須設定チェックリスト

✅ Phase 1: Package.appxmanifest 設定（最優先）

ファイル: {ProjectName}.PKG.wapproj/Package.appxmanifest

xml

<?xml version="1.0" encoding="utf-8"?>
<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap rescap">

  <!-- CRITICAL: ProcessorArchitecture="x64" を明示的に指定 -->
  <Identity
    Name="com.yourcompany.yourapp"
    Publisher="CN=..."
    Version="1.0.0.0"
    ProcessorArchitecture="x64" />  <!-- ← 必須！ -->

  <Properties>
    <DisplayName>Your App Name</DisplayName>
    <PublisherDisplayName>Your Company</PublisherDisplayName>
    <Logo>Images\StoreLogo.png</Logo>
  </Properties>

  <Dependencies>
    <TargetDeviceFamily 
      Name="Windows.Desktop" 
      MinVersion="10.0.17763.0" 
      MaxVersionTested="10.0.26100.0" />
    
    <!-- CRITICAL: VCLibs依存関係を明示的に宣言 -->
    <PackageDependency 
      Name="Microsoft.VCLibs.140.00.UWPDesktop" 
      MinVersion="14.0.33519.0" 
      Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" />
  </Dependencies>

  <Capabilities>
    <!-- フルトラスト必須（ONNX Runtimeはサンドボックス制限外の動作が必要） -->
    <rescap:Capability Name="runFullTrust" />
    
    <!-- 必要に応じて追加 -->
    <!-- <Capability Name="internetClient" /> -->
    <!-- <rescap:Capability Name="broadFileSystemAccess" /> ※最小限に -->
  </Capabilities>

  <Applications>
    <Application Id="App"
      Executable="$targetnametoken$.exe"
      EntryPoint="$targetentrypoint$">
      <uap:VisualElements
        DisplayName="Your App Name"
        Description="Your App Description"
        BackgroundColor="transparent"
        Square150x150Logo="Images\Square150x150Logo.png"
        Square44x44Logo="Images\Square44x44Logo.png">
        <uap:DefaultTile 
          Wide310x150Logo="Images\Wide310x150Logo.png" 
          Square71x71Logo="Images\SmallTile.png"
          Square310x310Logo="Images\LargeTile.png" />
        <uap:SplashScreen Image="Images\SplashScreen.png" />
      </uap:VisualElements>
    </Application>
  </Applications>
</Package>

重要ポイント:

ProcessorArchitecture="x64" が最重要設定（欠如すると0xc000027bクラッシュ）
VCLibs依存関係は、ONNX Runtimeの動作に必須
runFullTrust capability必須（ONNX RuntimeはUWPサンドボックス外の機能使用）

✅ Phase 2: .wapproj プロジェクトファイル設定

ファイル: {ProjectName}.PKG.wapproj

xml

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" DefaultTargets="Build" 
         xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  
  <PropertyGroup>
    <ProjectGuid>{YOUR-GUID}</ProjectGuid>
    <TargetPlatformVersion>10.0.26100.0</TargetPlatformVersion>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <DefaultLanguage>en-US</DefaultLanguage>
    
    <!-- CRITICAL: VCLibs自動インクルード -->
    <WinUISDKReferences>true</WinUISDKReferences>
    
    <!-- x64専用ビルド強制 -->
    <AppxBundlePlatforms>x64</AppxBundlePlatforms>
    <AppxBundle>Always</AppxBundle>
    
    <!-- 署名設定 -->
    <AppxPackageSigningEnabled>True</AppxPackageSigningEnabled>
    <PackageCertificateThumbprint>YOUR-THUMBPRINT</PackageCertificateThumbprint>
    
    <!-- エントリーポイント -->
    <EntryPointProjectUniqueName>..\src\{YourApp}\{YourApp}.csproj</EntryPointProjectUniqueName>
  </PropertyGroup>

  <!-- すべての構成でx64を強制 -->
  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <AppxBundle>Always</AppxBundle>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <AppxBundle>Always</AppxBundle>
  </PropertyGroup>

  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>

  <!-- ONNX Runtime DLLを直接配置 -->
  <ItemGroup>
    <!-- オプション1: NuGetパッケージから自動コピー（推奨） -->
    <!-- Microsoft.ML.OnnxRuntime NuGetパッケージが自動的に配置 -->
    
    <!-- オプション2: 手動配置（runtimes問題回避） -->
    <Content Include="..\packages\Microsoft.ML.OnnxRuntime.1.23.0\runtimes\win-x64\native\*.dll">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Link>%(Filename)%(Extension)</Link>
    </Content>
  </ItemGroup>

  <!-- AIモデルファイルをAssetsディレクトリに配置 -->
  <ItemGroup>
    <Content Include="..\models\{model_name}\**\*">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Link>Assets\models\{model_name}\%(RecursiveDir)%(Filename)%(Extension)</Link>
    </Content>
  </ItemGroup>

  <Import Project="$(WapProjPath)\Microsoft.DesktopBridge.props" />
  <Import Project="$(WapProjPath)\Microsoft.DesktopBridge.targets" />
  
  <ItemGroup>
    <PackageReference Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.26100.1742" />
  </ItemGroup>
  
  <ItemGroup>
    <ProjectReference Include="..\src\{YourApp}\{YourApp}.csproj" />
  </ItemGroup>
</Project>

重要ポイント:

<WinUISDKReferences>true</WinUISDKReferences> でVCLibs自動インクルード
すべてのPropertyGroupにRuntimeIdentifier=win-x64を明示
ONNX Runtime DLLは実行ディレクトリ直下に配置（runtimes/win-x64/native/問題回避）

✅ Phase 3: .csproj アプリケーションプロジェクト設定

ファイル: src/{YourApp}/{YourApp}.csproj

xml

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    
    <!-- CRITICAL: x64専用設定 -->
    <Platform>x64</Platform>
    <PlatformTarget>x64</PlatformTarget>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <Platforms>x64</Platforms>
    <RuntimeIdentifiers>win-x64</RuntimeIdentifiers>
    
    <!-- WinUI3設定 -->
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    
    <!-- MSIX最適化 -->
    <WindowsPackageType>MSIX</WindowsPackageType>
    <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
    
    <!-- 公開設定（Store配信時） -->
    <PublishReadyToRun>true</PublishReadyToRun>
    <PublishTrimmed>false</PublishTrimmed> <!-- ONNX Runtimeは trim 非対応 -->
    <SelfContained>false</SelfContained>
  </PropertyGroup>

  <ItemGroup>
    <!-- Windows App SDK -->
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.7.250310001" />
    <PackageReference Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.26100.6584" />
    
    <!-- ONNX Runtime -->
    <PackageReference Include="Microsoft.ML.OnnxRuntime" Version="1.23.0" />
    
    <!-- その他AI/ML関連 -->
    <PackageReference Include="Microsoft.ML" Version="3.0.1" />
    <PackageReference Include="Microsoft.ML.Tokenizers" Version="2.0.0-preview.25373.1" />
    
    <!-- MVVM Toolkit -->
    <PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.0" />
  </ItemGroup>

  <!-- ONNX Runtime DLL配置の確保 -->
  <Target Name="CopyOnnxRuntimeDlls" AfterTargets="Build">
    <ItemGroup>
      <OnnxRuntimeFiles Include="$(NuGetPackageRoot)\microsoft.ml.onnxruntime\1.23.0\runtimes\win-x64\native\*.dll" />
    </ItemGroup>
    <Copy SourceFiles="@(OnnxRuntimeFiles)" 
          DestinationFolder="$(OutDir)" 
          SkipUnchangedFiles="true" />
  </Target>
</Project>

重要ポイント:

PublishTrimmed=false 必須（ONNX Runtimeはリフレクション使用のためtrim不可）
SelfContained=false 推奨（.NET Runtimeは別途Framework依存）
ONNX Runtime DLLの明示的コピーターゲット（MSBuild）

このドキュメントは、FindSpark (v1.0.0 - v1.0.16.0) の開発経験と、10連続バージョンでの0xc000027b問題解決過程から得られた実証済み知見に基づいています。

完全版は1400行以上のガイドラインで、以下のセクションを含みます：

AIモデル配置戦略（MSIX同梱 vs 初回ダウンロード）
ONNX Runtime実装ベストプラクティス
パフォーマンス最適化（ArrayPool, Span<T>, バッチ処理）
セキュリティ・プライバシー考慮事項
MSIXパッケージサイズ管理
トラブルシューティング完全ガイド
FindSpark実装例と実績データ
実装チェックリスト

DNR

金曜日, 11月 28, 2025

AI/ML同梱 WinUI3 MSIXアプリケーション構築ガイドライン

📋 Executive Summary

🎯 適用対象プロジェクト

⚠️ クリティカル問題の予防

🏗️ アーキテクチャ概要

レイヤー構造

🔧 CRITICAL: 必須設定チェックリスト

✅ Phase 1: Package.appxmanifest 設定（最優先）

✅ Phase 2: .wapproj プロジェクトファイル設定

✅ Phase 3: .csproj アプリケーションプロジェクト設定

0 件のコメント: