Xamarin.Forms多目标项目XAML控件InitializeComponent歧义问题求助

我之前也碰到过一模一样的情况——在SDK风格的多目标Xamarin.Forms项目里用XAML写自定义控件时，动不动就弹出InitializeComponent()方法歧义的错误。说到底就是咱们关闭了默认的编译和资源嵌入规则后，手动配置的规则没把XAML文件和对应的代码隐藏文件正确关联起来，导致编译器要么生成了重复的方法定义，要么找不到正确的生成文件。

下面是修改后的完整.csproj配置，我会逐点解释关键修改：

<Project Sdk="MSBuild.Sdk.Extras/2.0.54">
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;xamarinios10;monoandroid9.0;</TargetFrameworks>
    <!-- 保留手动控制项，确保只编译我们指定的文件 -->
    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
    <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
    <!-- 开启设计时XAML构建，确保生成的代码和代码隐藏文件正确关联 -->
    <XamarinFormsDesignTimeBuild>true</XamarinFormsDesignTimeBuild>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Xamarin.Forms" Version="4.6.0.800" />
    <PackageReference Include="Xamarin.Essentials" Version="1.5.3" />
    <!-- 包含Shared目录下所有.cs文件（包括XAML的代码隐藏文件*.xaml.cs） -->
    <Compile Include="**\Shared\*.cs" />
    <!-- 仅在对应平台编译专属代码 -->
    <Compile Include="**\iOS\*.cs" Condition=" $(TargetFramework.StartsWith('xamarinios')) " />
    <Compile Include="**\Android\*.cs" Condition=" $(TargetFramework.StartsWith('monoandroid')) " />
  </ItemGroup>

  <ItemGroup>
    <!-- 批量包含Shared目录下所有XAML文件，配置生成规则 -->
    <EmbeddedResource Include="Shared\*.xaml">
      <Generator>MSBuild:UpdateDesignTimeXaml</Generator>
      <SubType>Designer</SubType>
      <!-- 明确关联XAML和对应的代码隐藏文件，避免生成重复代码 -->
      <DependentUpon>%(Filename).xaml.cs</DependentUpon>
    </EmbeddedResource>
  </ItemGroup>
</Project>

关键修改说明： #

• 添加XamarinFormsDesignTimeBuild属性：这个属性是核心，它确保设计时XAML能生成正确的临时代码，从根源上避免编译时的方法歧义。
• 统一Compile项配置：把平台专属代码的编译规则合并到同一个ItemGroup，同时确保所有Shared目录下的.cs文件（包括.xaml.cs）都被正确纳入编译范围。
• 优化EmbeddedResource配置：
  • 用Shared\*.xaml代替单个文件，后续添加新XAML控件时不用重复修改配置；
  • 添加SubType>Designer</SubType，让IDE识别这是设计文件，自动关联到对应的代码隐藏文件；
  • 添加DependentUpon，明确XAML文件和代码隐藏文件的对应关系，确保生成的.g.cs文件不会出现重复定义。

如果你不想手动管理所有编译项，也可以开启默认编译规则，通过Exclude来排除不需要的文件，这样更省心：

<Project Sdk="MSBuild.Sdk.Extras/2.0.54">
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;xamarinios10;monoandroid9.0;</TargetFrameworks>
    <EnableDefaultCompileItems>true</EnableDefaultCompileItems>
    <EnableDefaultEmbeddedResourceItems>true</EnableDefaultEmbeddedResourceItems>
    <XamarinFormsDesignTimeBuild>true</XamarinFormsDesignTimeBuild>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Xamarin.Forms" Version="4.6.0.800" />
    <PackageReference Include="Xamarin.Essentials" Version="1.5.3" />
    <!-- 非对应平台时，排除专属代码文件 -->
    <Compile Remove="**\iOS\*.cs" Condition=" !$(TargetFramework.StartsWith('xamarinios')) " />
    <Compile Remove="**\Android\*.cs" Condition=" !$(TargetFramework.StartsWith('monoandroid')) " />
  </ItemGroup>

  <ItemGroup>
    <EmbeddedResource Include="Shared\*.xaml">
      <Generator>MSBuild:UpdateDesignTimeXaml</Generator>
      <SubType>Designer</SubType>
      <DependentUpon>%(Filename).xaml.cs</DependentUpon>
    </EmbeddedResource>
  </ItemGroup>
</Project>

这样配置后，编译器就能正确识别XAML和对应的代码隐藏文件，不会再出现InitializeComponent()方法的歧义错误了。

内容的提问来源于stack exchange，提问作者Arvis