理解ABP框架中的嵌入式(Embedded)文件

NET应用程序的的嵌入文件（Embedded Files）功能允许将外部文件（如配置文件、图像等）直接嵌入到程序集（.exe 或 .dll）中。这样可以简化部署过程，避免文件丢失或篡改，提升安全性和性能，同时减少路径和依赖管理的麻烦。通过嵌入资源，程序可以更方便地访问这些文件，且无需额外的文件操作。

在项目中嵌入文件

我们在MyModule.csproj中将Volo\Abp\MyModule\Localization\*.json文件嵌入到程序集中.

<Project Sdk="Microsoft.NET.Sdk">

 <PropertyGroup>
 <TargetFramework>net9.0</TargetFramework>
 <OutputType>Exe</OutputType>
 <able>enable</able>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.0" />
 <PackageReference Include="Volo.Abp.VirtualFileSystem" Version="9.0.0" />
 </ItemGroup>

 <ItemGroup>
 <None Remove="Volo\Abp\MyModule\Localization\*.json" />
 <EmbeddedResource Include="Volo\Abp\MyModule\Localization\*.json" />
 </ItemGroup>

</Project>

如果我们在IDE中查看en.json文件, 我们会看到它已经被嵌入到程序集中了.

反编译构建后的MyModule.dll文件, 我们也会看到en.json文件.

在代码中访问嵌入的文件

public classProgram
{
 public static async Task<int> Main(string[] args)
 {
 var embeddedFiles = typeof(Program).Assembly.GetManifestResourceNames();
 foreach (var embeddedFile in embeddedFiles)
 {
 Console.WriteLine(embeddedFile);
 var fileStream = typeof(Program).Assembly.GetManifestResourceStream(embeddedFile);
 if (fileStream != )
 {
 usingvar reader = new System.IO.StreamReader(fileStream);
 var content = await reader.ReadToEndAsync();
 Console.WriteLine(content);
 }
 }
 }
}

上述代码会输出嵌入的文件名和内容.

MyModule.Volo.Abp.MyModule.Localization.en.json

{
 "key":"value"
}

集成ABP虚拟文件系统

ABP虚拟文件系统可以管理那些物理上并不存在于文件系统（磁盘）上的文件。它主要用于将（js、css、图片……）文件嵌入到程序集，并在运行时像使用物理文件一样使用它们。

下面的代码展示了添加当前应用程序集的嵌入文件到ABP虚拟文件系统.

[DependsOn(typeof(AbpVirtualFileSystemModule))]
public class MyModule : AbpModule
{
 public override void ConfigureServices(ServiceConfigurationContext context)
 {
 Configure(options =>
 {
 options.FileSets.AddEmbedded();
 });
 }
}

ABP会创建一个AbpEmbeddedFileProvider来访问嵌入的文件.

en.json的文件全名是
MyModule.Volo.Abp.MyModule.Localization.en.json, 它没有目录信息, ABP会使用.来分割和假定目录信息. 最终会在虚拟文件系统中生成如下的目录结构.

[Dir] [/MyModule]
[Dir] [/MyModule/Volo]
[Dir] [/MyModule/Volo/Abp]
[Dir] [/MyModule/Volo/Abp/MyModule]
[Dir] [/MyModule/Volo/Abp/MyModule/Localization]
[File] [/MyModule/Volo/Abp/MyModule/Localization/en.json]

现在你可以注入IVirtualFileProvider来根据上面的目录/文件来访问嵌入的文件.

Manifest Embedded File Provider

你应该已经注意到, 使用.来分割和假定目录信息, 如果文件名中包含.的话, 会导致目录结构混乱.

比如你的文件名称是zh.Hans.json, 那么ABP会生成如下的目录结构, 这显然不是我们想要的.

[Dir] [/MyModule]
[Dir] [/MyModule/Volo]
[Dir] [/MyModule/Volo/Abp]
[Dir] [/MyModule/Volo/Abp/MyModule]
[Dir] [/MyModule/Volo/Abp/MyModule/Localization]
[Dir] [/MyModule/Volo/Abp/MyModule/Localization/zh]
[File] [/MyModule/Volo/Abp/MyModule/Localization/zh/hans.json]

