多目标项目中Android端Xamarin Forms自定义渲染器被忽略问题

安全阿岳

2026-8-14

问题描述

我创建了一个面向netstandard、xamarin.ios和monodroid10的多目标项目，本地构建时Debug和Release模式下双平台均正常工作。但流水线构建Release模式时，Android应用的自定义渲染器被忽略，控件使用默认渲染器。

我想了解MSBuild中是否存在因构建配置导致渲染器未编译或运行时被忽略的因素？

相关信息

AssemblyInfo文件夹包含各平台的ExportRenderer导入，每个自定义渲染器均实现了ExportRenderer；
库的静态初始化器在Xamarin.Forms.Init()调用前执行；
应用程序的链接器设置为仅SDK程序集（<AndroidLinkMode>SdkOnly</AndroidLinkMode>）；
链接器已跳过该多目标程序集（<AndroidLinkSkip>MultiTargetAssemblyName</AndroidLinkSkip>）；
控件使用对应基类的默认Xamarin渲染器，无崩溃仅UX异常；
iOS端在Debug/Release及CI构建下均正常，仅Android端出问题；
多目标项目使用MSBuild.Sdk.Extras/3.0.44 SDK。

进一步排查发现，MSBuild构建时Android项目使用的是该多目标程序集的netstandard2.0版本，且出现命名空间错误：

/Users/runner/work/1/s/Test.Test.Mobile/Test.Test.Mobile.Android/Renderers/ControlLibrary/LibraryButtonRenderer.cs(3,38): error CS0234: The type or namespace name 'Android' does not exist in the namespace 'Test.Test.Mobile.Controls' (are you missing an assembly reference?) [/Users/runner/work/1/s/Test.Test.Mobile/Test.Test.Mobile.Android/Test.Test.Mobile.Android.csproj]

为何构建代理会在MonoDroid10.0项目中使用共享库版本？

解决方案与分析

核心原因

使用MSBuild.Sdk.Extras的多目标项目在CI环境中，构建代理未正确匹配MonoDroid10.0目标框架的输出，导致Android应用错误引用了netstandard2.0版本的程序集。由于netstandard版本不包含Android平台专属的Android命名空间代码，不仅会触发编译错误，还会导致自定义渲染器因未被正确编译/加载而被忽略，最终控件使用默认渲染器。

修复步骤

显式指定Android项目引用多目标项目的MonoDroid输出
在Android应用的.csproj中修改项目引用，强制指定目标框架为monoandroid10.0，避免自动 fallback 到netstandard版本：

<ProjectReference Include="..\YourMultiTargetLib\YourMultiTargetLib.csproj">
  <Project>{YourLibProjectGuid}</Project>
  <Name>YourMultiTargetLib</Name>
  <SetTargetFramework>TargetFramework=monoandroid10.0</SetTargetFramework>
</ProjectReference>

验证多目标项目的框架配置
确认多目标项目的.csproj中正确声明了所有目标框架，且无错误的输出过滤规则：

<PropertyGroup>
  <TargetFrameworks>netstandard2.0;xamarinios10;monoandroid10.0</TargetFrameworks>
  <SdkName>MSBuild.Sdk.Extras</SdkName>
  <SdkVersion>3.0.44</SdkVersion>
</PropertyGroup>

检查CI环境的Android SDK完整性
在流水线脚本中添加步骤，确认构建代理已安装MonoDroid10.0 SDK组件，缺失该组件会导致MSBuild无法找到对应目标框架的输出，被迫引用netstandard版本：
```
# GitHub Actions示例：验证MonoDroid10.0组件
- name: Validate Android SDK Components
  run: |
    $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --list | grep monoandroid10.0
```

确保链接器配置未被覆盖
检查Android项目的.csproj，确认Release模式下的链接器配置未被条件性覆盖：

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  <AndroidLinkMode>SdkOnly</AndroidLinkMode>
  <AndroidLinkSkip>MultiTargetAssemblyName</AndroidLinkSkip>
</PropertyGroup>

额外排查方向

检查多目标项目中Android平台代码的条件编译指令，确保monoandroid10.0目标下的专属代码被正确编译；
对齐本地与CI环境的MSBuild版本，版本差异可能导致目标框架解析逻辑不一致。

内容的提问来源于stack exchange，提问作者Burak Kaan Köse

多目标项目中Android端Xamarin Forms自定义渲染器被忽略问题

相关信息 #

核心原因 #

修复步骤 #

额外排查方向 #

相关信息

核心原因

修复步骤

额外排查方向