创建插件

使用 Fastdotnet.Plugin.CLI 工具可以快速生成插件项目骨架，包含完整的后端和前端结构。

---

🛠️ 安装 CLI 工具

从 NuGet 安装（推荐）

dotnet tool install -g Fastdotnet.Plugin.CLI

验证安装

fd-plugin --version

应该输出版本号，例如：1.0.0

更新工具

重要提示：为确保创建的插件与最新版本的 Fastdotnet 框架兼容，建议在使用前始终更新 CLI 工具到最新版本。

dotnet tool update -g Fastdotnet.Plugin.CLI

为什么需要更新？

• 🔄 框架升级后，插件模板可能发生变化
• 🐛 修复已知的 Bug 和问题
• ✨ 新增功能和改进
• 🔒 安全性更新

检查当前版本：

fd-plugin --version

查看最新版本： 访问 NuGet 包页面 查看最新版本号。

卸载工具

dotnet tool uninstall -g Fastdotnet.Plugin.CLI

---

🚀 创建插件项目

⚠️ 重要提示：在创建插件之前，请确保 CLI 工具已更新到最新版本，以保证生成的插件与当前 Fastdotnet 框架版本兼容。

dotnet tool update -g Fastdotnet.Plugin.CLI
fd-plugin --version  # 检查版本

CLI 工具提供两种创建方式：交互式模式和命令行模式。

方式一：交互式模式（推荐新手）

fd-plugin

程序会引导你完成配置：

交互式插件项目创建向导

插件名称（英文，用于命名空间，例如：MyPlugin）: MyPlugin
插件显示名称（中文，例如：我的插件）: 我的插件
官网申请的 PluginId: 12345678901234567
插件描述: 这是一个示例插件
输出目录: .
是否包含前端项目？ Yes
是否生成 .sln 解决方案文件？ No

参数说明：

• 插件名称: 英文名称，用于 C# 命名空间（PascalCase）
• 显示名称: 中文名称，用于界面显示
• PluginId: 从官网申请的唯一标识（必需）
• 插件描述: 简要描述插件功能
• 输出目录: 项目生成的位置（默认当前目录）
• 包含前端: 是否生成 Admin 和 App 两个前端项目
• 生成 .sln: 是否生成 Visual Studio 解决方案文件（默认不生成）

方式二：命令行模式

fd-plugin create \
  --name MyPlugin \
  --plugin-id 12345678901234567 \
  --display-name "我的插件" \
  --description "这是一个示例插件" \
  --output ./plugins \
  --include-frontend \
  --include-sln false

命令行参数：

参数	简写	说明	必需
--name	-n	插件名称	✅
--plugin-id	-p	Plugin ID	✅
--display-name	-d	显示名称	❌
--description	-desc	插件描述	❌
--output	-o	输出目录	❌ (默认: .)
--include-frontend	-f	包含前端	❌ (默认: true)
--include-sln	-sln	生成 .sln	❌ (默认: false)

---

📁 生成的项目结构

执行命令后，会生成以下结构：

MyPlugin/
├── Backend/                    # 后端项目
│   ├── MyPlugin.csproj         # 项目文件
│   ├── MyPluginPlugin.cs       # 插件入口类
│   ├── plugin.json             # 插件元数据
│   ├── Controllers/            # API 控制器
│   │   └── SampleController.cs # 示例控制器
│   ├── Dto/                    # 数据传输对象
│   ├── Initializers/           # 初始化器
│   │   └── FdMenuConfigInitializer.cs  # 菜单配置
│   └── Properties/
│       └── launchSettings.json
│
├── Frontend/                   # 前端项目（如果选择包含）
│   ├── MyPlugin.Admin/         # 管理端
│   │   ├── src/
│   │   │   ├── views/          # 页面组件
│   │   │   ├── router/         # 路由配置
│   │   │   └── main.ts         # 入口文件
│   │   ├── vite.config.ts      # Vite 配置
│   │   ├── micro-index.html    # 微前端入口
│   │   └── package.json
│   │
│   └── MyPlugin.App/           # 应用端
│       ├── src/
│       ├── vite.config.ts
│       ├── micro-index.html
│       └── package.json
│
└── publish/                    # 发布目录（构建后生成）
    └── {PluginId}/
        ├── dependencies/       # 后端 DLL
        ├── wwwroot/
        │   ├── admin/          # 管理端静态资源
        │   └── app/            # 应用端静态资源
        └── plugin.json

---

🔍 关键文件说明

1. plugin.json

插件的元数据文件，位于 Backend/plugin.json：

{
  "PluginId": "12345678901234567",
  "Name": "MyPlugin",
  "DisplayName": "我的插件",
  "Version": "1.0.0",
  "Description": "这是一个示例插件",
  "Author": "Your Name",
  "Website": "",
  "MinHostVersion": "1.0.0",
  "Enabled": true
}

