umbraco-add-extension-reference

Umbraco インスタンスへの拡張機能参照の追加

これは何ですか？

新しい Umbraco バックオフィス拡張プロジェクトを作成した後、それをメインの Umbraco インスタンスの .csproj ファイルにプロジェクト参照として追加する必要があります。この参照がないと、Umbraco サイトの実行時に拡張機能が読み込まれません。

ソリューションファイル（.sln）が存在する場合、適切な IDE サポート（Visual Studio、Rider）のために、拡張機能をそれにも追加する必要があります。これは任意です。ソリューションに含めなくても拡張機能は動作します。

使用するタイミング

このスキルは次の後に使用します。

• dotnet new umbraco-extension で新しい拡張機能を作成した
• 拡張プロジェクトをソリューションに移動またはコピーした
• umbraco-backoffice ブループリントから新しい拡張機能をセットアップした

ワークフロー

ステップ 1: メインの Umbraco プロジェクトを見つける

メインの Umbraco インスタンスの .csproj ファイルは動的に検出する必要があります。次の条件で検索します。

# Find all .csproj files
Glob: **/*.csproj

# Then search for the one containing Umbraco.Cms package reference
Grep: Umbraco\.Cms" Version  (in *.csproj files)

メインの Umbraco プロジェクトには次の特徴があります。

• <PackageReference Include="Umbraco.Cms" ...> エントリがある
• SDK が Microsoft.NET.Sdk.Web である
• 通常はソリューションのルートまたは専用フォルダーに配置されている

ステップ 2: プロジェクトファイルを読む

見つかったら、.csproj ファイルを読んで構造を理解し、<ProjectReference> エントリがどこにあるかを確認します。

ステップ 3: 相対パスを計算する

メインプロジェクトのディレクトリから新しい拡張機能の .csproj ファイルへの相対パスを計算します。

• スラッシュ / を使用します（クロスプラットフォーム互換）
• パスはメインの .csproj ファイルのディレクトリからの相対パスです

パスの例:

拡張機能の場所	相対パスの例
兄弟フォルダー	../MyExtension/MyExtension.csproj
サブフォルダー	./extensions/MyExtension/MyExtension.csproj
スキルフォルダー	../.claude/skills/.../MyExtension.csproj

ステップ 4: ProjectReference を追加する

<ItemGroup> に <ProjectReference> エントリを追加します。

<ItemGroup>
  
  <ProjectReference Include="../ExistingExtension/ExistingExtension.csproj" />
  
  <ProjectReference Include="../NewExtension/NewExtension.csproj" />
</ItemGroup>

すでに <ProjectReference> エントリを含む <ItemGroup> がある場合は、それに追加します。そうでない場合は、新しい <ItemGroup> を作成します。

ステップ 5: 拡張機能をソリューションファイルに追加する（任意）

ソリューションファイル（.sln）が存在する場合、適切な IDE サポートのために、拡張プロジェクトをそれに追加する必要があります。このステップは任意です。すべてのプロジェクトがソリューションファイルを使用するわけではありません。

ソリューションファイルを見つける:

# Find any .sln files in the workspace
Glob: **/*.sln

対処すべきシナリオ:

シナリオ	対応
.sln ファイルが見つからない	このステップをスキップします - 必須ではありません
.sln ファイルが 1 つ見つかった	それに拡張機能を追加します
.sln ファイルが複数見つかった	どのソリューションを使用するかユーザーに確認します
拡張機能がすでにソリューションにある	dotnet sln add がこれを報告します - 無視して問題ありません

拡張プロジェクトをソリューションに追加する:

dotnet sln <path-to-solution.sln> add <path-to-extension.csproj>

例:

# If solution is at ./MySite/MySite.sln and extension is at ./MyExtension/MyExtension.csproj
dotnet sln ./MySite/MySite.sln add ./MyExtension/MyExtension.csproj

ソリューションファイルが存在する場合、拡張機能を追加することで次のことが保証されます。

• 拡張機能が Visual Studio/Rider のソリューションエクスプローラーに表示される
• ソリューションをビルドすると拡張機能がビルドされる
• 「定義へ移動」などの IDE 機能がプロジェクト間で動作する

例

追加前

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Umbraco.Cms" Version="18.0.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="../BlankExtension/BlankExtension.csproj" />
  </ItemGroup>
</Project>

「MyNewExtension」を追加した後

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Umbraco.Cms" Version="18.0.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="../BlankExtension/BlankExtension.csproj" />
    <ProjectReference Include="../MyNewExtension/MyNewExtension.csproj" />
  </ItemGroup>
</Project>

実装チェックリスト

1. Glob + Grep を使用して Umbraco.Cms を検索し、メインの Umbraco プロジェクトを検出する
2. メインプロジェクトファイルを読み、構造を理解する
3. メインプロジェクトから新しい拡張機能への相対パスを計算する
4. 計算したパスに拡張機能の .csproj ファイルが存在することを確認する
5. メインプロジェクトファイルを編集して <ProjectReference> を追加する
6. Glob を使用してソリューションファイル（.sln）を確認する
7. 見つかった場合、dotnet sln add を使用して拡張機能をソリューションに追加する
8. dotnet build での検証をユーザーに依頼する

検証

参照を追加した後、ユーザーは次の方法で検証する必要があります。

1. ソリューションをビルドする: dotnet build
2. Umbraco インスタンスを実行する: dotnet run
3. バックオフィスが拡張機能を読み込むことを確認する

トラブルシューティング

ビルドエラー: プロジェクトが見つかりません

• 相対パスが正しいことを確認してください
• 拡張機能の .csproj ファイルが存在することを確認してください
• パスにスラッシュ（/）が使われていることを確認してください

拡張機能が読み込まれない

• 拡張機能がビルドされていることを確認してください: cd ExtensionName/Client && npm run build
• 拡張機能の wwwroot フォルダーに umbraco-package.json が存在することを確認してください
• ブラウザーコンソールにエラーがないか確認してください

複数の Umbraco プロジェクトが見つかりました

• Umbraco.Cms を含む .csproj ファイルが複数ある場合は、どれがメインインスタンスかをユーザーに確認してください
• メインインスタンスは通常、Microsoft.NET.Sdk.Web SDK を持ち、Program.cs または Startup.cs があるものです

ソリューションファイルが見つかりません

• これは問題ありません - ソリューションファイルは省略可能です
• 拡張機能が動作するには .csproj 内の <ProjectReference> で十分です
• ソリューションの手順をスキップし、検証に進んでください

複数のソリューションファイルが見つかりました

• どのソリューションに拡張機能を追加したいかをユーザーに確認してください
• 一般的なシナリオ: IDE ごとにソリューションを分けている、テスト用ソリューションなど

拡張機能がすでにソリューションに含まれています

• dotnet sln add はプロジェクトがすでに追加されていると報告します - これは無視して問題ありません
• このコマンドは冪等であり、重複は作成されません