简单聊聊Unity C# 代码中 [NativeMethod]、[NativeProperty]、[NativeHeader] 等特性（Attribute）标记的工作原理-CSDN博客

本文链接：https://blog.csdn.net/qq_33060405/article/details/145398428

下面详细讲解 Unity C# 代码中 [NativeMethod]、[NativeProperty]、[NativeHeader] 等特性（Attribute）标记的工作原理，以及它们如何指定 C++ 端的实现和头文件，并在 Unity 引擎中实现 C# 到 C++ 的桥接。

1. 这些特性是什么？

这些特性是 Unity 自己定义的 C# Attribute，用于标记托管层（C#）代码与原生层（C++）的绑定关系。它们不会直接影响 C# 运行时行为，而是为 Unity 的代码生成工具（BindingsGenerator）提供元数据。

常见的有：

[NativeMethod]：标记 C# 方法/属性，对应 C++ 的方法。
[NativeProperty]：标记 C# 属性，对应 C++ 的字段或属性。
[NativeHeader]：指定 C++ 头文件路径，告诉生成工具需要包含哪个头文件。
[StaticAccessor]、[NativeName] 等：进一步指定 C++ 访问方式或名称。

2. 工作原理详解

2.1 标记阶段

在 Unity 的 C# 源码（如 Camera.bindings.cs）中，开发者会这样写：

[NativeHeader("Runtime/Camera/Camera.h")]
[NativeMethod("Render", IsThreadSafe = false)]
public extern void Render();

extern 说明该方法没有 C# 实现，需由外部（C++）提供。
[NativeHeader] 指定 C++ 头文件路径。
[NativeMethod] 指定 C++ 方法名及其他元数据。

2.2 代码生成阶段

Unity 的BindingsGenerator工具会在引擎构建时扫描所有带有这些特性的 C# 代码，收集元数据，自动生成 glue code（桥接代码），主要包括：

C++ 端的导出函数（通常是 C API 或 C++/CLI）
C# 端的 P/Invoke 或 InternalCall 声明
参数类型、返回值、线程安全等信息

举例：

C# 端声明 public extern void Render();
BindingsGenerator 生成 C++ 端的 void Camera::Render() 导出函数
生成 glue code 负责参数封送、对象查找、异常处理等

2.3 运行时调用

当 C# 代码调用 Camera.Render() 时，CLR 通过 InternalCall 或 P/Invoke 跳转到 glue code。
glue code 再调用 C++ 的 Camera::Render() 实现。
如果有 [NativeHeader]，C++ glue code 会自动包含指定头文件，确保类型和声明一致。

3. 具体特性说明

3.1 [NativeHeader]

[NativeHeader("Runtime/Camera/Camera.h")]

告诉 BindingsGenerator 生成的 C++ glue code 需要 #include "Runtime/Camera/Camera.h"
保证 C++ 端类型声明和实现可见

3.2 [NativeMethod]

[NativeMethod("Render", IsThreadSafe = false)]

"Render" 指定 C++ 端的实际方法名
IsThreadSafe 告诉生成工具该方法是否可在多线程调用
还可指定 ThrowsException、FreeFunction 等参数

3.3 [NativeProperty]

[NativeProperty("FieldOfView", false, TargetType.Field)]
public extern float fieldOfView { get; set; }

"FieldOfView" 指定 C++ 端的字段名
TargetType.Field 指定是字段还是属性

3.4 [StaticAccessor]、[NativeName] 等

[StaticAccessor] 指定静态访问方式（如全局单例、静态类等）
[NativeName] 指定 C++ 端的实际名称（如 C# 名称与 C++ 不一致时）

4. 例子：Camera.bindings.cs 到 C++ 的完整流程

C# 代码：

[NativeHeader("Runtime/Camera/Camera.h")]
[NativeMethod("Render")]
public extern void Render();

BindingsGenerator 生成 glue code：

#include "Runtime/Camera/Camera.h"
extern "C" void Camera_Render(Camera* self) {
    self->Render();
}

