既知の問題のトラブルシューティング

  • [アーティクル]

この記事では、.NET マルチプラットフォーム アプリ UI (.NET MAUI) に関する既知の問題の一部と、それらを解決または回避する方法について説明します。 「.NET MAUI リポジトリ」にも、いくつかの既知の問題が詳しく説明されています。

.NET MAUI ワークロードが見つかりません

.NET MAUI ワークロードをインストールするには、次の 2 つのオプションがあります。

  1. Windows 上の Visual Studio では、各ワークロード パックの .msi ファイルをインストールできます。
  2. dotnet workload install コマンド。

Windows では、Visual Studio インストーラーを通じて .NET MAUI をインストールした後に dotnet workload install を実行すると、Visual Studio が .NET MAUI ワークロードを見つけられない状態に入る可能性があります。 .NET MAUI ワークロードをインストールするように指示するビルド エラーが表示され、ワークロードを修復または再インストールできない状態に入る可能性があります。 詳細については、GitHub 問題の「dotnet/sdk#22388」をご覧ください。

Windows

Windows でこの問題を解決するには、CLI を使用して .NET MAUI ワークロードをアンインストールし、コントロール パネルですべての .NET SDK をアンインストールし、Visual Studio で .NET MAUI ワークロードをアンインストールします。 これらのアンインストールは、次のプロセスで実行できます。

  1. dotnet workload install コマンドを使用したことがある場合は、dotnet workload uninstall maui を実行します。
  2. コントロール パネルからスタンドアロンの .NET SDK インストーラーをすべてアンインストールします。 これらのインストーラーは、Microsoft .NET SDK 6.0.300 に似た名前を持っています。
  3. Visual Studio のすべてのインスタンスで、.NET マルチプラットフォーム アプリ UI 開発および .NET デスクトップ開発 Visual Studio ワークロードをアンインストールします。

その後、次のコマンドを実行して、アンインストールする必要がある追加の .msi ファイルがあるかどうかを確認します。

reg query HKLM\SOFTWARE\Microsoft\Windows\currentversion\uninstall\ -s -f manifest

この reg query コマンドは、マシンにまだインストールされている次の .NET 6 以降の SDK を一覧表示します。

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\currentversion\uninstall\{EEC1BB5F-3391-43C2-810E-42D78ADF3140}
    InstallSource    REG_SZ    C:\ProgramData\Microsoft\VisualStudio\Packages\Microsoft.MacCatalyst.Manifest-6.0.300,version=125.179.40883,chip=x64,productarch=neutral\
    DisplayName    REG_SZ    Microsoft.NET.Sdk.MacCatalyst.Manifest-6.0.300

同様の出力を受け取った場合は、各パッケージの GUID をコピーし、msiexec コマンドを使用してパッケージをアンインストールする必要があります。

msiexec /x {EEC1BB5F-3391-43C2-810E-42D78ADF3140} /q IGNOREDEPENDENCIES=ALL

その後、結果が返されなくなるまで reg query コマンドを実行し続ける必要があります。 結果がなくなり、すべての .NET 6 以降の SDK がアンインストールされたら、次のフォルダーを削除することも検討する必要があります。

  • C:\Program Files\dotnet\sdk-manifests
  • C:\Program Files\dotnet\metadata
  • C:\Program Files\dotnet\packs
  • C:\Program Files\dotnet\library-packs
  • C:\Program Files\dotnet\template-packs
  • C:\Program Files\dotnet\sdk\6.* または C:\Program Files\dotnet\sdk\7.*
  • C:\Program Files\dotnet\host\fxr\6.* または C:\Program Files\dotnet\host\fxr\7.*

このプロセスの後、Visual Studio を使用するか、選択した .NET SDK バージョンをインストールして dotnet workload install maui コマンドを実行することで、.NET MAUI を再インストールできるようになります。

Mac

Visual Studio for Mac のインストーラーとアップデーターは、dotnet workload install コマンドを使用して .NET MAUI .pkg ファイルをインストールします。

.pkg ファイルはアンインストールできないため、Mac でワークロードをアンインストールする最も簡単な方法は、次のコマンドを実行して指定したフォルダーを削除することです。

rm -r ~/.dotnet/
sudo rm -r /usr/local/share/dotnet/

これらのコマンドを実行した後は、Visual Studio for Mac を使用するか、選択した .NET SDK バージョンをインストールして dotnet workload install maui コマンドを実行することで、.NET MAUI を再インストールできるようになります。