微软提供了
Microsoft.Extensions.FileProviders.Manifest类库来解决这个问题.

我们需要在项目中添加这个包的依赖并设置<
GenerateEmbeddedFilesManifest>true<
/GenerateEmbeddedFilesManifest>

<Project Sdk="Microsoft.NET.Sdk">

 <PropertyGroup>
 <TargetFramework>net9.0</TargetFramework>
 <OutputType>Exe</OutputType>
 <able>enable</able>
 <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.0" />
 <PackageReference Include="Volo.Abp.VirtualFileSystem" Version="9.0.0" />
 <PackageReference Include="Microsoft.Extensions.FileProviders.Manifest" Version="9.0.0" />
 </ItemGroup>

 <ItemGroup>
 <None Remove="Volo\Abp\MyModule\Localization\*.json" />
 <EmbeddedResource Include="Volo\Abp\MyModule\Localization\*.json" />
 </ItemGroup>

</Project>

重新构建项目, 我们反编译的MyModule.dll文件, 会看到会多一个
Microsoft.Extensions.FileProviders.Embedded.Manifest.xml文件.

它的内容如下, 它记录了所有嵌入的文件和目录和文件信息, 如果ABP发现了这个文件, 它会使用
ManifestEmbeddedFileProvider替换AbpEmbeddedFileProvider来访问嵌入的文件.

<Manifest>
 <ManifestVersion>1.0</ManifestVersion>
 <FileSystem>
 <File Name="Microsoft.Extensions.FileProviders.Embedded.Manifest.xml">
 <ResourcePath>Microsoft.Extensions.FileProviders.Embedded.Manifest.xml</ResourcePath>
 </File>
 <Directory Name="Volo">
 <Directory Name="Abp">
 <Directory Name="MyModule">
 <Directory Name="Localization">
 <File Name="zh.hans.json">
 <ResourcePath>MyModule.Volo.Abp.MyModule.Localization.zh.hans.json</ResourcePath>
 </File>
 </Directory>
 </Directory>
 </Directory>
 </Directory>
 </FileSystem>
</Manifest>

AddEmbedded方法的参数

AddEmbedded方法可以接受两个参数:

baseNamespace

它只有在你没有使用Manifest Embedded File Provider且您的根命名空间不为空时才需要。在这种情况下，请在这里设置您的根命名空间。

baseNamespace 只有在没有使用Manifest Embedded File Provider时才有效.

默认情况下，根命名空间就是你的项目名称。你可以在csproj文件里修改它，或者把它设置为空。

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <RootNamespace>MyModule</RootNamespace>
 </PropertyGroup>
</Project>

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <RootNamespace></RootNamespace>
 </PropertyGroup>
</Project>

Configure(options =>
{
 options.FileSets.AddEmbedded(baseNamespace: "MyModule");
});

[Dir] [/Volo]
[Dir] [/Volo/Abp]
[Dir] [/Volo/Abp/MyModule]
[Dir] [/Volo/Abp/MyModule/Localization]
[File] [/Volo/Abp/MyModule/Localization/en.json]

baseFolder

如果你不想公开项目中所有嵌入的文件，只想公开特定文件夹（及其子文件夹/文件），那么你可以设置相对于项目根文件夹的基准文件夹。

baseFolder 只有在使用Manifest Embedded File Provider时才有效.

你可以设置baseFolder参数为/Volo/Abp/MyModule, 那么最终的目录结构如下:

Configure(options =>
{
 options.FileSets.AddEmbedded(baseFolder: "/Volo/Abp/MyModule");
});

[Dir] [Localization]
[File] [Localization/en.json]

总结

我们推荐你在你的项目和类库中使用Manifest Embedded File Provider来结合ABP虚拟文件系统来管理嵌入的文件. 希望这篇文章对你有所帮助.

References

ABP Virtual File System

Manifest Embedded File Provider