Skip to content

Commit

Permalink
更新旗舰版文档,包含带校验和不带校验的工作流
Browse files Browse the repository at this point in the history
  • Loading branch information
pirunxi committed Jan 26, 2024
1 parent aa22600 commit 3ac6125
Show file tree
Hide file tree
Showing 8 changed files with 1,356 additions and 492 deletions.
59 changes: 52 additions & 7 deletions docs/business/ultimate/manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,14 +92,25 @@ dhao文件是DHE技术的核心概念。dhao文件中包含了离线计算好的

## 代码中使用

运行时,完成热更新后,对于每个dhe程序集,调用 `RuntimeApi::LoadDifferentialHybridAssembly` 加载热更新assembly。
运行时,完成热更新后,对于每个dhe程序集,调用 `RuntimeApi::LoadDifferentialHybridAssembly``RuntimeApi::LoadDifferentialHybridAssemblyUnchecked` 加载热更新assembly。

注意事项:

- 要按照assembly的依赖顺序加载 差分混合执行 assembly。
- 如果某个程序集未发生改变,dhao字段可以传null,但此时一定要使用打包时生成的AOT dll,而不能使用通过`HybridCLR/CompileDll/xxx`命令生成的热更新dll。
- DHE程序集本身已经包含了元数据,即使未开启完全泛型共享时也**不要对DHE程序集进行补充元数据**,补充了也会失败,其他非DHE的AOT程序集可以照常补充元数据。


`RuntimeApi::LoadDifferentialHybridAssembly`为带校验的工作流,需要传入原始dhe dll的md5及当前dhe dll的md5,与dhao文件中保存的md5进行对比。
为了originalDllMd5和currentDllMd5参数,极大增加了工作流的复杂度。

:::tip

推荐初学者在demo项目中使用带校验的工作流,熟悉工作流后在正式项目中使用不带校验的工作流。
:::

### 带校验的 `RuntimeApi::LoadDifferentialHybridAssembly`

```csharp title="加载DHE程序集"

public static string CreateMD5Hash(byte[] bytes)
Expand All @@ -126,13 +137,34 @@ void LoadDifferentialHybridAssembly(string assemblyName, string originalDllMd5)
}
```

### 不带校验的 `RuntimeApi::LoadDifferentialHybridAssemblyUnchecked`

:::warning

`RuntimeApi::LoadDifferentialHybridAssemblyUnchecked` 函数不需要提供originalDllMd5和currentDllMd5参数,使用较为便利,但强烈不建议使用。
实践中经常由于操作失误,使用了错误的原始dll或者热更新dll,导致生成了错误的dhao文件。使用了错误的dhao文件,轻则运行出错,重则进程崩溃。
使用不带校验的工作流,请务必保证原始dhe dll、当前dhe dll和dhao文件的一致性。如果不一致,轻则运行出错,重则进程崩溃。

:::

```csharp title="加载DHE程序集"

///
/// originalDllMd5 从构建时生成的`{manifest}`清单文件中获得,此清单文件由开发者自己生成
///
void LoadDifferentialHybridAssembly(string assemblyName)
{
LoadImageErrorCode err = RuntimeApi.LoadDifferentialHybridAssemblyUnchecked(dllBytes, dhaoBytes);
if (err == LoadImageErrorCode.OK)
{
Debug.Log($"LoadDifferentialHybridAssembly {assName} OK");
}
else
{
Debug.LogError($"LoadDifferentialHybridAssembly {assName} failed, err={err}");
}
}
```


## 配置函数注入策略

:::tip
Expand All @@ -159,9 +191,16 @@ DHE技术中与构建相关的文件为dhe dll文件和对应的dhao文件。

- 将构建后生成的裁剪AOT dll作为 首包(没有任何改动)的dhe dll
- 使用`HybridCLR.Editor.DHE.BuildUtils.GenerateUnchangedDHAODatas`生成首包的dhao文件
- 为dhe文件生成一个至少包含 assemblyName,md5的`{manifest}`清单文件(由开发者自由决定怎么实现),因为`RuntimeApi.LoadDifferentialHybridAssembly`需要提供dhe dll的原始md5