重要提示：

• PluginId 必须与从官网申请的一致
• Version 遵循语义化版本规范
• 修改后需要重新构建插件

2. MyPluginPlugin.cs

插件的入口类，继承自 PluginBase：

using Fastdotnet.Plugin.Contracts;

namespace MyPlugin
{
    public class MyPluginPlugin : PluginBase
    {
        public override string PluginId => "12345678901234567";
        
        public override string Name => "MyPlugin";
        
        public override string Version => "1.0.0";
        
        protected override async Task OnInitializeAsync(IServiceProvider serviceProvider)
        {
            // 插件初始化逻辑
            await base.OnInitializeAsync(serviceProvider);
        }
        
        protected override async Task OnStartAsync()
        {
            // 插件启动逻辑
            await base.OnStartAsync();
        }
        
        public override void ConfigureServices(ContainerBuilder builder)
        {
            // 注册服务
            base.ConfigureServices(builder);
        }
    }
}

生命周期方法：

• OnInitializeAsync: 插件加载时调用，用于初始化
• OnStartAsync: 插件启动时调用
• ConfigureServices: 注册依赖注入服务

3. vite.config.ts

前端的 Vite 配置文件，位于 Frontend/MyPlugin.Admin/vite.config.ts：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  },
  server: {
    port: 8099,  // 开发服务器端口
    cors: true
  },
  build: {
    outDir: '../../publish/{PluginId}/wwwroot/admin',  // 构建输出目录
    emptyOutDir: true
  }
})

重要配置：

• server.port: 开发时的端口
• build.outDir: 构建产物输出到 publish 目录

---

⚙️ 初始配置

1. 获取 Plugin ID

在开始开发之前，你需要从 Fastdotnet 官网申请唯一的 Plugin ID：

1. 访问 https://fastdotnet.top/marketplace
2. 注册/登录开发者账号
3. 进入"开发者中心"
4. 申请新的 Plugin ID
5. 记录 ID 并填入 plugin.json

2. 配置数据库连接

如果插件需要访问数据库，编辑 appsettings.json（如果需要）：

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=Fastdotnet;..."
  }
}

注意: 大多数情况下，插件会使用主程序的数据库连接，无需单独配置。

3. 配置前端代理

如果需要跨域访问后端 API，配置 vite.config.ts：

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:18889',
        changeOrigin: true
      }
    }
  }
})

---

🎯 下一步

项目创建完成后，你可以：

1. 打开项目

   cd MyPlugin
   code .  # VS Code
   # 或
   start MyPlugin.sln  # Visual Studio（如果生成了 .sln）

2. 恢复依赖

   # 后端
   cd Backend
   dotnet restore
   
   # 前端（如果包含）
   cd ../Frontend/MyPlugin.Admin
   pnpm install
   
   cd ../MyPlugin.App
   pnpm install

3. 开始开发

   • 后端：添加控制器、服务、数据模型
   • 前端：开发页面、组件、路由

详见：

• 后端开发
• 前端开发

---

💡 常见问题

Q: 为什么要及时更新 CLI 工具？

A: Fastdotnet 框架会不断更新，插件模板也会随之变化。使用最新版本的 CLI 工具可以确保：

• ✅ 生成的插件与当前框架版本完全兼容
• ✅ 使用最新的最佳实践和代码规范
• ✅ 避免已知的 Bug 和问题
• ✅ 获得新功能和改进

建议：每次创建新插件前，先运行 dotnet tool update -g Fastdotnet.Plugin.CLI。

Q: Plugin ID 格式有什么要求？

A: Plugin ID 应该是小写字母、数字和连字符的组合，例如：my-plugin-123。但实际使用时，官网会分配一个数字 ID。

Q: 可以不包含前端项目吗？

A: 可以。在创建时使用 --include-frontend false 参数，或者在交互模式下选择"No"。

Q: 为什么默认不生成 .sln 文件？

A: 为了保持项目简洁。如果需要，可以在创建时指定 --include-sln true，或手动在 Visual Studio 中创建。

Q: 如何修改已创建项目的 Plugin ID？

A:

1. 修改 Backend/plugin.json 中的 PluginId
2. 修改 Backend/MyPluginPlugin.cs 中的 PluginId 属性
3. 重新构建项目

Q: 前端构建后文件在哪里？

A: 构建产物会自动输出到 publish/{PluginId}/wwwroot/admin/ 和 publish/{PluginId}/wwwroot/app/ 目录。

---

🔗 相关链接

• 插件概述
• 后端开发
• 前端开发
• Fastdotnet.Plugin.CLI
• 插件商城