umbraco-extension-template

Umbraco Extension Template

これは何ですか？

Umbraco Extension Template は、バックオフィス拡張機能を作成するための公式 .NET テンプレートです。TypeScript/Vite ツール、適切なフォルダー構造、拡張機能の開発に必要なすべての必須ファイルを備えた、事前構成済みのプロジェクト構造を提供します。すべての Umbraco バックオフィス拡張機能は、このテンプレートから始めるべきです。

ドキュメント

実装する前に、常に最新のドキュメントを取得してください。

• メインドキュメント: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/development-flow/umbraco-extension-template
• Development Flow: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/development-flow
• Foundation: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

前提条件

• .NET SDK 10.0 以降
• Node.js 24 以降

ワークフロー

0. バージョンガード: まず umbraco-version-guard を呼び出して、対象サイトの Umbraco メジャーバージョンがこれらのスキルが対象とするメジャーバージョンと一致することを確認します。一致しない場合は停止します。
1. テンプレートをインストール（初回のみ）: dotnet new install Umbraco.Templates
2. 拡張機能を作成: dotnet new umbraco-extension -n MyExtension
3. 依存関係をインストール: cd MyExtension/Client && npm install
4. 開発を開始: npm run watch
5. 本番用にビルド: npm run build

コマンド

テンプレートをインストール

dotnet new install Umbraco.Templates

新しい拡張機能を作成（基本）

dotnet new umbraco-extension -n MyExtension

新しい拡張機能を作成（サンプル付き）

dotnet new umbraco-extension -n MyExtension -ex

-ex フラグを指定すると、以下を含むサンプルコードが追加されます。

• サンプル API コントローラー
• Swagger API の登録
• サンプルダッシュボードコンポーネント
• 生成された API クライアント

プロジェクト構造

基本テンプレート

MyExtension/
├── MyExtension.csproj        # .NET project file
├── Constants.cs              # Extension constants
├── README.md                 # Setup instructions
└── Client/                   # TypeScript source
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    └── src/
        └── ...               # Your extension code

サンプル付き（-ex フラグ）

MyExtension/
├── MyExtension.csproj
├── Constants.cs
├── README.md
├── Composers/                # C# composers
│   └── SwaggerComposer.cs    # API documentation setup
├── Controllers/              # C# API controllers
│   └── MyExtensionController.cs
└── Client/
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    └── src/
        ├── api/              # Generated API client
        ├── dashboards/       # Example dashboard
        └── entrypoints/      # Extension entry point

開発コマンド

# Navigate to Client folder
cd MyExtension/Client

# Install dependencies
npm install

# Development with hot reload
npm run watch

# Production build
npm run build

# Type checking
npm run check

ビルドとデプロイ

拡張機能を公開

dotnet publish --configuration Release

NuGet パッケージを作成

dotnet pack --configuration Release

最小限の例

テンプレートを実行した後、Client/src/ に最初のマニフェストを追加します。

manifest.ts

export const manifests: Array<UmbExtensionManifest> = [
  {
    name: "My Extension Entrypoint",
    alias: "MyExtension.Entrypoint",
    type: "backofficeEntryPoint",
    js: () => import("./entrypoint.js"),
  },
];

entrypoint.ts

import type { UmbEntryPointOnInit } from "@umbraco-cms/backoffice/extension-api";

export const onInit: UmbEntryPointOnInit = (_host, _extensionRegistry) => {
  console.log("Extension loaded!");
};

重要: Umbraco インスタンスに拡張機能を追加

新しい拡張機能を作成した後、それをメインの Umbraco インスタンスへのプロジェクト参照として追加する必要があります。この手順を行わないと、拡張機能は読み込まれません。

参照スキル: umbraco-add-extension-reference

このスキルでは、新しい拡張機能の .csproj ファイルをメインの Umbraco プロジェクト（例: Umbraco-CMS.Skills.csproj）に <ProjectReference> として追加する方法を説明します。

関連スキル

拡張機能を作成した後は、これらのスキルを使用して機能を追加します。

• セクション: 参照スキル: umbraco-sections
• ダッシュボード: 参照スキル: umbraco-dashboard
• メニュー: 参照スキル: umbraco-menu
• ワークスペース: 参照スキル: umbraco-workspace
• ツリー: 参照スキル: umbraco-tree

動作するサンプルを含む完全な拡張機能のブループリントについては、以下を参照してください。

• 参照スキル: umbraco-backoffice

以上です！常に最新のドキュメントを取得し、テンプレートを使用してスキャフォールドし、プロジェクト参照を追加してから、必要に応じて拡張機能の種類を追加してください。