Unity3D：API更新程序
推荐：将NSDT场景编辑器加入你的3D工具链
3D工具集：NSDT简石数字孪生
API更新程序
为了提高可用性和性能，Unity 可能会更改类、函数和属性（API）的工作方式。有时，这些改进可能会在从一个主要 Unity 版本移动到另一个主要 Unity 版本时引入重大更改。
为了最大程度地减少中断性更改的影响，API 更新程序会识别并更新脚本和程序集中的过时代码。
API 更新程序由 ScriptUpdater 和 AssemblyUpdater 组成，它们分别负责更新源代码（脚本）和程序集（dll 文件）。
注意：API 更新程序只能修复 API 中的某些错误和警告。这些在控制台消息中指示为“UnityUpgradable”。您必须手动解决 API 更新程序无法处理的其他错误或警告。
使用 API 更新程序
触发脚本编译时，API 更新程序会自动运行。例如，当您执行以下操作时，会发生这种情况：
- 打开一个项目。
- 导入包。
- 保存对脚本所做的更改。
API 更新程序提供更新它检测到的任何过时代码。如果接受，它将使用建议的 API 更新版本重写任何过时的代码。
例如，API 更新程序会将以下过时的语句从：
light.color = Color.red;
自：
GetComponent<Light>().color = Color.red;
以下步骤描述了 Unity 触发脚本编译时 API 更新程序的工作流程：
- Unity 会触发脚本编译。
- API 更新程序检查它可以处理的可更新编译器错误或警告。
- 如果未找到任何错误或警告，则该过程结束。
- 如果发现任何错误或警告，它会显示一个提供自动更新的对话框。
在让 API 更新程序更新脚本或程序集之前，关闭编辑器并备份项目。重新打开项目时，Unity 会编译脚本并触发 API 更新程序。
- 如果接受更新，API 更新程序将更新同一编译单元中的所有脚本。
- API 更新程序重复此过程，直到它不再检测到它可以处理的错误或警告。
如果具有过时代码的脚本属于不同的编译过程（例如编辑器脚本），则更新程序可以运行多次。
如果您不允许 API 更新程序更新脚本，控制台将显示任何脚本错误或警告。API 更新程序可以解决的错误或警告在消息中显示 （UnityUpgradable）。
如果您的脚本存在阻止 API 更新程序成功运行的其他错误，控制台将显示一条消息通知您。必须先解决这些错误，然后 API 更新程序才能完成更新。
与 API 更新程序相关的命令行参数
从命令行以批处理模式运行 Unity 时，请使用该选项运行 API 更新程序。有关详细信息，请参阅命令行参数。-accept-apiupdate
日志记录
API 更新程序将它对任何程序集所做的更改记录到编辑器日志中。要控制记录的信息量，请将UNITY_APIUPDATER_LOG_THRESHOLD环境变量设置为所需的日志阈值，然后启动 Unity。例如：
窗户：
c:> set UNITY_APIUPDATER_LOG_THRESHOLD=Debug
c:> \path\to\unity\Unity.exe
在 Linux 上：
$ export UNITY_APIUPDATER_LOG_THRESHOLD=Debug
$ /path/to/unity/Unity
在 Mac 上：
$ export UNITY_APIUPDATER_LOG_THRESHOLD=Debug
$ /path/to/unity/Unity
注意：您还可以使用版本控制来查看 API 更新程序对项目脚本所做的更改。
组装更新程序完成后，编辑器.log将显示更改。例如：
[AssemblyUpdater] Property access to 'UnityEngine.Rigidbody
UnityEngine.GameObject::get_rigidbody()' in 'System.Void
Test.ClassReferencingObsoleteUnityAPIThroughEditorAssembly::Run()' replaced with 'T
UnityEngine.GameObject::GetComponent<UnityEngine.Rigidbody>()'.
下表描述了环境变量的值：UNITY_APIUPDATER_LOG_THRESHOLD
| 日志阈值 | 描述 |
|---|---|
| 错误（默认值） | API 更新程序仅记录错误消息。当 API 更新程序无法应用特定更新时，将记录错误消息，这需要您采取纠正措施（通常要求原始程序集作者提供程序集的更新版本）。 |
| 警告 | API 更新程序会记录警告和错误消息。当 API 更新程序应用用户可能需要查看的更改时，将记录警告消息。 |
| 信息 | API 更新程序记录信息性、警告和错误消息。信息消息包括程序集更新程序应用的更新。 |
| 调试 | API 更新程序记录所有消息。这对于故障排除非常有用，例如，如果要向 Unity 报告的 API 更新程序出现问题。 |
故障排除
API 更新失败。检查以前的控制台消息。
API 更新程序无法更新所有过时的代码。如果更新程序无法保存其更改，例如，如果用户对脚本具有只读权限，则可能会发生这种情况。
检查控制台中前面的行，以查看更新过程中出现的任何问题。
- 2018–07–31 页面已修订
- Unity 2017.2 中添加了“accept-apiupdate”命令行选项
- 在 Unity 2018.3 版本中改进了 AssemblyUpdater 日志记录
此文由3D建模学习工作室整理翻译，转载请注明出处！