Blazor で MainLayout.razor に <CartMenu /> のようなコンポーネントを置いたのに表示されず、RZ10012 の警告が出る――これは多くの場合「その .razor が Razor コンポーネントとして認識されていない」か「名前空間解決が崩れて未知のタグ扱い」になっている状態です。最短で直す手順から再発防止まで整理します。
症状：<CartMenu /> が表示されず RZ10012 が出るときに起きていること
Blazor のレイアウト（例：MainLayout.razor）に <CartMenu /> を追加したのに、画面には何も出ず、エディタ上で RZ10012 の緑の波線が付くことがあります。さらに CartMenu.razor 側では @inject や @using が効いていないように見え、IShoppingCartService などが解決できず「エラーっぽい」状態になります。
この現象の本質はシンプルで、Razor が CartMenu を Blazor コンポーネントとして解決できていない（= 未知のタグとして扱っている）ことです。未知のタグ扱いになると、Razor はそれを「HTML のカスタム要素」として出力するだけなので、自己終了タグ <cartmenu /> は見た目上ほぼ何も表示されません。結果として「動いているのに表示されない」状態に見えます。
| よくある見え方 | 起きていること | 最初に試す対処 |
|---|---|---|
RZ10012（緑の警告）で <CartMenu /> が波線 | コンポーネント型が見つからず、未知のタグ扱い | Build Action を Content にして Clean/Rebuild |
CartMenu.razor で @inject や型が赤く見える | .razor が Razor として処理されていない／デザイン時解析が壊れている | .vs / bin / obj を削除してキャッシュをリセット |
@using ...Services.Contracts を入れたのに解決しない | その _Imports.razor が適用範囲外、または名前空間が変わっている | MainLayout.razor に一時的に @using を追加して切り分け |
RZ10012 の意味：Blazor が「そのコンポーネントを知らない」と言っている
RZ10012 は、ざっくり言うと「そのタグ名に対応するコンポーネント（型）が見つからない」状態で出やすい診断です。原因は大きく 2 系統に分かれます。
- ファイル認識系（認識が壊れている）：
CartMenu.razorが Razor コンポーネントとしてプロジェクトに取り込まれていない、または IDE のキャッシュが壊れて Razor の解析がズレている。 - 名前空間解決系（見えていない）：コンポーネントは存在するが、
@using（または@namespace）の関係でMainLayout.razorから型解決できていない。
現場感としては、最初に疑うべきは ファイル認識系 です。理由は、ここが壊れていると @inject なども巻き込んで「全体が崩れる」ためです。
最優先で試す：Build Action を Content にして Clean / Rebuild
一番効くことが多いのが、対象コンポーネント（例：CartMenu.razor）の Build Action（ビルド アクション） を見直す手順です。チュートリアルやコピペでファイルを追加したときに、稀にプロジェクト側の扱いが崩れることがあります。
手順（Visual Studio）
CartMenu.razorを右クリック → プロパティ- Build Action を Content に変更
- ソリューション／プロジェクトを Clean（クリーン） → Rebuild（リビルド）
- まだ残る場合は Visual Studio を再起動 してからビルド
ここが直ると、以下が同時に改善することが多いです。
MainLayout.razorの<CartMenu />がコンポーネントとして色付く（または IntelliSense が効く）- RZ10012 の波線が消える
CartMenu.razorで@inject IShoppingCartServiceなどの型が解決できる
なぜ Build Action が効くのか（理解しておくと再発に強い）
Blazor の .razor は「ビルド時に Razor エンジンで解析され、C# コードに生成される」ことで初めてコンポーネントとして動きます。Build Action が期待と違う状態だと、そのファイルは 解析対象から外れ、Razor ディレクティブ（@inject や @code）も正しく扱われなくなります。結果として IDE も「未知の構文」として扱い、RZ10012 のような診断が連鎖します。
再発・突発の RZ10012 に効く：.vs / bin / obj の削除（キャッシュ掃除）
リネームや移動、Git のブランチ切り替え後などに、IDE のキャッシュが壊れてコンポーネント探索がおかしくなることがあります。その場合は「キャッシュ掃除」が最短です。
基本のキャッシュ掃除手順
- Visual Studio を終了
- ソリューション直下の
.vsフォルダを削除 - Visual Studio を起動し直す
- Rebuild（リビルド）
それでも改善しない場合は、ビルド生成物側の整合も取り直します。
- プロジェクト（またはソリューション）配下の
bin/objフォルダを削除 - もう一度 Rebuild
| 削除対象 | 狙い | 向いている状況 |
|---|---|---|
.vs | IDE の解析・補完・キャッシュの再生成 | 「急に」RZ10012 が出た／エディタ上だけ赤い |
bin / obj | 生成コード・中間成果物の再生成 | 移動・リネーム後に直らない／ビルド結果が怪しい |
名前空間と _Imports.razor の確認：@using が効いていない理由を潰す
RZ10012 は「そのタグ（コンポーネント）が見つからない」ので、名前空間が見えていないと簡単に起きます。特に _Imports.razor は配置場所によって適用範囲が変わるため、「入れたはずなのに効かない」原因になりがちです。
まずは最短で切り分け：MainLayout.razor に一時的に @using を書く
_Imports.razor の影響範囲が怪しいときは、まず MainLayout.razor の先頭に一時的に @using を追加して、タグが解決できるかを確認します。
@using ShopOnline.Web.Pages
@using ShopOnline.Web.Components
これで RZ10012 が消えるなら、コンポーネント自体は存在するので、次は _Imports.razor の配置や内容の問題に絞れます。
_Imports.razor の適用範囲を整理する（重要）
_Imports.razor は「そのファイルが置かれたフォルダと、その配下のフォルダ」に適用されます。つまり、上位フォルダに置かないと下位に効きません。
| _Imports.razor の場所 | 適用される範囲 | よくある落とし穴 |
|---|---|---|
| プロジェクト直下（推奨） | 全ての Razor ファイル | 複数プロジェクトがあると、別プロジェクトの _Imports と混同しやすい |
Pages フォルダ | Pages 以下の Razor | Shared や Layouts の Razor には効かない |
Shared フォルダ | Shared 以下の Razor | MainLayout.razor が別フォルダだと効かない |
コンポーネントの既定名前空間は「フォルダ構成」で変わる
Blazor のコンポーネントは、一般的に「プロジェクトの既定ルート名前空間 + フォルダ名」で名前空間が決まります。たとえばプロジェクト名が ShopOnline.Web の場合、配置場所によって次のようになります。
| ファイルの配置 | 想定される名前空間（例） | レイアウトから呼ぶために必要になりやすい @using |
|---|---|---|
/Pages/CartMenu.razor | ShopOnline.Web.Pages | @using ShopOnline.Web.Pages |
/Shared/CartMenu.razor | ShopOnline.Web.Shared | @using ShopOnline.Web.Shared |
/Components/CartMenu.razor | ShopOnline.Web.Components | @using ShopOnline.Web.Components |
「@using ...Services.Contracts は入っているのに、CartMenu が見つからない」という場合、サービスの using ではなくコンポーネント自身の using が足りていないパターンが多いです。まずは CartMenu.razor の配置フォルダから、どの名前空間にいるかを推測し、@using を追加してみてください。
@namespace ディレクティブで想定外の名前空間になっていないか
プロジェクトによっては _Imports.razor や特定フォルダ配下に @namespace が書かれていることがあります。@namespace はその配下の Razor の名前空間を上書きするため、チーム開発やテンプレート差分で知らないうちに別の名前空間にいることが起きます。
「フォルダから推測した @using を入れても直らない」場合は、CartMenu.razor の近く（同じフォルダ階層）にある _Imports.razor を探し、@namespace が無いかを確認してください。
注入（@inject）がエラーっぽく見えるときのポイント
CartMenu.razor で次のような注入が赤く見える場合、原因は 2 つに絞られます。
- 本当に型が見えていない：
IShoppingCartServiceの名前空間が@usingされていない、または参照プロジェクトが追加されていない。 - .razor 自体が Razor として扱われていない：Build Action やキャッシュ破損で、Razor の解析が止まっている。
前者の切り分けは「型名を完全修飾で書く」方法が手堅いです。
@inject ShopOnline.Web.Services.Contracts.IShoppingCartService ShoppingCartService
完全修飾で直るなら、@using ShopOnline.Web.Services.Contracts の適用範囲や記述場所を見直す方向に進めます。完全修飾でも直らない／Razor 全体が変なら、まずは前述の Build Action とキャッシュ掃除を優先してください。
移動・リネーム後に多発するパターン：名前空間の変化と「参照できているはず」の崩壊
RZ10012 が「昨日まで出ていなかったのに急に出た」場合、次の変更が入っていないかを振り返ると原因に直結します。
CartMenu.razorを別フォルダに移動した- フォルダ名をリネームした（= 既定名前空間が変わる）
_Imports.razorを移動した／複数作ってしまった- Git でブランチを切り替え、
objが古い生成物のままになった
特に「フォルダ名の変更」は、見た目以上に影響が大きいです。例として、/Components を /Component に変えるだけで、既定名前空間が ...Components から ...Component に変わり、従来の @using が効かなくなります。RZ10012 はその結果として出ます。
「どの @using を入れればいいか」最短で決める方法
迷ったら、次の 3 ステップで機械的に決めるのが早いです。
CartMenu.razorを開き、同じフォルダ階層に_Imports.razorがあるか確認（@namespaceがあれば最優先で把握）- 無ければ「プロジェクトの既定名前空間 + フォルダ」を仮置きで推測し、
MainLayout.razorに@usingを一時追加 - 解決したら、その
@usingを適切な_Imports.razor（できればプロジェクト直下）に移す
VS Code 環境での回避策：.razor.cs を作って partial class + ComponentBase
Visual Studio ではなく VS Code を中心に開発している場合や、.NET 8 世代で Razor のデザイン時解析が不安定なとき、コードビハインド（.razor.cs）を追加して明示的にコンポーネントとして成立させると認識が改善することがあります。これは根本修正というより「ツールが生成コードを拾いやすい形に寄せる」回避策です。
例：CartMenu.razor と同じ場所に CartMenu.razor.cs を追加します。
using Microsoft.AspNetCore.Components;
using ShopOnline.Web.Services.Contracts;
namespace ShopOnline.Web.Components;
public partial class CartMenu : ComponentBase
{
[Inject] public IShoppingCartService ShoppingCartService { get; set; } = default!;
} CartMenu.razor 本体はマークアップ中心にし、ロジックは .razor.cs に寄せると、型解決と IntelliSense の安定度が上がることがあります。
それでも直らないときの最終チェック：csproj・参照・ワークロード
ここまでを試しても RZ10012 が消えない場合、プロジェクト設定側で Razor の取り込みが妨げられている可能性があります。頻度は高くありませんが、ハマると時間を溶かすので、チェック項目を表にまとめます。
| チェック項目 | 確認する理由 | 見る場所／対処 |
|---|---|---|
| .razor ファイルがプロジェクトに「含まれている」 | 除外されているとビルド対象にならない | ソリューション エクスプローラーでグレー表示でないか確認（除外なら「プロジェクトに含める」） |
.csproj で .razor を Remove していない | カスタム ItemGroup で誤って除外されることがある | <Content Remove="**\\*.razor" /> のような記述が無いか検索 |
| 参照プロジェクト／NuGet の欠落 | IShoppingCartService が別プロジェクトなら参照が必須 | 依存関係に該当プロジェクト／パッケージがあるか確認 |
| Visual Studio のワークロード | ASP.NET と Web 開発が不完全だと Razor が不安定になり得る | Visual Studio Installer で「ASP.NET と Web 開発」を確認 |
| SDK の差分 | チーム内で SDK がズレると生成物が不整合になりやすい | global.json の有無と指定 SDK バージョンを確認 |
ビルドは通るのに表示されない場合は「HTML 要素扱い」を疑う
RZ10012 が出ているのにアプリが起動するケースでは、前述のとおり <CartMenu /> がコンポーネントではなく <cartmenu /> という HTML 要素として出力されている可能性が高いです。ブラウザの開発者ツールで要素を確認し、<cartmenu> のようなタグがそのまま出ていれば「コンポーネント未解決」が確定します。
再発防止：RZ10012 を起こしにくくする運用ルール
最後に、同じプロジェクトで RZ10012 が断続的に出るときに効く、実務寄りのルールをまとめます。
- _Imports.razor は原則プロジェクト直下に 1 つ：フォルダごとに増やすほど「効いている／いない」の判断が難しくなります。
- コンポーネント用フォルダを決める：例として
/Componentsに統一すると、必要な@usingが固定化されます。 - 移動・リネーム後は Clean/Rebuild を癖にする：生成物（
obj）が古いまま残ると、Razor のデザイン時解析がズレやすいです。 - 「とりあえず MainLayout に @using」で切り分け：原因が名前空間かキャッシュかを短時間で判定できます。
- Visual Studio を最新の安定版に保つ：Razor/Blazor は IDE 依存の不具合の影響を受けやすく、更新で改善することがあります。
よくある質問（詰まりポイントの最終確認）
_Imports.razor に @using を書いたのに効かないのはなぜ？
ほとんどは「_Imports.razor の置き場所が適用範囲外」か「同名の _Imports.razor が複数あって期待と違う方が効いている」です。まずは MainLayout.razor に一時的に @using を書いて解決するかで切り分けるのが早いです。
Build Action を Content にしたのに直らない…次は？
.vs / bin / obj を消してから Rebuild してください。特に「フォルダ移動」「リネーム」「ブランチ切り替え」の直後は、生成物が残っているだけで再現します。
CartMenu 側の @inject が赤いのに、実行すると動くことがあるのはなぜ？
IDE のデザイン時解析（エディタの言語サービス）が壊れていると、エディタ上は赤いのに、実際のビルドでは解決できて動くことがあります。この場合もキャッシュ掃除が効きます。逆に、実行時に動かないなら本当に参照が足りていない可能性が高いので、完全修飾での注入や参照設定を確認してください。
まとめ：RZ10012 は「コンポーネント未解決」なので、認識と名前空間を順番に潰す
Blazor の RZ10012 は、コンポーネントが「存在しない」のではなく、見えていない／認識されていないことで起きるのが大半です。最短で直すなら、まず Build Action を Content → Clean/Rebuild、次に .vs / bin / obj の削除、最後に _Imports.razor と名前空間の順に確認すると、迷子にならずに解決できます。
コメント