Extension Loading Mechanism
Overview
Different Versions of Libraries Available per Extension
Next Design loads libraries into different areas for each extension. This allows different versions of the same library to be used for each extension.
Purpose
- Extensions can use different versions of the same library across multiple extensions.
Extension A uses version 4.7.1 of System.Text.Json, while another extension B uses a newer version 5.0.2 of System.Text.Json. In this case, extension A uses the API version 4.7.1, and extension B uses the API version 5.0.2.
- Extensions can use newer versions of libraries than those referenced by the Next Design core.
Extensions can use newer versions of libraries than the Microsoft.WindowsAPICodePack referenced by the Next Design core.
If the version of a library referenced by an extension is less than or equal to the version of the library included with the Next Design core, the extension will not load the corresponding library; instead, the library already loaded by the Next Design core will be used.
This is for the following reasons:
- To reduce the memory size allocated for library loading
- To guarantee the operation of the Next Design core
- To suppress interface inconsistencies caused by data exchange between the Next Design core and extensions
How Extension Dependencies are Resolved
Next Design uses the assembly metadata description file (*.deps.json file) to resolve the location of extension dependencies.
Furthermore, it can correctly recognize dependent libraries even if they are native libraries.
Objective
- By describing assembly metadata, the deployment configuration of dependent libraries can be customized on the extension side.
- If dependent libraries are resolved using NuGet package management, the assembly metadata description file (*.deps.json file) is automatically generated during the build process.
- Therefore, it is recommended that extensions resolve dependent libraries using NuGet package management.
- Extensions that depend on native libraries can be distributed.
- By using the assembly metadata description file (*.deps.json file), extensions that depend on native libraries can be deployed.
- Furthermore, even if the "dependent native libraries differ" due to differences in OS or CPU, this is resolved at the time the extension is executed. For example, native libraries for
win-x64andwin-x86can be included in a single extension.
Handling of Static Variables in Libraries Referenced by Multiple Extensions
Next Design loads libraries in different memory areas for each extension. Consequently, static variables are handled as follows:
- Because each extension has different memory management, static variables (such as class variables) are not shared between multiple extensions.
- Therefore, static variables cannot be used to share information between extensions.
For example, even if you define a class variable like the following in one extension, another extension cannot reference the value of _SomeDictionary:
public class SomeClass
{
private static IDictionary<string, object> _SomeDictionary = new Dictionary<string, object>();
}
About Shared Libraries
Overview of Shared Libraries
Next Design loads libraries in different memory areas for each extension to allow extensions to use newer versions of libraries than those referenced by Next Design itself. However, depending on the library, loading it in a different memory area may affect its operation.
Shared libraries are a mechanism to load such libraries into the same area and avoid impacting operation.
- When a library referenced by an extension is designated as a shared library, it is shared with other extensions. This allows objects managed by other extensions to be passed around.
- If different versions of the library are designated as shared libraries for different extensions, the newest version of the library will be loaded and shared. This automatically applies feature improvements and bug fixes.
If you want to use a newer version of the library included with Next Design in your extension, do not designate that library as a shared library.
Loading Shared Libraries
Next Design scans the manifests of all active extensions1 regardless of their lifecycle to determine which libraries are designated as shared libraries. If different versions of the same library are designated as shared libraries for different extensions, the newest file version of the library will be loaded.
This mechanism ensures that even extensions with older versions of the library will use the latest version located in other extension folders.
Furthermore, regarding the culture (Resource), the resource library is loaded into the culture of the Next Design main application 2. In this process, subfolders such as ja and en within the same folder as the library targeted for loading as a shared library are searched.
- Extension shared libraries are searched from folders under the extension's execution folder.
However, folders (and their subfolders) that meet the following conditions are excluded from the search: - Folders whose names begin with "."
- Folders that contain executable files (*.exe)
Shared Library Restrictions
- Native libraries cannot be designated as shared libraries. Please configure shared libraries so that they do not contain native libraries.
- Libraries referenced by the Next Design main application cannot be designated as shared libraries. Define your manifest so that libraries referenced by the Next Design application itself are not designated as shared libraries.
Notes on Shared Libraries
If extensions that designate the same library as a shared library and extensions that do not designate it as a shared library coexist, the shared library will be used by all extensions.
This mechanism allows extensions with older versions of the library to utilize bug fixes and the latest features.
On the other hand, if backward compatibility is not guaranteed for the library in question, runtime errors may occur in the extension.
If a library referenced by an extension is not designated as a shared library, it will be loaded as a non-shared library. If a library is designated as a shared library, in addition to that library, all libraries referenced by that library will also be loaded as shared libraries.
Furthermore, if a non-shared library and a shared library reference the same library, the same library will be loaded twice under separate memory management.
In this state, even if the same type is defined in the same library, runtime errors may occur where it cannot be found under the other library's memory management.
For extensions that use WPF, and other extensions that reference such libraries, please specify all relevant libraries as shared libraries.
Notes on Extension Development and Maintenance
If a library referenced by an extension is a non-shared library, the version of the library referenced at the time of extension execution will be determined according to the following rules.
| Included in extension (A) | Included in Next Design core (B) | Library version age | Referenced version |
|---|---|---|---|
| Included | - | - | (A) |
| - | Included | - | (B) |
| Included | Included | (A) is newer than (B) | (A) |
| Included | Included | (A) and (B) are the same, or (B) is newer than (A) | (B) |
In the case of shared libraries between extensions, the newest version of the library included in each extension is referenced.
Also, libraries included in the Next Design core cannot be designated as shared libraries.
With the above rules in mind, please note the following points when developing and maintaining extensions:
During development, verify that the extension works correctly by combining it with the target Next Design version and other extensions that reference the shared library.
For maintenance, check the versions of the libraries referenced when the extension is executed in accordance with the following changes, and verify that the extension works correctly in combination with those versions.
- The Next Design core has been updated, and the libraries included with the core and their versions have changed.
- The shared library specification has changed in other extensions.
- The version of the library specified as a shared library in other extensions has changed.
Extension Distribution Procedure and Precautions
When distributing extensions, configure the files to be distributed according to the following.
Extension Folder Structure
In Next Design, the extension distribution folder should contain the manifest file, the extension core library, dependent libraries, and the assembly metadata description file (*.deps.json file).
{Extension Folder}/
manifest.json
{Extension Main Library Name}.dll
{Extension Main Library Name}.deps.json
{Extension Dependency Library Name}.dll
...
Assembly Metadata Description File
When you build an extension with dotnet build, this file is automatically created in the build result output folder. See below for details.
- When distributing an extension, place the generated
*.deps.json filein the extension folder. - If it is not placed, loading of libraries that the extension depends on may fail.
Collecting Dependency Libraries
You can collect the extension's dependent libraries in the output folder with dotnet publish. See below for details.
- dotnet publish collects all dependent libraries.
- If an extension uses libraries that are also referenced by Next Design itself, you can remove those libraries from the package during extension distribution to reduce the package size, provided they are not newer versions than the main application.
Placement of Internationalization Resource DLLs
DLL-based extensions can utilize the C# standard localization.
- If the extension (and its dependent libraries) uses string resources for internationalization, a library (*.resources.dll) containing language-specific resource information will be generated in the output folder.
- When distributing the extension, place these libraries in the extension folder along with the folder structure.
{Extension Folder}/
en/
{Extension Main Library Name}.resources.dll
fr/
{Extension Main Library Name}.resources.dll
manifest.json
{Extension Main Library Name}.dll
{Extension Main Library Name}.deps.json
{Extension Dependency Library Name}.dll
...
Native Library Placement
Next Design allows extensions to utilize native libraries.
- If an extension (and its dependent libraries) depends on a native library, native libraries for each runtime environment will be output to the output folder.
- When distributing extensions, please place these libraries in the extension folder along with their folder structure.
{Extension Folder}/
runtimes/
win-x64/
{Native Library Name}.dll
win-x86/
{Native Library Name}.dll
manifest.json
{Extension Main Library Name}.dll
{Extension Main Library Name}.deps.json
{Extension Dependent Library Name}.dll
...
Limitations
Conflicts with Libraries Referenced by Next Design
Older versions of libraries referenced by Next Design will not be loaded. The newer version referenced by Next Design will be used. Therefore, if an extension uses an older version of a library located in the same folder as the Next Design executable, and backward compatibility is not guaranteed between those libraries, the extension will fail to activate or an error will occur at runtime.
- For example, if an extension built with an older
Next Design.Corereferences an interface that is deprecated in the newerNext Design.Core, the newer Next Design will not be able to resolve that interface, resulting in an error.
Extension Restrictions on Referencing Native Libraries
Due to .NET limitations, the location of native libraries may not be resolvable.
-
When a native library is requested to be loaded using NativeLibrary.Load(), the extension loading mechanism cannot resolve it.
-
Therefore, if you are loading a native library using the above method, the library must be located in a place where it can be loaded by NativeLibrary.Load().
Native Libraries Subject to the Above Restrictions (as Known at This Time)
-
The SQLite native library (e_sqlite3.dll) used in EFCore is affected.
-
Next Design includes native libraries for EFCore 3.1 series to mitigate the above limitations.
-
Therefore, the operation of extensions that depend on versions other than EFCore 3.1 series is not guaranteed.
Restrictions on Temporary Assembly File Generation
If an extension uses a function that requires the generation of temporary assembly files at runtime, the extension loading mechanism may not be able to identify the location of those assembly files, which may cause the extension to malfunction.
Please choose an implementation method that avoids the generation of temporary assembly files, according to the information provided by the developer of the function you are using.