Skip to content

Home

Jump to bottom
Norbert Bietsch edited this page Feb 26, 2021 · 2 revisions
Logo

Axuno.VirtualFileSystem

The Axuno.VirtualFileSystem makes it possible to manage files that do not physically exist in the file system (disk). It's mainly used to embed files (e.g. (js, css, image) into assemblies and use them like physical files at runtime.

Working with the Embedded Files

Embedding the Files

A file should be first marked as embedded resource to embed the file into the assembly. The easiest way to do it is to select the file from the Visual Studio Solution Explorer and set Build Action to Embedded Resource from the Properties window.

If you want to add multiple files, this can be tedious. Alternatively, you can edit your project file (.csproj) directly :

<ItemGroup>
  <EmbeddedResource Include="MyResources\**\*.*" />
  <Content Remove="MyResources\**\*.*" />
</ItemGroup>

This configuration recursively adds all files under the MyResources folder of the project (including the files you will add in the future).

Embedding a file in the project/assembly may cause problems if a file name contains some special characters. To overcome this limitation;

  1. Add Microsoft.Extensions.FileProviders.Embedded NuGet package to the project that contains the embedded resource(s).
  2. Add <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest> into the <PropertyConfig>...</PropertyConfig> section of your .csproj file.

While these two steps are optional and Axuno.VirtualFileSystem can work without these configurations, it is strongly recommended to go them.

Configure the VirtualFileSystemOptions

Use VirtualFileSystemOptions to register the embedded files to the virtual file system in the ConfigureServices method of your App (Startup.cs for AspNetCore).

Example: Add embedded files to the virtual file system

Configure<VirtualFileSystemOptions>(options =>
{
    options.FileSets.AddEmbedded<MyModule>();
});

The AddEmbedded extension method takes a class, finds all embedded files from the assembly of the given class and registers them to the virtual file system.

AddEmbedded can get two optional parameters;

  • baseNamespace: This may only needed if you didn't configure the GenerateEmbeddedFilesManifest step explained above and your root namespace is not empty. In this case, set your root namespace here.
  • baseFolder: If you don't want to expose all embedded files in the project, but only want to expose a specific folder (and sub folders/files), then you can set the base folder relative to your project root folder.

Example: Add files under the MyResources folder in the project

Configure<AbpVirtualFileSystemOptions>(options =>
{
    options.FileSets.AddEmbedded<MyModule>(
        baseNamespace: "Acme.BookStore",
        baseFolder: "/MyResources"
    );
});

This example assumes;

  • Your project root (default) namespace is Acme.BookStore.
  • Your project has a folder, named MyResources
  • You only want to add MyResources folder to the virtual file system.

IVirtualFileProvider

After embedding a file into an assembly and registering it to the virtual file system, the IVirtualFileProvider interface can be used to get the file or directory contents:

public class MyServicey
{
    private readonly IVirtualFileProvider _virtualFileProvider;

    public MyService(IVirtualFileProvider virtualFileProvider)
    {
        _virtualFileProvider = virtualFileProvider;
    }

    public void Test()
    {
        //Getting a single file
        var file = _virtualFileProvider
            .GetFileInfo("/MyResources/js/test.js");

        var fileContent = file.ReadAsString();

        //Getting all files/directories under a directory
        var directoryContents = _virtualFileProvider
            .GetDirectoryContents("/MyResources/js");
    }
}

ASP.NET Core and 5.0 Integration

The Virtual File System is well integrated to ASP.NET Core and 5.0:

  • Virtual files can be used just like physical (static) files in a web application.
  • js, css, image files and all other web content types can be embedded into assemblies and used just like the physical files.
  • An application can override a virtual file of an or library just by placing a file with the same name and extension into the same folder as the virtual file.

Dealing With Embedded Files During Development

Embedding a file into an assembly and being able to use it from another project just by referencing the assembly (or adding a NuGet package) is invaluable for creating a re-usable module. However, it makes it a little bit harder to develop the module itself.

Let's assume that you're developing a library that contains an embedded JavaScript file. Whenever you change this file you must re-compile the project, re-start the application and refresh the browser page to take the change. Obviously, this is very time consuming and tedious.

What is needed is the ability for the application to directly use the physical file at development time and a browser refresh reflects any change made in the JavaScript file. The ReplaceEmbeddedByPhysical method makes all this possible.

The example below shows an application that depends on a module (MyModule) that contains embedded files. The application can access to the source code of the module at development time.

public class MyLibraryClass
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        var hostingEnvironment = context.Services.GetHostingEnvironment();

        if (hostingEnvironment.IsDevelopment()) //only for development time
        {
            Configure<VirtualFileSystemOptions>(options =>
            {
                options.FileSets.ReplaceEmbeddedByPhysical<MyModule>(
                    Path.Combine(
                        hostingEnvironment.ContentRootPath,
                        string.Format(
                            "..{0}MyModuleProject",
                            Path.DirectorySeparatorChar
                        )
                    )
                );
            });
        }
    }
}

The code above assumes that MyLibraryClass and MyModule are two different projects in a Visual Studio solution and MyLibraryClass depends on the MyModule.

Replacing/Overriding Virtual Files

Virtual File System creates a unified file system at runtime, where the actual files are distributed into different modules during development.

If two modules add a file to the same virtual path (like my-path/my-file.css), the one added later overrides/replaces the previous one.

This feature allows your application to override/replace any virtual file defined a module that is used by your application. This is one of the fundamental extensibility features.

So, if you need to replace a file of a library, just create the file in the exactly same path in your application.

Physical Files

Physical files always override the virtual files. That means if you put a file under the /wwwroot/my-folder/my-file.css, it will override the file in the same location of the virtual file system. So, you need to know the file paths defined in the library to override them.

Clone this wiki locally