Skip to content

Commit c36b055

Browse files
isc30isc30
authored
Versionable Wiki (#52)
* versionable wiki * test wiki change * adapt github action to only push wiki for master branch
1 parent aef2c60 commit c36b055

16 files changed

+426
-6
lines changed

‎.github/workflows/nuget-publish.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,14 @@ jobs:
6969
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
7070
BRANCH: gh-pages
7171

72+
- name: Deploy wiki
73+
uses: jamesives/[email protected]
74+
with:
75+
FOLDER: docs
76+
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
77+
REPOSITORY_NAME: isc30/blazor-lazy-loading.wiki
78+
BRANCH: master
79+
7280
- name: Upload artifacts
7381
uses: actions/upload-artifact@v1
7482
with:

‎README.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
<p align="center">
22
<a href="https://github.com/isc30/blazor-lazy-loading">
3-
<img src="doc/img/logo.png?raw=true" />
3+
<img src="docs/img/logo.png?raw=true" />
44
</a>
55
</p>
66
<p align="center">
77
<a href="https://github.com/isc30/blazor-lazy-loading"><img src="https://img.shields.io/github/workflow/status/isc30/blazor-lazy-loading/[trigger]%20new%20release/master?logo=github" /></a>
8-
<a href="https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=false"><img src="https://img.shields.io/nuget/v/BlazorLazyLoading.Components?color=brightgreen&label=stable&logo=nuget)](https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=false" /></a>
9-
<a href="https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=false"><img src="https://img.shields.io/nuget/dt/BlazorLazyLoading.Components?color=brightgreen&label=downloads&logo=nuget)](https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=false" /></a>
10-
<a href="https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=true"><img src="https://img.shields.io/nuget/vpre/BlazorLazyLoading.Components?color=yellow&label=dev&logo=nuget)](https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=false" /></a>
8+
<a href="https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=false"><img src="https://img.shields.io/nuget/v/BlazorLazyLoading.Components?color=brightgreen&label=stable&logo=nuget" /></a>
9+
<a href="https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=false"><img src="https://img.shields.io/nuget/dt/BlazorLazyLoading.Components?color=brightgreen&label=downloads&logo=nuget" /></a>
10+
<a href="https://www.nuget.org/packages?q=BlazorLazyLoading&prerel=true"><img src="https://img.shields.io/nuget/vpre/BlazorLazyLoading.Components?color=yellow&label=dev&logo=nuget" /></a>
1111
</p>
1212
<br/>
1313

1414
Automatic Lazy Loading support for Blazor WebAssembly and Blazor Server!<br/><br/>
1515

16-
[![Documentation / Wiki](doc/img/documentation.png?raw=true)](https://github.com/isc30/blazor-lazy-loading/wiki)
16+
[![Documentation / Wiki](docs/img/documentation.png?raw=true)](https://github.com/isc30/blazor-lazy-loading/wiki)
1717

18-
[![Demo](doc/img/demo.png?raw=true)](https://isc30.github.io/blazor-lazy-loading/)
18+
[![Demo](docs/img/demo.png?raw=true)](https://isc30.github.io/blazor-lazy-loading/)

‎docs/[email protected]

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# &lt;Lazy /&gt;
2+
3+
Renders a Component (`IComponent`) from a Lazy Module based on it's **LazyName** or **TypeFullName** (*string*).
4+
5+
This Component needs to exist in a *known* Lazy Module, either [hinted directly](Configuring-Lazy-Loading-@-Server#modulehints) or using [ModulesHost strategy](Creating-a-Lazy-Loadable-Module#creating-an-aggregated-module).
6+
7+
# Render by using TypeFullName
8+
9+
The is no extra prerequisite to render an `IComponent` by using **TypeFullName**:
10+
11+
```razor
12+
<Lazy Name="MyApplication.Hello" />
13+
```
14+
15+
This snippet renders a `Hello` Component assuming the type is `MyApplication.Hello`. It will **automatically fetch** the manifests, consume them to **locate** the Component and **download** the minimum assemblies to make it work 😄
16+
17+
# Named Components
18+
19+
It is possible to **manually name** your Components and use that name later to resolve them.<br />
20+
This is done by adding a simple **attribute** `BlazorLazyLoading.LazyNameAttribute` to your Component:
21+
22+
* Syntax: `.razor`
23+
```razor
24+
@attribute [LazyName("SayHello")]
25+
<h1>Hello!</h3>
26+
```
27+
28+
* Syntax: `.cs`
29+
```cs
30+
[LazyName("SayHello")]
31+
public class Hello : IComponent { ... }
32+
```
33+
34+
And then **render** it like the following:
35+
36+
```razor
37+
<Lazy Name="SayHello" />
38+
```
39+
40+
In order to *debug* if your component **name** is generated properly, you can check the contents of `_lazy.json`.
41+
```json
42+
{
43+
"MyApplication": {
44+
"Components": [
45+
{
46+
"TypeFullName": "MyApplication.Hello",
47+
"Name": "SayHello"
48+
}
49+
]
50+
}
51+
}
52+
```
53+
54+
# Custom 'Loading' view
55+
56+
It is possible to customize the `<Lazy>` Component with a **loading** `RenderFragment` that will get rendered while everything is being initialized.
57+
58+
It only requires setting a `RenderFragment` called `Loading`:
59+
60+
```razor
61+
<Lazy Name="SayHello">
62+
<Loading>
63+
<p>Loading, please wait</p>
64+
<div class="spinner" />
65+
</Loading>
66+
</Lazy>
67+
```
68+
69+
# Custom 'Error' view
70+
71+
It is possible to customize the 'error' `RenderFragment` that gets renderd if the Component fails to initialize *(because some assembly failed to load, such element doesn't exist, etc)*.
72+
73+
It only requires setting a `RenderFragment` called `Error`:
74+
75+
```razor
76+
<Lazy Name="SayHello">
77+
<Error>
78+
<p class="error">Something bad happened</p>
79+
</Error>
80+
</Lazy>
81+
```
82+
83+
# Handling Errors
84+
85+
It is possible to specify if a Component is **Required** (if a loading error throws an exception) by setting the property `Required` *(bool)* on it.
86+
87+
```razor
88+
<Lazy Required="false" Name="Unknown" /> @* this will simply not get rendered *@
89+
<Lazy Required="true" Name="Unknown" /> @* this will throw an exception *@
90+
@* both will render the 'error' view *@
91+
```
92+
93+
# Hooking into Events
94+
95+
There are 2 Events you can hook to by just setting Callbacks in the Component:
96+
97+
* #### OnBeforeLoadAsync
98+
99+
This callback will be awaited **before** trying to resolve the Component from the manifests.
100+
Useful for delaying a Component render to perform another operation before, and Debugging with `Task.Delay`.
101+
102+
* #### OnAfterLoad
103+
104+
This callback will be invoked **after** resolving and rendering the lazy Component.
105+
106+
```razor
107+
<Lazy
108+
Name="SayHello"
109+
OnBeforeLoadAsync="l => Task.Delay(500)"
110+
OnAfterLoad='l => Console.WriteLine($"Loaded LazyComponent: {l.Name}")' />
111+
```
112+
113+
# SEO and Prerendering Support
114+
115+
Don't worry about SEO. If you use BlazorServer or Prerendering, the Component HTML will be **fully rendered** automatically by the server so there is no difference between rendering it directly and using `<Lazy>`.

‎docs/[email protected]

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# &lt;LazyRouter /&gt;
2+
3+
Provides SPA navigation for Pages and Routes in Lazy Modules. It is a direct replacement of `<Router>`.
4+
5+
The pages need to exist in a *known* Lazy Module, either [hinted directly](Configuring-Lazy-Loading-@-Server#modulehints) or using [ModulesHost strategy](Creating-a-Lazy-Loadable-Module#creating-an-aggregated-module).
6+
7+
# Creating Lazy Pages and Routes
8+
9+
Pages and Routes don't require any configuration, just create them as you would normally (using `@page` attribute, etc).
10+
11+
If the Page is contained in a **Module**, the manifest *(_lazy.json)* will already generate all the information for routing automatically:
12+
13+
```json
14+
{
15+
"MyApplication": {
16+
"Routes": [
17+
{
18+
"Route": "/counter",
19+
"Name": "CounterPage"
20+
}
21+
]
22+
}
23+
}
24+
```
25+
26+
# Using LazyRouter
27+
28+
As mentioned before, this is a **direct replacement** of `Router` so it's safe to replace one with another in your `App.razor` file.
29+
30+
```diff
31+
- <Router AppAssembly="@typeof(Program).Assembly">
32+
+ <LazyRouter AppAssembly="@typeof(Program).Assembly">
33+
<Found Context="routeData">
34+
<LayoutView Layout="@typeof(MainLayout)">
35+
<RouteView RouteData="@routeData" />
36+
</LayoutView>
37+
</Found>
38+
<NotFound>
39+
<LayoutView Layout="@typeof(MainLayout)">
40+
<p>Sorry, there's nothing at this address</p>
41+
</LayoutView>
42+
</NotFound>
43+
- </Router>
44+
+ </LazyRouter>
45+
```
46+
47+
Done! The router will automatically provide SPA style navigation for your lazy routes!
48+
49+
# Custom 'Loading' screen
50+
51+
It is possible to customize the 'loading' screen while a Page is downloading the needed Assemblies.
52+
53+
This is done by setting the `Loading` `RenderFragment`:
54+
55+
```razor
56+
<LazyRouter AppAssembly="@typeof(Program).Assembly">
57+
<Loading Context="moduleName">
58+
<LayoutView Layout="@typeof(MainLayout)">
59+
<div class="fullScreenOverlay">
60+
<LoadingSpinner />
61+
</div>
62+
</LayoutView>
63+
</Loading>
64+
@* ... the rest of <Found> and <NotFound> *@
65+
</LazyRouter>
66+
```
67+
68+
# SEO and Prerendering Support
69+
70+
There is no need to worry about SEO. If you use BlazorServer or Prerendering, the returned page HTML will be **fully rendered** automatically by the server so there is no difference between the prerendered HTML content of `<Router>` and `<LazyRouter>`.

‎docs/Components.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
There are multiple ways of using resources from modules, but the simplest one is to use the built-in components from `BlazorLazyLoading.Components`.
2+
3+
It should be installed in every library that wants to consume decoupled resources:
4+
5+
```xml
6+
<PackageReference Include="BlazorLazyLoading.Components" Version="1.1.0" />
7+
```
8+
9+
This section will cover the different components available and their usage.

‎docs/[email protected]

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
The following nuget package includes everything you need to support lazy loading on **Blazor Server** and **Prerendering**.<br/>
2+
3+
It can be installed by adding the following line inside the host csproj:
4+
5+
```xml
6+
<PackageReference Include="BlazorLazyLoading.Server" Version="1.1.0" PrivateAssets="all" />
7+
```
8+
9+
It will also require to be initialized from **Startup.cs** by adding the following lines:<br/>
10+
11+
```cs
12+
public class Startup
13+
{
14+
public void ConfigureServices(IServiceCollection services)
15+
{
16+
services.AddLazyLoading(new LazyLoadingOptions
17+
{
18+
ModuleHints = new[] { "ModulesHost" }
19+
});
20+
}
21+
22+
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
23+
{
24+
// ideally after calling app.UseStaticFiles()
25+
app.UseLazyLoading(); // serves DLL and PDB files as octet/stream
26+
}
27+
}
28+
```
29+
# LazyLoadingOptions
30+
31+
* #### ModuleHints
32+
33+
In order to find the `_lazy.json` manifest files and DLLs, you need to specify *at least* an entry-point to a lazy module. This **must** be done by passing the *"known modules"* as **string**.
34+
35+
>Specifies a list of Module Names (hints) to:
36+
>- Download DLLs from them
37+
>- Use their manifest to locate lazy resources
38+
39+
* #### UseAssemblyIsolation
40+
41+
Serverside Blazor has a small disadvantage: by default, the loaded assemblies are in **the same context** for every user. If you have a `static` field in them, the value will be shared accross all SignalR connections. If this happens, it can introduce weird bugs and massive scalability issues (*it could also happen with a nuget package using a static field internally*).
42+
43+
To avoid these issues, BlazorLazyLoading introduces full assembly isolation by creating a Scoped `AssemblyLoadContext`. Unless you really know what you are doing, it is recommended to **NOT** turn this off.
44+
45+
>default: true
46+
>Configures assembly isolation level. Do NOT set this to 'false' unless you want to share 'static' fields between users.<br />
47+
>Keeping this enabled ensures that the server can be scaled horizontally.<br />

‎docs/[email protected]

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
The following nuget package includes everything you need to support lazy loading on **Blazor WebAssembly** (when statically published, using DevServer or using [DualMode](https://github.com/Suchiman/BlazorDualMode)).<br/>
2+
3+
It can be installed by adding the following line inside the host csproj:
4+
5+
```xml
6+
<PackageReference Include="BlazorLazyLoading.Wasm" Version="1.1.0" PrivateAssets="all" />
7+
```
8+
9+
It will also require to be initialized from **Program.cs** by adding the following lines:<br/>
10+
11+
```cs
12+
builder.Services.AddLazyLoading(new LazyLoadingOptions
13+
{
14+
ModuleHints = new[] { "ModulesHost" }
15+
});
16+
```
17+
18+
# Configuring the Linker
19+
20+
In order to load assemblies dynamically, the linker can be a big issue since it is **enabled** for release builds **by default**.
21+
22+
There are 2 ways of approaching this:
23+
24+
### Disabling the Linker (easy)
25+
26+
This option sounds worse that it is in reality. Yes, disabling the linker will ship mscorlib as initial download to the browser, **BUT that's all**. The initial impact won't be big if we Lazy Load the rest of the application.
27+
28+
```xml
29+
<PropertyGroup>
30+
<BlazorWebAssemblyEnableLinking>false</BlazorWebAssemblyEnableLinking>
31+
</PropertyGroup>
32+
```
33+
34+
### Using LinkerConfig.xml (advanced)
35+
36+
Even if this solution is more advanced, it will give us the best performance. Please refer to [the following guide](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/blazor/configure-linker?view=aspnetcore-3.1#control-linking-with-a-configuration-file) to setup your *LinkerConfig.xml*.
37+
38+
The recommendation here would be something like this, but you might need to adapt it for your needs:
39+
40+
```xml
41+
<?xml version="1.0" encoding="UTF-8" ?>
42+
<linker>
43+
<assembly fullname="netstandard" /> <!-- keep full netstandard since its used by the lazy modules -->
44+
<assembly fullname="ModulesHost" /> <!-- keep full entrypoint -->
45+
</linker>
46+
```
47+
48+
Done! Lazy Loading is now configured 😄
49+
50+
# LazyLoadingOptions
51+
52+
* #### ModuleHints
53+
54+
In order to find the `_lazy.json` manifest files and DLLs, you need to specify *at least* an entry-point to a lazy module. This **must** be done by passing the *"known modules"* as **string**.
55+
56+
>Specifies a list of Module Names (hints) to:
57+
>- Download DLLs from them
58+
>- Use their manifest to locate lazy resources

‎docs/Configuring-Lazy-Loading.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Depending on the Blazor host, different instructions are required.<br/>
2+
Please refer to the specific guide 😄
3+
4+
- [WebAssembly](Configuring-Lazy-Loading-@-WebAssembly)
5+
- [BlazorServer](Configuring-Lazy-Loading-@-Server)

0 commit comments

Comments
 (0)