如果使用带校验的工作流,则执行以下操作:

- 为dhe dll生成一个至少包含 assemblyName,md5的`{manifest}`清单文件(由开发者自由决定怎么实现),因为`RuntimeApi.LoadDifferentialHybridAssembly`需要提供dhe dll的原始md5
- 将 dhe dll、dhao文件及`{manifest}`文件加入热更新资源管理系统

如果使用不带校验的工作流,则执行以下操作:

- 将 dhe dll、dhao文件加入热更新资源管理系统

如果想随包携带首包的dhe dll和dhao文件,请先导出工程,再按照上面的步骤生成dhe dll和dhao文件,再将它们加入到导出工程中。


Expand All @@ -181,11 +220,17 @@ DHE技术中与构建相关的文件为dhe dll文件和对应的dhao文件。

#### 构建主包

- 将构建后生成的裁剪AOT dll作为 首包(没有任何改动)的dhe dll
- 将构建后生成的裁剪AOT dll作为 原始dhe dll
- 使用`HybridCLR.Editor.DHE.BuildUtils.EncryptDllAndGenerateUnchangedDHAODatas`生成首包的dhao文件及加密后的dhe dll文件
- 将 dhe dll和dhao文件加入热更新资源管理系统

如果想随包携带首包的dhe dll和dhao文件,请先导出工程,再按照上面的步骤生成dhe dll和dhao文件,再将它们加入到导出工程中。
如果使用带校验的工作流,则执行以下操作:

- 为dhe dll生成一个至少包含 assemblyName,md5的`{manifest}`清单文件(由开发者自由决定怎么实现),因为`RuntimeApi.LoadDifferentialHybridAssembly`需要提供dhe dll的原始md5
- 将 加密后的dhe dll、dhao文件及`{manifest}`文件加入热更新资源管理系统

如果使用不带校验的工作流,则执行以下操作:

- 将 加密后的dhe dll、dhao文件加入热更新资源管理系统


#### 热更新
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,21 @@
# 快速上手
# 快速上手(带校验的工作流)

本教程引导从空项目开始体验HybridCLR热更新。出于简化起见,只演示BuildTarget为**Windows****MacOS** Standalone平台的情况。
请在Standalone平台上正确跑通热更新流程后再自行尝试Android、iOS平台的热更新,它们的流程非常相似。

旗舰版本使用难度跟社区版本相似,大多数原理相同,建议先熟悉社区版本后再尝试旗舰版本。

自v5.0.0版本起,同时支持带校验的`RuntimeApi.LoadDifferentialHybridAssembly`工作流和不带校验的`RuntimeApi.LoadDifferentialHybridAssemblyUnchecked`工作流。
本文档介绍带校验的工作流。

:::tip

实践中不带校验的工作流会简单很多,不必传递originalDllMd5和currentDllMd5参数,所以省去了工作流中保存或者计算dll md5的过程。
但要求开发者确保aot dll、hot update dll、dhao文件的一致性。
推荐初学者在demo项目中使用带校验的工作流,熟悉工作流后在正式项目中使用不带校验的工作流。

:::

## 体验目标

- 创建热更新程序集
Expand Down Expand Up @@ -347,10 +358,9 @@ public class Hello

为了简化演示,我们不通过http服务器下载HotUpdate.dll,而是直接将HotUpdate.dll放到StreamingAssets目录下。

HybridCLR是原生运行时实现,因此调用`Assembly Assembly.Load(byte[])`即可加载热更新程序集。

创建`Assets/LoadDll.cs`脚本,然后**在main场景中创建一个GameObject对象,挂载LoadDll脚本**


```csharp
using HybridCLR;
using System;
Expand Down
Loading

0 comments on commit 3ac6125

Please sign in to comment.