文档插件集成部署指南

大约 3 分钟约 949 字

文档插件集成部署指南

本文档合并 DLL 引用、NuGet 包和前端集成说明。开发环境优先源码引用；内部分发可用 DLL；多项目生产分发建议使用 NuGet 包。

前置条件

后端项目已引用 Admin.NET.Core。
.NET SDK 支持插件目标框架：net8.0 或 net10.0。
数据库配置开启表初始化和增量表更新。
需要初始化菜单时开启种子数据初始化和增量种子。
前端项目包含 Web/src/views/document/ 和 Web/src/api-services/document/。
预览功能需要安装 @vue-office/docx、@vue-office/excel、@vue-office/pdf、md-editor-v3。

源码引用

适用于开发和联调。

Admin.NET/Plugins/Admin.NET.Plugin.Document/

在目标后端项目 .csproj 中添加项目引用：

<ItemGroup>
  <ProjectReference Include="..\Plugins\Admin.NET.Plugin.Document\Admin.NET.Plugin.Document.csproj" />
</ItemGroup>

确认插件项目会复制配置文件：

<ItemGroup>
  <None Update="Configuration\**">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

启动后检查 Swagger 中是否出现 Document 分组。

DLL 引用

适用于内部交付或不希望暴露源码的部署。

打包

在插件目录执行：

dotnet build Admin.NET.Plugin.Document.csproj -c Release

按目标框架从 bin/Release/net8.0/ 或 bin/Release/net10.0/ 取出：

Admin.NET.Plugin.Document.dll
Admin.NET.Plugin.Document.xml
Admin.NET.Plugin.Document.pdb   可选，调试用

同时带上：

Configuration/Document.json

如果后续启用独立资源文件，也需要按同级 Resources/ 目录一起交付。

集成

推荐目录结构：

YourProject/
└── Plugins/
    └── Admin.NET.Plugin.Document/
        ├── Admin.NET.Plugin.Document.dll
        ├── Admin.NET.Plugin.Document.xml
        └── Configuration/
            └── Document.json

在目标项目 .csproj 中添加：

<ItemGroup>
  <Reference Include="Admin.NET.Plugin.Document">
    <HintPath>$(MSBuildProjectDirectory)\Plugins\Admin.NET.Plugin.Document\Admin.NET.Plugin.Document.dll</HintPath>
    <Private>True</Private>
    <CopyLocal>True</CopyLocal>
  </Reference>
</ItemGroup>

<ItemGroup>
  <None Update="Plugins\Admin.NET.Plugin.Document\Configuration\**">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

如遇 MSB3245 找不到程序集，优先检查：

HintPath 是否相对于 .csproj 所在目录。
DLL 是否在 Plugins\Admin.NET.Plugin.Document\ 下。
目标框架是否匹配。
清理 bin、obj 后重新构建。

NuGet 包

适用于多项目分发和版本化管理。

当前项目文件尚未包含完整 NuGet 元数据。如需打包发布，先在 Admin.NET.Plugin.Document.csproj 中补充：

<PropertyGroup>
  <PackageId>Admin.NET.Plugin.Document</PackageId>
  <Version>1.0.1</Version>
  <Authors>Admin.NET</Authors>
  <Company>Admin.NET</Company>
  <Description>Admin.NET 文档管理插件</Description>
  <PackageTags>Admin.NET;Plugin;Document</PackageTags>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>
  <IncludeSymbols>true</IncludeSymbols>
  <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>

<ItemGroup>
  <None Include="Configuration\**" Pack="true" PackagePath="contentFiles\any\any\Configuration\" />
</ItemGroup>

打包：

dotnet pack Admin.NET.Plugin.Document.csproj -c Release

发布到本地或私有源：

dotnet nuget push bin/Release/Admin.NET.Plugin.Document.1.0.1.nupkg --source C:\LocalNuGet

使用方安装：

dotnet add package Admin.NET.Plugin.Document --version 1.0.1 --source C:\LocalNuGet

NuGet 包通常不包含前端源码，前端仍需按下节复制。

前端集成

复制目录：

Web/src/views/document/ -> 目标项目 Web/src/views/document/
Web/src/api-services/document/ -> 目标项目 Web/src/api-services/document/

菜单路由由后端菜单种子数据生成，常规页面无需手工配置。分享码公开访问页如果目标项目需要匿名访问路径，需要在前端路由中加入：

{
  path: '/document/share/:shareCode',
  name: 'documentShareView',
  component: () => import('/@/views/document/share/view.vue'),
  meta: {
    title: '分享文档',
    isPublic: true,
    isHide: true,
  },
}

安装缺失依赖示例：

pnpm add @vue-office/docx @vue-office/excel @vue-office/pdf md-editor-v3

数据库和种子数据

目标项目数据库配置建议开启：

{
  "DbSettings": {
    "EnableInitDb": true
  },
  "TableSettings": {
    "EnableInitTable": true,
    "EnableIncreTable": true
  },
  "SeedSettings": {
    "EnableInitSeed": true,
    "EnableIncreSeed": true
  }
}

首次启动后确认：

文档相关表已创建或增量更新。
文档管理 菜单已写入。
默认分类种子数据按预期写入。
目标角色已分配菜单和按钮权限。

发布后验证

后端启动无插件加载错误。
Swagger 出现 Document 分组。
数据库存在文档相关表。
菜单出现 文档管理。
文档上传后能生成编号、写入 SysFile 关联和文档版本记录。
预览、下载、分享、权限设置按当前登录用户权限生效。

更新插件

备份已调整的 Configuration/Document.json。
替换 DLL 或更新 NuGet 版本。
对比配置项是否新增。
启用 EnableIncreTable 和 EnableIncreSeed 完成表结构和菜单增量更新。
重新构建并按发布后验证清单检查。