Skip to main content
Version: Next

DHAO Workflow

danger

If you are using HybridCLR version >= v7.7.0, it is recommended to use the MetaVersion Workflow.

The DHAO workflow is the oldest workflow used for DHE hot updates. Before version v7.6.0, only the DHAO workflow was supported.

Principle​

When loading DHE assemblies, it is necessary to know which types and functions have changed in order to decide whether the runtime should call the original AOT code or execute the latest hot-update code through interpretation. This difference calculation relies on the original DHE and the latest DHE assembly. The calculation is very complex and time-consuming, and it is not feasible to perform it in real-time during runtime. Therefore, an offline calculation method is used, and the resulting difference information is saved into a dhao file.

The principle of the DHAO workflow is simple. However, since the dhao file is calculated based on the latest DHE and the original DHE, if there are multiple main packages in the official release, a corresponding dhao file must be generated for each main package. When there are many main packages, this process can become complex and difficult to manage. The MetaVersion Workflow completely solves this pain point.

Basic Concepts​

To understand the DHAO workflow, you need to be familiar with the following terms:

  • AOT Snapshot
  • Inject Rule file
  • manifest.json
  • dhao file
  • spec file

AOT Snapshot​

An AOT Snapshot is a collection of files required to calculate the dhao file. It includes the following:

  • dll file
  • Inject Rule file
  • manifest.json

The AOT Snapshot records the AOT information of the main package, and its core function is to calculate the dhao file required for hot updates.

The directory structure of an AOT Snapshot is as follows:

  AotSnapshotDir
    ├── *.dll
    ├── InjectRules
    └── manifest.json

The AOT Snapshot information is fully determined at the time of main package build. Please add it to your project's version control system.

Inject Rule File​

By default, code is injected at the beginning of almost all DHE functions. Code injection can greatly alleviate the problem of dirty function propagation, but its downside is that it increases code size and introduces a small amount of additional overhead. The Inject Rule file is used to customize code injection rules, allowing certain functions to be excluded from injection. For detailed documentation, see Function Injection Strategy.

manifest.json​

This file records information such as the list of DHE assemblies.

dhao File​

The dhao file records the types and functions that have changed in the DHE assembly. When these changed functions are executed, they will automatically switch to interpreted execution.

The dhao file has a .dhao.bytes suffix.

spec File​

The spec file is a human-readable version of the dhao file. This file is not needed during runtime. It is recommended to add it to your repository, but do not include it in the hot-update resource system, as it serves no purpose there!

Build and Hot-Update Workflow​

  • Build Main Package

    • Export the main package project or directly build the main package.
    • Create an AOT Snapshot.

  • Release Hot Update

    • Compile the hot-update dll.
    • Calculate the dhao file based on the AOT Snapshot and the latest hot-update dll.
    • Add the hot-update dll and dhao file to the hot-update resource system.

Creating an AOT Snapshot​

danger

The dll in the AOT Snapshot must be precisely consistent with the binary code in the built main package. Please create it only after exporting the project or building! Do not use the AOT dll generated by HybridCLR/Generate/All!

Call DhaoWorkflow.CreateAotSnapshot(BuildTarget target, string outputSnapshotDir) to create the AOT Snapshot files.

Please add the AOT Snapshot to version control for future use.

Generating dhao Files​

The generation process is as follows:

  • Use HybridCLR/CompileDll/ActivedBuildTarget to compile the latest hot-update dll.

  • Call DhaoWorkflow.GenerateDhaoFiles(string aotSnapshotDir, string hotUpdateSnapshotDir, string dhaoOutputDir) to generate the dhao file.

    • aotSnapshotDir is the directory of the AOT Snapshot created during the main package build.
    • hotUpdateSnapshotDir is the directory of the latest hot-update dll.
    • dhaoOutputDir is the output directory for the dhao file.

Multi-Platform and Multiple Main Packages​

Due to the implementation principle of dhao, each {main package - platform} combination requires a separate dhao file to be generated whenever a hot update is released.

danger

Merging dhao files will lead to performance degradation. Use this feature with caution!!!

If you find it cumbersome to provide separate dhao files for each main package, you can consider merging all dhao files for the same platform into a single dhao file. This can be done by calling DhaoWorkflow.MergeDhaoFile.

Merging dhao files for all main packages into one has a significant downside. The resulting dhao file will record the union of all type and function changes from the input dhao files. This means that if a function has changed only in an older main package and not in the latest one, the merged dhao file will still mark this function as changed, causing it to be executed in interpreted mode even in the latest main package. This leads to performance degradation.