バージョン: 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不整合 |
🏗️ アーキテクチャ概要
レイヤー構造
┌─────────────────────────────────────────────────┐
│ 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の動作に必須
runFullTrustcapability必須（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実装例と実績データ
- 実装チェックリスト