C# 调用 Render()，CLR 跳转到 glue code，最终调用 C++ 的 Camera::Render()。

5. 总结

这些特性本质上是元数据，为 Unity 的代码生成工具提供 C# 到 C++ 的映射信息。
它们不会直接影响 C# 运行时，而是在引擎构建时参与 glue code 的自动生成。
这样做的好处是：自动化、类型安全、易于维护，大大减少了手写桥接代码的出错概率。

下面继续深入讲解 Unity 的特性标记（如 [NativeMethod]、[NativeProperty]、[NativeHeader]）的底层工作原理，并补充一些实际开发和源码层面的细节。

6. 特性标记的底层实现细节

6.1 Attribute 的本质

这些特性（Attribute）在 C# 编译后会被保存在程序集（Assembly）的元数据中。
它们不会影响 C# 代码的直接运行，但可以被工具（如 BindingsGenerator）通过反射读取。

6.2 BindingsGenerator 的工作流程

扫描程序集
BindingsGenerator 工具会遍历 UnityEngine.dll、UnityEditor.dll 等程序集，查找所有带有 [NativeMethod]、[NativeProperty] 等特性的成员。
收集元数据
读取特性参数（如 C++ 方法名、头文件路径、线程安全性等），并记录每个 extern 方法/属性的签名。
生成 glue code
- 生成 C++ 端的导出函数（通常是 extern “C” 的 C API，或 C++/CLI 的桥接代码）。
- 生成 C# 端的 InternalCall 或 P/Invoke 声明。
- glue code 负责参数类型转换、对象查找、异常处理等。
集成到引擎
生成的 glue code 会被编译进 Unity 引擎的 C++ 代码库，C# 端则通过 InternalCall/PInvoke 机制调用。

6.3 InternalCall 与 P/Invoke 的区别

InternalCall：Unity 内部的 C# 到 C++ 调用机制，性能高，主要用于引擎核心 API。
P/Invoke：标准的 .NET 跨平台调用机制，主要用于调用外部 DLL（如自定义插件）。

Unity 的 bindings.cs 主要用 InternalCall，效率更高。

7. 特性参数的实际作用

7.1 [NativeMethod] 的参数

Name：C++ 端实际方法名（如 C# 名称与 C++ 不一致时用）。
IsThreadSafe：标记方法是否可多线程调用，生成 glue code 时会加锁或做线程检查。
ThrowsException：标记 C++ 方法是否可能抛出异常，glue code 会捕获并转为 C# 异常。
FreeFunction：标记为全局函数而非成员函数。
HasExplicitThis：标记是否需要显式传递 this 指针。

7.2 [NativeProperty] 的参数

Name：C++ 端字段或属性名。
TargetType：指定是字段（Field）还是属性（Property）。
IsThreadSafe：同上。

7.3 [NativeHeader] 的参数

只需一个参数，指定 C++ 头文件路径，glue code 生成时自动 #include。

8. 典型 glue code 生成示例

假设有如下 C# 代码：

[NativeHeader("Runtime/Camera/Camera.h")]
[NativeMethod("SetFieldOfView", IsThreadSafe = false)]
public extern void SetFieldOfView(float fov);

BindingsGenerator 可能生成如下 C++ glue code：

#include "Runtime/Camera/Camera.h"

extern "C" void Camera_SetFieldOfView(Camera* self, float fov)
{
    self->SetFieldOfView(fov);
}

C# 端调用 SetFieldOfView，CLR 跳转到 Camera_SetFieldOfView，再由 glue code 调用 C++ 的成员函数。

9. 复杂场景下的 glue code 处理

9.1 结构体、数组、委托

结构体参数：glue code 会自动处理内存布局和拷贝。
数组参数：glue code 会传递指针和长度，必要时做类型转换。
委托/回调：glue code 会注册 C# 委托，C++ 端触发时回调到 C#。

9.2 静态方法与全局函数

[FreeFunction] 标记的 C# 方法会绑定到 C++ 的全局函数，而不是类成员。

10. 维护和调试建议

