diff --git a/docs/en/Text-Templating.md b/docs/en/Text-Templating.md index 11a07b8673..07f3b141ab 100644 --- a/docs/en/Text-Templating.md +++ b/docs/en/Text-Templating.md @@ -390,7 +390,7 @@ The [Virtual File System](Virtual-File-System.md) allows you to override any fil #### Example: Replace the Standard Email Layout Template -ABP Framework provides an [email sending system](Emailing.md) that internally uses the text templating to render the email content. It defines an email layout template in the `/Volo/Abp/Emailing/Templates/Layout.tpl` path. The unique name of the template is `Abp.StandardEmailTemplates.Layout` and this string is defined as a constant on the `Volo.Abp.Emailing.Templates.StandardEmailTemplates` static class. +ABP Framework provides an [email sending system](Emailing.md) that internally uses the text templating to render the email content. It defines a standard email layout template in the `/Volo/Abp/Emailing/Templates/Layout.tpl` path. The unique name of the template is `Abp.StandardEmailTemplates.Layout` and this string is defined as a constant on the `Volo.Abp.Emailing.Templates.StandardEmailTemplates` static class. Do the following steps to replace the template file with your own; @@ -437,7 +437,7 @@ This makes the template files "embedded resource". **4)** Configure the virtual file system -Configure the `AbpVirtualFileSystemOptions` to add embedded files into the virtual file system: +Configure the `AbpVirtualFileSystemOptions` in the `ConfigureServices` method of your [module](Module-Development-Basics.md) to add the embedded files into the virtual file system: ```csharp Configure(options => diff --git a/docs/en/Virtual-File-System.md b/docs/en/Virtual-File-System.md index a519b02ec6..6a8effb751 100644 --- a/docs/en/Virtual-File-System.md +++ b/docs/en/Virtual-File-System.md @@ -6,7 +6,7 @@ The Virtual File System makes it possible to manage files that do not physically > Most of the times you don't need to manually install this package since it comes pre-installed with the [application startup template](Startup-Templates/Application.md). -[Volo.Abp.VirtualFileSystem](https://www.nuget.org/packages/Volo.Abp.VirtualFileSystem) is the main page of the Virtual File System. +[Volo.Abp.VirtualFileSystem](https://www.nuget.org/packages/Volo.Abp.VirtualFileSystem) is the main package of the Virtual File System. Use the ABP CLI to add this package to your project: @@ -18,9 +18,9 @@ If you want to do it manually, install the [Volo.Abp.VirtualFileSystem](https:// ## Working with the Embedded Files -### Embed the Files +### Embedding the Files -A file should be first marked as an **embedded resource** to embed the file into the assembly. The easiest way to do it is to select the file from the **Solution Explorer** and set **Build Action** to **Embedded Resource** from the **Properties** window. Example: +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 **Solution Explorer** and set **Build Action** to **Embedded Resource** from the **Properties** window. Example: ![build-action-embedded-resource-sample](images/build-action-embedded-resource-sample.png) @@ -55,21 +55,21 @@ Configure(options => }); ```` -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. It is common to pass the module class as the generic argument. +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 page. +* `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 `MyFiles` folder in the project** +**Example: Add files under the `MyResources` folder in the project** ````csharp Configure(options => { options.FileSets.AddEmbedded( - baseNamespace: "Acme.BookStore.MyFiles", - baseFolder: "/MyFiles" + baseNamespace: "Acme.BookStore", + baseFolder: "/MyResources" ); }); ```` @@ -77,56 +77,15 @@ Configure(options => This example assumes; * Your project root (default) namespace is `Acme.BookStore`. -* Your project has a folder, named `MyFiles` -* You only want to add `MyFiles` folder to the virtual file system. +* Your project has a folder, named `MyResources` +* You only want to add `MyResources` folder to the virtual file system. -### Dealing With Embedded Files During Development +### IVirtualFileProvider -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 module 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 have a browser refresh reflect 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 itself contains embedded files. The application can reach the source code of the module at development time. - -````C# -[DependsOn(typeof(MyModule))] -public class MyWebAppModule : AbpModule -{ - public override void ConfigureServices(ServiceConfigurationContext context) - { - var hostingEnvironment = context.Services.GetHostingEnvironment(); - - if (hostingEnvironment.IsDevelopment()) //only for development time - { - Configure(options => - { - options.FileSets.ReplaceEmbeddedByPhysical( - Path.Combine( - hostingEnvironment.ContentRootPath, - string.Format( - "..{0}MyModuleProject", - Path.DirectorySeparatorChar - ) - ) - ); - }); - } - } -} -```` - -The code above assumes that `MyWebAppModule` and `MyModule` are two different projects in a Visual Studio solution and `MyWebAppModule` depends on the `MyModule`. - -> The [application startup template](Startup-Templates/Application.md) already uses this technique for the localization files. So, when you change a localization file it automatically detects the change. - -## IVirtualFileProvider - -After embedding a file into an assembly and registering it to the virtual file system, the `IVirtualFileProvider` interface can be used to get files or directory contents: +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: ````C# -public class MyService +public class MyService : ITransientDependency { private readonly IVirtualFileProvider _virtualFileProvider; @@ -135,7 +94,7 @@ public class MyService _virtualFileProvider = virtualFileProvider; } - public void Foo() + public void Test() { //Getting a single file var file = _virtualFileProvider @@ -160,14 +119,14 @@ The Virtual File System is well integrated to ASP.NET Core: ### UseVirtualFiles Middleware -The Virtual Files Middleware is used to serve embedded (js, css, image...) files to clients/browsers just like physical files in the **wwwroot** folder. Add it just after the static file middleware as shown below: +The Virtual Files Middleware is used to serve embedded (js, css, image...) files to clients/browsers just like physical files in the **wwwroot** folder. It also covers the physical files. + +Replace the `app.UseStaticFiles()` with the `app.UseVirtualFiles()` in your ASP.NET Core middleware configuration: ````C# app.UseVirtualFiles(); ```` -Adding virtual files middleware after the static files middleware makes it possible to override a virtual file with a real physical file simply by placing it in the same location as the virtual file. - > `UseVirtualFiles()` is already configured for the [application startup template](Startup-Templates/Application.md). #### Static Virtual File Folders @@ -178,4 +137,45 @@ By default, ASP.NET Core only allows the `wwwroot` folder to contain the static * Views * Themes -This allows to add `.js`, `.css`... files near to your `.cshtml` file that is easier to develop and maintain your project. \ No newline at end of file +This allows to add `.js`, `.css`... files near to your `.cshtml` file that is easier to develop and maintain your project. + +## 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 module 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. + +````C# +[DependsOn(typeof(MyModule))] +public class MyWebAppModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + var hostingEnvironment = context.Services.GetHostingEnvironment(); + + if (hostingEnvironment.IsDevelopment()) //only for development time + { + Configure(options => + { + options.FileSets.ReplaceEmbeddedByPhysical( + Path.Combine( + hostingEnvironment.ContentRootPath, + string.Format( + "..{0}MyModuleProject", + Path.DirectorySeparatorChar + ) + ) + ); + }); + } + } +} +```` + +The code above assumes that `MyWebAppModule` and `MyModule` are two different projects in a Visual Studio solution and `MyWebAppModule` depends on the `MyModule`. + +> The [application startup template](Startup-Templates/Application.md) already uses this technique for the localization files. So, when you change a localization file it automatically detects the change. \ No newline at end of file