プラットフォームのバージョンが存在しない

プロジェクトをコンパイルしようとして次のテキストのようなエラーが表示された場合、Visual Studio が必要なワークロードを解決していない可能性があります。

プラットフォーム: net8.0-android、net8.0-ios、net8.0-maccatalyst が指定されている場合でも、1 つ以上のターゲット フレームワークにプラットフォーム バージョンが存在しません

この問題は通常、x86 および x64 SDK がインストールされており、x86 バージョンが使用されていることが原因で発生します。 Visual Studio と .NET MAUI には x64 .NET SDK が必要です。 オペレーティング システムにシステム全体の PATH 変数があり、x86 SDK を最初に解決している場合は、PATH 変数から x86 .NET SDK を削除するか、x64 .NET SDK を昇格させて最初に解決するように修正する必要があります。 x86 と x64 SDK 解像度のトラブルシューティングの詳細については、「Windows への .NET のインストール - トラブルシューティング」をご覧ください。

型または名前空間の 'Default' が存在しません

Contacts API を使用すると、iOS と macOS に関連する次のエラーが表示される場合があります。

The type or namespace name 'Default' does not exist in the namespace 'Contacts' (are you missing an assembly reference?)

iOS および macOS プラットフォームには、Contacts という名前のルート名前空間が含まれています。 この競合により、Contacts 型を含む Microsoft.Maui.ApplicationModel.Communication 名前空間を持つプラットフォームで競合が発生します。 Microsoft.Maui.ApplicationModel.Communication 名前空間は、プロジェクト ファイルの <ImplicitUsings> 設定によって自動的にインポートされます。

iOS および macOS 用にもコンパイルされるコードを作成するには、Contacts 型を完全修飾します。 または、コード ファイルの先頭に using ディレクティブを指定して、Communication 名前空間をマップします。

using Communication = Microsoft.Maui.ApplicationModel.Communication;

// Code that uses the namespace:
var contact = await Communication.Contacts.Default.PickContactAsync();

Xcode が現在インストールされていないか、見つかりませんでした

xcode-select --install を使用して Xcode コマンド ライン ツールをインストールした後、iOS または Mac Catalyst を対象とする .NET MAUI アプリをビルドしようとすると、Visual Studio for Mac に「Xcode が現在インストールされていないか、見つかりませんでした」というメッセージが表示されることがあります。 このシナリオでは、Xcode が App Store からインストールされていることも確認してください。 次に、Xcode を起動し、[Xcode] > [設定] > [ロケーション] > [コマンド ライン ツール] に移動し、ドロップダウンが空かどうかを確認します。 空の場合は、ドロップダウンを選択し、Xcode コマンド ライン ツールの場所を選択します。 次に、Xcode を閉じて、Visual Studio for Mac を再起動します。

有効な Xcode アプリ バンドルが見つかりませんでした

iOS または Mac Catalyst を対象とする .NET MAUI アプリをビルドしようとしたときに、「/Library/Developer/CommandLineTools で有効な Xcode アプリ バンドルが見つかりませんでした」というエラーが表示された場合は、「Xcodeが現在インストールされていないか、見つかりませんでした」で説明されているソリューションをお試しください。 それでも [Xcode] > [設定] > [ロケーション] > [コマンド ライン ツール] ドロップダウンにアクセスできない場合は、次のコマンドを実行します。

sudo xcode-select --reset

Xcode のバージョンが見つかりません

一部のシナリオでは、iOS または Mac Catalyst で .NET MAUI アプリをビルドすると、マシンにインストールされなくなった Xcode のバージョンを使用しようとすることがあります。 この場合、次のようなエラー メッセージが表示されます。

xcodebuild: error: SDK "/Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" cannot be located.
xcrun: error: sh -c '/Applications/Xcode_14.1.app/Contents/Developer/usr/bin/xcodebuild -sdk /Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk -find dsymutil 2> /dev/null' failed with exit code 16384: (null) (errno=Invalid argument)
xcrun: error: unable to find utility "dsymutil", not a developer tool or in PATH

アプリをビルドする際に、.NET iOS と .NET Mac Catalyst は次のプロセスを使用して、使用すべき Xcode のバージョンを決定します。

  1. MD_APPLE_SDK_ROOT 環境変数が設定されている場合は、その値を使用します。
  2. ~/Library/Preferences/Xamarin/Settings.plist ファイルが存在する場合は、その中に定義されている値を使用します。
  3. xcode-select -p の値を使用します。
  4. /Applications/Xcode.app を使用してください。

