Xamarin.Android绑定项目迁移至.NET 6+的完整指南

Xamarin.Android绑定项目迁移至.NET 6+的完整指南

前言

随着.NET 6的发布，Xamarin.Android绑定项目的结构和配置发生了重大变化。本文将全面解析这些变更，帮助开发者顺利完成迁移工作。我们将从基础概念讲起，逐步深入到高级配置选项，确保您能充分理解并掌握新版本中的绑定项目特性。

绑定项目的新变化

在.NET 6+环境中，绑定项目不再作为一种独立的项目类型存在。现在，您可以使用标准的.NET 6+ Android应用程序或类库项目来完成Java库的绑定工作。

基础项目结构

一个基本的绑定类库项目文件现在看起来与普通类库完全一致：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-android</TargetFramework>
  </PropertyGroup>
</Project>

虽然项目文件简化了，但仍建议为每个需要绑定的Java库创建单独的项目，以保持代码的模块化和可维护性。

不再支持的旧选项

AndroidClassParser选项

jar2xml解析器已被完全移除，现在唯一可用的解析器是class-parse。这个变化带来了多项优势：

• 自动获取类方法的参数名称（如果Java代码使用javac -parameters编译）
• 完整的Kotlin支持
• 静态方法和默认接口方法(DIM)支持
• Java可空引用类型(NRT)注解支持

AndroidCodegenTarget选项

XamarinAndroid代码生成目标已被弃用，现在唯一支持的选项是XAJavaInterop1。如果您在Additions文件中手动编写了与生成代码交互的逻辑，可能需要调整这些代码以适应新的生成模式。

文件包含机制

.NET 6+引入了更智能的默认文件包含机制：

项目目录/
    Transforms/
        Metadata.xml
    foo.jar

系统会自动包含：

• Transforms/*.xml作为转换文件(@(TransformFile))
• .jar和.aar文件作为Android库(@(AndroidLibrary))

排除不需要的文件

如果自动包含机制捕获了不需要的Java库（如构建工具自带的jar文件），可以通过以下方式排除：

<ItemGroup>
  <AndroidLibrary Remove="不需要的路径/gradle-wrapper.jar" />
</ItemGroup>

或者排除整个目录：

<AndroidLibrary Remove="不需要的目录/**/*" />

嵌入Java库的变化

在传统Xamarin.Android中，Java库通常被嵌入到绑定的DLL中。这种做法的缺点是会导致构建速度变慢，因为每次构建都需要解压这些资源。

在.NET 6+中，Java库不再嵌入DLL，而是直接放在DLL旁边。构建系统会自动查找并使用这些文件。

引用方式注意事项

• 使用<PackageReference>或<ProjectReference>：无需额外配置
• 使用<Reference>：必须确保.jar/.aar文件与.dll位于同一目录

迁移时的兼容性考虑

接口常量处理

Java允许在接口中定义常量，传统做法是生成一个包含这些常量的辅助类。现在可以直接在C#接口中定义这些常量，但可能破坏现有代码。

解决方案：设置<AndroidBoundInterfacesContainConstants>false</AndroidBoundInterfacesContainConstants>恢复旧行为。

嵌套接口类型

Java允许在接口中定义嵌套类型，传统做法是将它们提升为顶级类型。现在可以保持嵌套结构，但可能影响现有代码。

解决方案：

1. 全局设置：<AndroidBoundInterfacesContainTypes>false</AndroidBoundInterfacesContainTypes>
2. 单个接口设置：使用metadata中的unnest属性

静态和默认接口方法

Java 8+支持接口中的静态方法和默认方法，传统做法是为静态方法生成辅助类并忽略默认方法。现在可以直接在C#接口中实现这些特性。

解决方案：设置<AndroidBoundInterfacesContainStaticAndDefaultInterfaceMethods>false</AndroidBoundInterfacesContainStaticAndDefaultInterfaceMethods>恢复旧行为。

可空引用类型(NRT)

从Xamarin.Android 11.0开始支持NRT，在.NET 6+中默认禁用。要启用：

<PropertyGroup>
  <Nullable>enable</Nullable>
</PropertyGroup>

Resource.designer.cs生成

传统绑定项目不生成此文件，但.NET 6+类库会生成，可能导致命名冲突。禁用方法：

<PropertyGroup>
  <AndroidGenerateResourceDesigner>false</AndroidGenerateResourceDesigner>
</PropertyGroup>

最佳实践建议

1. 逐步迁移：先在现有项目中测试新选项，再迁移到.NET 6+
2. 模块化设计：为每个Java库维护单独的绑定项目
3. 版本控制：记录所有自定义的metadata转换，便于后续维护
4. 兼容性测试：迁移后全面测试现有应用，确保API行为一致

通过理解这些变化和配置选项，您可以顺利将Xamarin.Android绑定项目迁移到.NET 6+环境，同时保持应用的稳定性和兼容性。