如果你在调试 Unity 源码时遇到 extern 方法，可以通过特性参数快速定位 C++ 实现和头文件。
若 glue code 生成有误，通常是特性参数配置不当或 C++/C# 签名不一致。

11. 设计优势

自动化：大幅减少手写 glue code 的工作量。
类型安全：参数、返回值、线程安全等信息都能自动校验。
易维护：C# 和 C++ 层的 API 变更只需同步特性参数，自动生成 glue code。

12. 参考资料

下面继续深入讲解 Unity 特性标记（如 [NativeMethod]、[NativeProperty]、[NativeHeader]）的底层机制、实际开发中的细节和进阶内容。

13. Unity 特性标记与 C++ 端的自动同步

13.1 C# 与 C++ 的同步机制

Unity 的 C# 层和 C++ 层是分开维护的，但通过这些特性标记，Unity 的自动化工具可以确保两端的 API 始终同步。
当 C# 层的 extern 方法、属性、字段发生变更时，只需调整特性参数，BindingsGenerator 会自动重新生成 glue code。
这样可以极大减少人工同步 C# 和 C++ 代码的出错概率。

13.2 版本兼容与升级

Unity 升级引擎时，C++ 层的 API 变更只需同步更新 C# 层的特性标记，自动生成 glue code，保证兼容性。
这也是 Unity 能够频繁发布新版本、快速修复底层 bug 的重要基础。

14. 特性标记的高级用法

14.1 [NativeConditional]

用于条件编译，只有在满足某些条件时才生成 glue code。

例如：

[NativeConditional("ENABLE_PHYSICS")]
public extern void AddForce(Vector3 force);

只有定义了 ENABLE_PHYSICS 宏时，才会生成对应的 C++ glue code。

14.2 [NativeThrows]

标记 C++ 方法可能抛出异常，glue code 会自动捕获并转为 C# 异常。

例如：

[NativeThrows]
public extern void DangerousOperation();

14.3 [StaticAccessor]

指定静态访问方式，常用于全局单例或静态类。

例如：

[StaticAccessor("GetGlobalManager()", StaticAccessorType.Dot)]
public extern static int GetSomeValue();

14.4 [NativeName]

当 C# 方法名与 C++ 不一致时，强制指定 C++ 端名称。

例如：

[NativeName("SetFOV")]
public extern void SetFieldOfView(float fov);

15. Unity glue code 的类型映射规则

15.1 基本类型

int、float、bool、string 等会自动映射为 C++ 的 int、float、bool、std::string 或 Unity 自己的 String 类型。

15.2 结构体和类

UnityEngine.Vector3、Quaternion、Matrix4x4 等结构体会自动映射为 C++ 端的同名结构体。
UnityEngine.Object 派生类（如 Camera、GameObject）会映射为 C++ 端的指针（如 Camera*）。

15.3 数组和列表

C# 的 T[]、List 会映射为 C++ 的指针和长度，glue code 负责内存管理和类型转换。

15.4 委托和回调

C# 委托会映射为 C++ 的回调指针，glue code 负责注册和触发。

16. Unity glue code 的异常处理

如果 C++ 端抛出异常，glue code 会捕获并转为 C# 的 System.Exception。
这依赖于 [NativeThrows] 或 [NativeMethod(ThrowsException = true)] 标记。
这样可以保证 C# 层不会因为 C++ 崩溃而直接挂掉，而是能捕获到异常并处理。

17. Unity glue code 的线程安全

[NativeMethod(IsThreadSafe = true)] 标记的方法，glue code 会允许在多线程环境下调用。
否则，glue code 可能会加锁或做主线程检查，防止多线程访问引擎核心对象导致崩溃。

18. 实际开发中的调试技巧

18.1 如何定位 C++ 实现

通过 [NativeHeader] 和 [NativeMethod] 的参数，可以直接在 Unity 源码仓库中搜索对应的 C++ 头文件和方法名。
例如，[NativeHeader("Runtime/Camera/Camera.h")]，你可以在 Unity 源码的 Runtime/Camera/Camera.h 文件中找到对应实现。