そのため、マシン上の Xcode の場所を指定する方法として、Xcode バージョンのパスに MD_APPLE_SDK_ROOT 環境変数を設定することをお勧めします。 詳細については、「Xcode の特定のバージョンを使用したビルド」を参照してください。

その後、マシンから安全に ~/Library/Preferences/Xamarin/Settings.plist を削除できます。

Blazor Hybrid アプリの問題を診断する

BlazorWebView には、Blazor Hybrid アプリの問題を診断するのに役立つ組み込みのログ記録があります。 このログ記録を有効にするには、次の 2 つの手順があります。

  1. 診断情報をログに記録するために、BlazorWebView と関連コンポーネントを有効にする。
  2. ログ出力を表示できる場所に書き込むようにロガーを構成します。

詳細については、「Blazor Hybrid アプリの問題の診断」をご覧ください。

イメージ パッケージを無効にする

トラブルシューティングの目的で、プロジェクト ファイルの最初の <PropertyGroup> ノードで $(EnableMauiImageProcessing) ビルド プロパティを false に設定することで、画像リソースのパッケージ化を無効にすることができます。

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

スプラッシュ スクリーン パッケージを無効にする

トラブルシューティングの目的で、プロジェクト ファイルの最初の <PropertyGroup> ノードで $(EnableSplashScreenProcessing) ビルド プロパティを false に設定することで、スプラッシュ スクリーン リソースの生成を無効にすることができます。

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

フォントのパッケージ化を無効にする

トラブルシューティングの目的で、プロジェクト ファイルの最初の <PropertyGroup> ノードで $(EnableMauiFontProcessing) ビルド プロパティを false に設定することで、フォント リソースのパッケージ化を無効にすることができます。

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

アセット ファイルのパッケージ化を無効にする

トラブルシューティングの目的で、プロジェクト ファイルの最初の <PropertyGroup> ノードで $(EnableMauiAssetProcessing) ビルド プロパティを false に設定することで、アセット ファイル リソースのパッケージ化を無効にすることができます。

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

空のスプラッシュ スクリーンを生成する

<MauiSplashScreen> 項目がなく、カスタム スプラッシュ スクリーンがない場合は、トラブルシューティングの目的で空のスプラッシュ スクリーンを生成できます。 これを実現するには、プロジェクト ファイルの最初の <PropertyGroup> ノードで $(EnableBlankMauiSplashScreen) ビルド プロパティを true に設定します。

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

空のスプラッシュ スクリーンを生成すると、カスタム スプラッシュ スクリーンがオーバーライドされ、アプリ ストアの拒否が発生します。 ただし、アプリの UI が正しいことを確認するためのテストでは、これは有用なアプローチになる可能性があります。

画像ファイル名の重複エラー

重複した画像ファイル名に関するビルド エラーが発生する場合があります。

1 つ以上の重複したファイル名が検出されました。 すべての画像出力ファイル名は一意である必要があります。

これは、MauiIcon および MauiImage 項目で発生します。.NET 8 以降 .NET MAUI が、重複する画像リソース ファイル名が存在しないことを確認するためです。

このエラーは、複数のフォルダーに同じファイル名がある場合や、特定の状況において、異なるフォルダー内に異なる拡張子を持つ同じファイル名がある場合に発生します。 たとえば、ビルド エラーは、Resources/Images/PNG/dotnet_bot.png にある PNG ファイルと、Resources/Images/SVG/dotnet_bot.svg にある SVG ファイルで発生します。SVG ファイルはビルド時に PNG ファイルに変換されるためです。

このエラーは、MauiImage 項目の Include 属性を使用してフォルダー内のすべての画像を含めた後、特定の画像ファイルも含めた場合にも発生します。

<MauiImage Include="Resources\Images\*" />
<MauiImage Include="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

このビルド エラーが発生した場合は、プロジェクト ファイルに重複する画像が含まれていないことを確認することで修正できます。 これを行うには、特定のファイルを参照する MauiIcon または MauiImage を、Include 属性の代わりに Update 属性を使用するように変更します。

<MauiImage Include="Resources\Images\*" />
<MauiImage Update="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

MSBuild 項目要素の属性の詳細については、「項目要素 (MSBuild): 属性と要素」をご覧ください。