-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
140 additions
and
40 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
107 changes: 81 additions & 26 deletions
107
i18n/en/docusaurus-plugin-content-docs/current/business/reload/quickstart.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,46 +1,101 @@ | ||
| # Quick Start | ||
|
|
||
| Almost identical to the [Quick Start](../../beginner/quickstart.md) of the Community Edition, this document only highlights the differences. | ||
| This is almost identical to the community version of the [Quick Start](../../beginner/quickstart.md), and this document only describes the differences. | ||
|
|
||
| ## Installation | ||
|
|
||
| - Extract hybridclr_unity and place it in the project's Packages directory, renaming it to com.code-philosophy.hybridclr. | ||
| - Extract the corresponding il2cpp_plus-{version}.zip based on your Unity version. | ||
| - Extract hybridclr.zip. | ||
| - Place the hybridclr directory from the extracted hybridclr.zip into the libil2cpp directory from the extracted il2cpp-{version}.zip. | ||
| - Open `HybridCLR/Installer`, enable the `Copy libil2cpp from local` option, select the libil2cpp directory that was just extracted, and proceed with the installation. | ||
| - Unzip hybridclr_unity and put it in the project Packages directory, rename it to com.code-philosophy.hybridclr | ||
| - Unzip the corresponding `il2cpp_plus-{version}.zip` according to your unity version | ||
| - Unzip `hybridclr.zip` | ||
| - Put the hybridclr directory after unzipping `hybridclr.zip` into the libil2cpp directory after unzipping `il2cpp-{version}.zip` | ||
| - Open `HybridCLR/Installer`, turn on the `Copy libil2cpp from local` option, select the libil2cpp directory just unzipped, and install it | ||
|
|
||
|  | ||
|
|
||
| ## Usage in Code | ||
| ## Use in code | ||
|
|
||
| Use `RuntimeApi.UnloadAssembly` to unload the assembly and `Assembly.Load` to reload the assembly. Currently, reloading the same assembly without unloading it first is not supported. Example code: | ||
| Call `RuntimeApi.TryUnloadAssembly or RuntimeApi.ForceUnloadAssembly` Unload the assembly and reload it using `Assembly.Load`. The assembly must be successfully unloaded before it can be loaded again. | ||
|
|
||
| There are currently two unloading workflows: | ||
|
|
||
| - TryUnloadAssembly | ||
| - ForceUnloadAssembly | ||
|
|
||
| ### TryUnloadAssembly | ||
|
|
||
| Try to unload. If there is a reference to the object in the unloaded assembly in the AppDomain, keep the status quo and return failure, otherwise return success. | ||
|
|
||
| The sample code is as follows: | ||
|
|
||
| ```csharp | ||
| // First load | ||
| Assembly ass = Assembly.Load(yyy); | ||
|
|
||
| // Execute some code | ||
| Type mainType = ass.GetType("Entry"); | ||
| mainType.GetMethod("Main").Invoke(null, null); | ||
| // First load | ||
| Assembly ass = Assembly.Load(yyy); | ||
|
|
||
| // Execute some code | ||
| Type mainType = ass.GetType("Entry"); | ||
| mainType.GetMethod("Main").Invoke(null, null); | ||
|
|
||
| // First unload | ||
| // The printObjectReferenceLink parameter is true, which means that when the unloading fails, a detailed reference chain log of illegal objects will be printed, which is convenient for developers to locate where illegal references are maintained. | ||
| // It is recommended to set it to true only during the development period and change it to false after the official launch | ||
| if (!RuntimeApi.TryUnloadAssembly(ass, true)) | ||
| { | ||
| throw new Exception("unload fail"); | ||
| } | ||
|
|
||
| // Second load | ||
| Assembly newAss = Assembly.Load(yyy); | ||
|
|
||
| // Execute some code | ||
| Type mainType = ass.GetType("Entry"); | ||
| mainType.GetMethod("Main").Invoke(null, null); | ||
|
|
||
| // Second uninstall | ||
| if (!RuntimeApi.TryUnloadAssembly(ass, true)) | ||
| { | ||
| throw new Exception("unload fail"); | ||
| } | ||
| ``` | ||
|
|
||
| ### ForceUnloadAssembly | ||
|
|
||
| Force uninstallation, even if there are references to objects in the uninstalled assembly in the AppDomain. Returning true means there is no problem, and returning false means that an illegal reference was detected during the uninstallation process. If false is returned, it may crash after running for a period of time. Use this operation with caution, and it is recommended to communicate with official technical support in detail. | ||
|
|
||
| ```csharp | ||
|
|
||
| // Load for the first time | ||
| Assembly ass = Assembly.Load(yyy); | ||
|
|
||
| // Execute some code | ||
| Type mainType = ass.GetType("Entry"); | ||
| mainType.GetMethod("Main").Invoke(null, null); | ||
|
|
||
| // First unload | ||
| RuntimeApi.UnloadAssembly(ass); | ||
| // Uninstall for the first time | ||
| // The ignoreObjectReferenceValidation parameter is true, which means that illegal object references are not checked during the uninstall process, which can shorten the uninstall time. However, it is recommended to use false regardless of the development period or the official release | ||
| // The printObjectReferenceLink parameter is true, which means that when the uninstall fails, a detailed illegal object reference chain log will be printed, which is convenient for developers to locate where the illegal reference is maintained. It is recommended to set it to true only during the development period and change it to false after the official launch | ||
| if (!RuntimeApi.ForceUnloadAssembly(ass, false, true)) | ||
| { | ||
| throw new Exception("unload fail"); | ||
| } | ||
|
|
||
| // Second load | ||
| Assembly newAss = Assembly.Load(yyy); | ||
| // Second load | ||
| Assembly newAss = Assembly.Load(yyy); | ||
|
|
||
| // Execute some code | ||
| Type mainType = ass.GetType("Entry"); | ||
| mainType.GetMethod("Main").Invoke(null, null); | ||
| // Execute some code | ||
| Type mainType = ass.GetType("Entry"); | ||
| mainType.GetMethod("Main").Invoke(null, null); | ||
|
|
||
| // Second unload | ||
| RuntimeApi.UnloadAssembly(ass); | ||
| // Second uninstall | ||
| if (!RuntimeApi.ForceUnloadAssembly(ass, false, true)) | ||
| { | ||
| throw new Exception("unload fail"); | ||
| } | ||
| ``` | ||
|
|
||
| ## Notes | ||
|
|
||
| - async or coroutine functions easily hold references to unloaded assembly code on other threads, so make sure to clean up all async or coroutine functions before unloading. | ||
| - UI OnClick or various callback events easily hold references to unloaded assembly, so make sure to clean them up properly. | ||
| - Events or other registrations to the global scope can accidentally hold references to unloaded assembly, so make sure to clean them up properly. | ||
| - Based on the logs of illegal references printed in RuntimeApi.UnloadAssembly, clean up all illegal references in the code. | ||
| - Async or coroutines can easily implicitly keep references to the uninstalled assembly code in other threads. Please be sure to clean up all asynchronous or coroutine functions before uninstalling | ||
| - UI OnClick or various callback events can easily keep references to the uninstalled assembly, so be sure to clean them up | ||
| - Registering to global events or other heightening can easily accidentally keep references to uninstalled assemblies, so be sure to clean them up. | ||
| - Clean up illegal references in the code according to the illegal reference logs printed during the uninstall process |