.NET MAUI XAML 源生成器诊断规则完全指南MAUIG/MAUIX 前缀编译期诊断清单AnalyzerReleases.Unshipped 解析【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui本文基于 .NET MAUI 仓库中 AnalyzerReleases.Unshipped.md 这份诊断规则发布清单系统梳理 XAML 源生成器XAML Source Generator在编译期抛出的全部 32 条诊断规则。你将掌握每条规则的 ID 语义、所属类别XamlParsing / XamlInflation、严重级别、触发场景与修复方法并能理解这些诊断与仓库内 Descriptors.cs、资源消息模板及单元测试的对应关系——无论是排查 XAML 编译错误、阅读源码生成日志还是参与 MAUI 本身开发这份清单都是权威索引。一、背景AnalyzerReleases 文件是什么AnalyzerReleases.Unshipped.md与同目录的 AnalyzerReleases.Shipped.md 是 Roslyn 分析器/源生成器的发布跟踪Release Tracking约定文件前者登记尚未随 NuGet 正式发布的新增规则后者记录已发布规则。两个文件在 Controls.SourceGen.csproj 中以AdditionalFiles形式参与编译由 Roslyn 的Microsoft.CodeAnalysis.AnalyzersRelease Tracking 分析器RS 系列规则校验确保每条诊断 ID 都有完整声明、不会出现重复或缺失。ItemGroup AdditionalFiles IncludeAnalyzerReleases.Shipped.md / AdditionalFiles IncludeAnalyzerReleases.Unshipped.md / /ItemGroup文件采用固定表格格式每行声明一条规则Rule ID | Category | Severity | Notes --------|----------|----------|------- MAUIG1001 | XamlParsing | Error | XamlParsingFailed四个字段的含义分别是字段说明Rule ID诊断唯一标识。MAUIG前缀代表 Generic/XAML 通用诊断MAUIX前缀代表 XAML 相关诊断Category诊断类别。XamlParsing表示 XAML 文本解析阶段XamlInflation表示将解析树膨胀为对象图、解析符号与绑定阶段Severity严重级别Error编译错误/Warning警告/Info信息Notes备注指向 Descriptors.cs 中的描述符字段或诊断主题名二、规则总览32 条诊断全清单以下为 AnalyzerReleases.Unshipped.md 的完整内容按文档原序整理。后文将按主题分组逐条讲解。Rule ID | Category | Severity | Notes --------|----------|----------|------- MAUIG1001 | XamlParsing | Error | XamlParsingFailed MAUIG1002 | XamlParsing | Error | AmbiguousType MAUIG1003 | XamlParsing | Error | ExpressionNotClosed MAUIG1010 | XamlParsing | Error | ConversionFailed MAUIX2000 | XamlInflation | Error | TypeResolutionFailed MAUIX2001 | XamlInflation | Error | Descriptors MAUIX2002 | XamlInflation | Error | Descriptors MAUIX2003 | XamlInflation | Error | Descriptors MAUIX2004 | XamlInflation | Error | Descriptors MAUIX2005 | XamlInflation | Warning | Descriptors MAUIX2006 | XamlParsing | Warning | PropertyElementWithAttribute MAUIX2014 | XamlInflation | Error | MissingEventHandler MAUIG2024 | XamlInflation | Warning | BindingWithXDataTypeFromOuterScope MAUIG2041 | XamlInflation | Error | BindingIndexerNotClosed MAUIG2042 | XamlInflation | Error | BindingIndexerEmpty MAUIG2043 | XamlInflation | Error | BindingIndexerTypeUnsupported MAUIG2045 | XamlInflation | Warning | BindingPropertyNotFound MAUIG2064 | XamlInflation | Error | NamescopeDuplicate MAUIX2007 | XamlParsing | Warning | AmbiguousExpressionOrMarkup MAUIX2008 | XamlParsing | Error | AmbiguousMemberExpression MAUIX2009 | XamlParsing | Error | MemberNotFound MAUIX2010 | XamlParsing | Info | ExpressionNotSettable MAUIX2011 | XamlParsing | Warning | AmbiguousMemberWithStaticType MAUIX2012 | XamlParsing | Error | CSharpExpressionsRequirePreviewFeatures MAUIX2013 | XamlParsing | Error | AsyncLambdaNotSupported可以看到严重级别分布Error 17 条、Warning 7 条、Info 1 条MAUIX2010。绝大多数解析与符号解析失败都是硬错误直接阻断编译而部分歧义与能力边界问题设计为警告或信息保证尽量生成可运行代码。三、XamlParsing 类别解析阶段诊断MAUIG1001–MAUIG1010XamlParsing 类别对应 XAML 文本被解析为节点树阶段。诊断描述符统一定义在 Descriptors.cs 的Descriptors静态类中消息文案来自 MauiGResources.resx。MAUIG1001 XamlParsingFailed —— XAML 解析失败所有解析器未能消化 XAML 文本的兜底错误消息格式为An error occured while parsing Xaml: {0}.。典型触发点包括XAML 文件缺少x:Class特性源码在 CodeBehindCodeWriter.cs 中直接报告Xaml file {path} does not have a Class attributeXAML 中使用了{Binding}但找不到BindingExtension见 CompiledBindingMarkup.cs解析异常被 GeneratorHelpers.cs 捕获后以该 ID 上报。对应测试见 XmlParserErrorTests.cs 与 SourceGenXamlCodeBehindTests.cs。MAUIG1002 AmbiguousType —— 类型歧义当 XAML 中引用的类型名可同时匹配多个类型例如不同命名空间下的同名类型时触发级别为 Error。修复方式是使用完整的xmlns前缀限定例如将{local:MyType}写为{ns1:MyType}。MAUIG1003 ExpressionNotClosed —— 表达式未闭合消息为Expression must end with }.即花括号表达式markup extension 或 C# 表达式缺少右花括号。例如Text{Binding Name会触发此错误。检查点在于表达式以{开头必须以}结尾。MAUIG1010 ConversionFailed —— 字符串到类型转换失败这是覆盖面最广的一条规则XAML 属性值本质是字符串需经类型转换器转为目标类型转换失败统一报MAUIG1010。在 Descriptors.cs 中它被复用了十余次每个具体类型有专属消息模板全部集中在 MauiGResources.resx目标类型期望格式resx 原文Rectx, y, w, hPointx, yThicknessh, v或l, t, r, b或lCornerRadiustl, tr, bl, br或lEasingLinear,SinOut,CubicInOut,BounceOut,SpringIn等枚举名FlexBasisAuto或n%、nn 为数值FlowDirectionrtl,ltr,inherit,MatchParent,LeftToRight,RightToLeftGridLength*,n*,Auto或nListstringx, y, zColumnDefinitionCollection / RowDefinitionCollection*,n*,Auto,n的组合逗号分隔LayoutOptionsStart,Center,End,Fill上述转换逻辑的实现分布在 TypeConverters 目录下如 RectConverter.cs、GridLengthConverter.cs、EasingConverter.cs 等注册中心是 TypeConverterRegistry.cs。例如!-- 错误GridLength 期望 *、n*、Auto 或数值 -- Grid ColumnDefinitionsa,b,c修复为ColumnDefinitions*,2*,Auto即可消除 MAUIG1010。四、XamlInflation 类别符号解析与对象图构建诊断MAUIX2000–MAUIX2005XamlInflation 阶段将解析好的节点树转换为可执行的构建代码涉及类型/成员/事件查找、资源字典与命名空间检查。这一批描述符同样在 Descriptors.cs 定义。规则 ID描述符消息含义修复方向MAUIX2000 TypeResolutionFailedTypeResolutionCannot resolve type {0}.无法按 xmlns 类型名解析出 CLR 类型检查 xmlns 声明、类型所在程序集引用、类型名拼写MAUIX2001DuplicateTypeErrorMultiple Types found for {0}.同类型名映射到多个类型使用更具体的 xmlns 前缀消除歧义MAUIX2002MemberResolutionNo accessible property, BindableProperty, or event found for {0}, or mismatching type between value and property.属性/BindableProperty/事件均不可访问或值与属性类型不匹配核对成员名与可访问性public、值类型与属性类型一致性MAUIX2003MethodResolutionNo method found for {0}.找不到对应方法/构造函数核对方法签名、可见性与所在类型MAUIX2004DuplicateKeyInRDduplicate key in resource dictionary资源字典键重复检查 [ResourceDictionary] 中重复的x:KeyMAUIX2005WarningRequiredProperty目标属性带 C#required关键字XAML 对其支持有限消息原文提示{0} has the required keyword. Support for this in XAML is limited at the moment, avoid using it. Were still doing a best effort to provide a value.其中 MAUIX2005 是典型的软失败设计required成员在 XAML 中的赋值属于尽力而为源码生成器仍会尝试提供值因此只报 Warning 不阻断编译。类型解析失败的示例!-- x:DataType 指向的类型不存在或拼写错误 -- ContentPage x:DataTypelocal:MisspelledViewModel编译器将报 MAUIX2000Cannot resolve type local:MisspelledViewModel.。符号查找核心逻辑在 MemberResolver.cs该文件中有 9 处诊断上报点与 XmlTypeExtensions.cs。五、绑定编译诊断MAUIG2024 与 MAUIG2041–MAUIG2045这组规则专门针对**编译绑定Compiled Binding**的编译期检查。源码注释明确指出 MAUIG2041–MAUIG2045 与旧 XAML 编译器XamlC的XC0041–XC0045一一对应见 Descriptors.cs其消息模板在 MauiGResources.resx 中均以Binding: ...开头触发逻辑集中在 CompiledBindingMarkup.cs。MAUIG2041 / MAUIG2042 / MAUIG2043 —— 绑定索引器语法与类型规则消息场景示例MAUIG2041 BindingIndexerNotClosedBinding: Indexer did not contain closing bracket.{Binding Items[0}缺少]MAUIG2042 BindingIndexerEmptyBinding: Indexer did not contain arguments.{Binding Items[]}索引器为空MAUIG2043 BindingIndexerTypeUnsupportedBinding: Unsupported indexer index type: {0}.索引键类型不受支持如非字符串/数值类型上报位置在 CompiledBindingMarkup.cs 的索引器解析逻辑中{0}填充实际的索引类型名。MAUIG2045 BindingPropertyNotFoundWarning—— 绑定属性未找到回退反射绑定这是设计意图非常明确的一条警告。源码注释Descriptors.cs说明之所以是 Warning 而非 Error是因为 MAUI 源生成器不一定能看到由其他源生成器如 CommunityToolkit.Mvvm 的[ObservableProperty]生成的属性。虽然可能是拼写错误但也可能是运行期才存在的合法属性。此时绑定会回退到较慢的反射式绑定若属性确实存在则仍能正常工作。消息模板为Binding: Property {0} not found on {1}. The binding will use slower reflection-based binding at runtime...实战含义当你看到 MAUIG2045 时先确认属性是否真拼错若属性确实由另一个源生成器生成可将其视为良性告警——代价仅是运行期使用反射绑定而非编译绑定。该诊断的触发与回退路径在 CompiledBindingMarkup.cs 可见。MAUIG2024 BindingWithXDataTypeFromOuterScopeWarning—— x:DataType 来自外部作用域消息提示绑定可能被错误编译因为x:DataType注解来自外层作用域建议为所有 DataTemplate 中的 XAML 元素标注正确的x:DataType。典型场景是在DataTemplate内部使用绑定而未在模板根元素上声明x:DataType导致继承外层类型ListView ItemsSource{Binding Orders} ListView.ItemTemplate DataTemplate !-- 应在此处声明 x:DataTypelocal:Order否则报 MAUIG2024 -- Label Text{Binding Total} / /DataTemplate /ListView.ItemTemplate /ListView修复在DataTemplate根元素上补x:DataType。上报点见 KnownMarkups.cs。MAUIG2064 NamescopeDuplicate —— 命名空间重复消息为An element with the name {0} already exists in this NameScope.即同一 NameScope 内x:Name重复。错误级别的重复命名会导致生成的字段初始化相互覆盖必须修复!-- 两个元素同名触发 MAUIG2064 -- Label x:NameTitle TextA / Button x:NameTitle TextB /六、C# 表达式XAML C# Expressions诊断MAUIX2006–MAUIX2014MAUIX2006–MAUIX2013这组规则服务于 XAML 中直接书写 C# 表达式的实验特性规则语义在 docs/specs/XamlCSharpExpressions.md 中有完整规格说明描述符定义见 Descriptors.cs解析实现见 ExpressionAnalyzer.cs。MAUIX2006 PropertyElementWithAttributeWarning属性元素property element如Label.Text.../Label.Text上不应再出现特性attribute消息原文为Property element has attributes。上报位置在 InitializeComponentCodeWriter.cs。例如!-- 属性元素上带特性触发 MAUIX2006 -- Label.Text Padding5Hello/Label.TextMAUIX2007 AmbiguousExpressionOrMarkupWarning—— 属性与标记扩展重名当裸标识符{Foo}既能匹配标记扩展存在FooExtension又能匹配可解析的 C# 属性时标记扩展优先同时发出警告。消息给出了明确的消歧语法Use {{ {0}}} for the property or {{local:{0}}} for the markup extension.MAUIX2008 AmbiguousMemberExpressionError—— 页面与 BindingContext 成员冲突当{Foo}同时存在于页面类型和 BindingContext 上时报错消息{0} exists on both {1} and {2}. Use this.{0} for the local member or .{0} for the binding.修复方式即二选一Label Text{this.Title} / !-- 明确取页面成员 -- Label Text{.Title} / !-- 明确取 BindingContext 成员 --MAUIX2009 MemberNotFoundError{0} not found on {1} or {2}.表达式引用的成员在页面与 BindingContext 上均不存在。检查成员拼写与可见性。MAUIX2011 AmbiguousMemberWithStaticTypeWarning{0} exists on {1} but is also a well-known static type.成员名与知名静态类型如System.*下的类型冲突用.前缀表示绑定或完全限定静态类型如System.Int32。MAUIX2010 ExpressionNotSettableInfo—— 表达式无法生成 setterExpression {0} cannot generate a setter. Two-way binding to {1} will be one-way.该规则级别为 Info不打断编译。当表达式包含运算符、方法调用或本地捕获即 ExpressionAnalyzer.cs 中IsSettable为 false 的情况无法为双向绑定生成赋值代码绑定自动降级为单向。MAUIX2012 CSharpExpressionsRequirePreviewFeaturesError—— 需要启用预览特性C# 表达式是实验特性未开启时直接报错并给出启用方法在项目文件中添加PropertyGroup EnablePreviewFeaturestrue/EnablePreviewFeatures /PropertyGroup消息原文XAML C# Expressions are an experimental feature. Add EnablePreviewFeaturestrue/EnablePreviewFeatures to your project file to enable them.MAUIX2013 AsyncLambdaNotSupportedError—— 不支持异步 lambda 事件处理事件使用{async (s, e) ...}形式的 lambda 不被支持消息建议改用普通方法处理异步事件!-- 错误触发 MAUIX2013 -- Button Clicked{async (s, e) await LoadAsync()} / !-- 正确改用普通方法 -- Button ClickedOnLoadClicked /async void OnLoadClicked(object? sender, EventArgs e) { await LoadAsync(); }MAUIX2014 MissingEventHandlerError—— 事件处理器缺失Event handler {0} with correct signature not found in type {1}.XAML 中引用的事件处理器在 code-behind 类型中不存在或签名不匹配见 MauiGResources.resx 的MissingEventHandler。七、诊断规则的测试保障这 32 条规则并非纸面清单仓库在 src/Controls/tests/SourceGen.UnitTests 下为它们建立了系统化单元测试BindingDiagnosticsTests.cs覆盖 MAUIG2024/2041/2042/2043/2045 等绑定诊断CSharpExpressionDiagnosticsTests.cs覆盖 MAUIX2007–MAUIX2013 表达式诊断XmlParserErrorTests.cs覆盖 MAUIG1001/MAUIG1003 等解析错误SourceGenXamlCodeBehindTests.cs验证 code-behind 生成与相关诊断。这些测试通过 RoslynCSharpGeneratorDriver直接驱动 Controls.SourceGen.csproj 生成的程序集项目以netstandard2.0为目标、引用Microsoft.CodeAnalysis.CSharp 4.12.0IsRoslynComponenttrue、EnforceExtendedAnalyzerRulestrue对输入 XAML 断言产生预期 ID 的诊断——这意味着新增或修改任何一条诊断规则都必须同步更新 AnalyzerReleases 文件并配套测试这正是 Release Tracking 机制的闭环。八、开发者在项目中的实用建议把严重级别当作契约Error17 条类诊断应在 CI 中保持为零Warning7 条类中 MAUIG2045 可能是良性的外部源生成器属性MAUIX2007/MAUIX2011 则提示你主动消歧用{ ...}、{this.}、{.}或全限定静态类型让意图显式化。善用 Info 级 MAUIX2010它告诉你某处双向绑定静默降级为单向在表单类 UI 中值得关注可通过改写为可赋值表达式消除。启用 C# 表达式前先开预览特性EnablePreviewFeaturestrue/EnablePreviewFeatures是 MAUIX2012 的官方解药但该特性仍处于实验阶段生产项目需自行评估。遇到转换类错误MAUIG1010时对照第五节表格Rect、GridLength、Easing 等类型的期望格式都有明确文案按格式修正字符串即可。通过本文你可以将任意一条 MAUIG/MAUIX 诊断 ID 快速映射到其定义AnalyzerReleases.Unshipped.md、描述符Descriptors.cs、消息模板MauiGResources.resx与实现/测试位置从而在开发与排障中直接定位问题根因。【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 .NET MAUI XAML 源生成器诊断规则完全指南：MAUIG/MAUIX 前缀编译期诊断清单（AnalyzerReleases.Unshipped 解析）
.NET MAUI XAML 源生成器诊断规则完全指南MAUIG/MAUIX 前缀编译期诊断清单AnalyzerReleases.Unshipped 解析【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui本文基于 .NET MAUI 仓库中 AnalyzerReleases.Unshipped.md 这份诊断规则发布清单系统梳理 XAML 源生成器XAML Source Generator在编译期抛出的全部 32 条诊断规则。你将掌握每条规则的 ID 语义、所属类别XamlParsing / XamlInflation、严重级别、触发场景与修复方法并能理解这些诊断与仓库内 Descriptors.cs、资源消息模板及单元测试的对应关系——无论是排查 XAML 编译错误、阅读源码生成日志还是参与 MAUI 本身开发这份清单都是权威索引。一、背景AnalyzerReleases 文件是什么AnalyzerReleases.Unshipped.md与同目录的 AnalyzerReleases.Shipped.md 是 Roslyn 分析器/源生成器的发布跟踪Release Tracking约定文件前者登记尚未随 NuGet 正式发布的新增规则后者记录已发布规则。两个文件在 Controls.SourceGen.csproj 中以AdditionalFiles形式参与编译由 Roslyn 的Microsoft.CodeAnalysis.AnalyzersRelease Tracking 分析器RS 系列规则校验确保每条诊断 ID 都有完整声明、不会出现重复或缺失。ItemGroup AdditionalFiles IncludeAnalyzerReleases.Shipped.md / AdditionalFiles IncludeAnalyzerReleases.Unshipped.md / /ItemGroup文件采用固定表格格式每行声明一条规则Rule ID | Category | Severity | Notes --------|----------|----------|------- MAUIG1001 | XamlParsing | Error | XamlParsingFailed四个字段的含义分别是字段说明Rule ID诊断唯一标识。MAUIG前缀代表 Generic/XAML 通用诊断MAUIX前缀代表 XAML 相关诊断Category诊断类别。XamlParsing表示 XAML 文本解析阶段XamlInflation表示将解析树膨胀为对象图、解析符号与绑定阶段Severity严重级别Error编译错误/Warning警告/Info信息Notes备注指向 Descriptors.cs 中的描述符字段或诊断主题名二、规则总览32 条诊断全清单以下为 AnalyzerReleases.Unshipped.md 的完整内容按文档原序整理。后文将按主题分组逐条讲解。Rule ID | Category | Severity | Notes --------|----------|----------|------- MAUIG1001 | XamlParsing | Error | XamlParsingFailed MAUIG1002 | XamlParsing | Error | AmbiguousType MAUIG1003 | XamlParsing | Error | ExpressionNotClosed MAUIG1010 | XamlParsing | Error | ConversionFailed MAUIX2000 | XamlInflation | Error | TypeResolutionFailed MAUIX2001 | XamlInflation | Error | Descriptors MAUIX2002 | XamlInflation | Error | Descriptors MAUIX2003 | XamlInflation | Error | Descriptors MAUIX2004 | XamlInflation | Error | Descriptors MAUIX2005 | XamlInflation | Warning | Descriptors MAUIX2006 | XamlParsing | Warning | PropertyElementWithAttribute MAUIX2014 | XamlInflation | Error | MissingEventHandler MAUIG2024 | XamlInflation | Warning | BindingWithXDataTypeFromOuterScope MAUIG2041 | XamlInflation | Error | BindingIndexerNotClosed MAUIG2042 | XamlInflation | Error | BindingIndexerEmpty MAUIG2043 | XamlInflation | Error | BindingIndexerTypeUnsupported MAUIG2045 | XamlInflation | Warning | BindingPropertyNotFound MAUIG2064 | XamlInflation | Error | NamescopeDuplicate MAUIX2007 | XamlParsing | Warning | AmbiguousExpressionOrMarkup MAUIX2008 | XamlParsing | Error | AmbiguousMemberExpression MAUIX2009 | XamlParsing | Error | MemberNotFound MAUIX2010 | XamlParsing | Info | ExpressionNotSettable MAUIX2011 | XamlParsing | Warning | AmbiguousMemberWithStaticType MAUIX2012 | XamlParsing | Error | CSharpExpressionsRequirePreviewFeatures MAUIX2013 | XamlParsing | Error | AsyncLambdaNotSupported可以看到严重级别分布Error 17 条、Warning 7 条、Info 1 条MAUIX2010。绝大多数解析与符号解析失败都是硬错误直接阻断编译而部分歧义与能力边界问题设计为警告或信息保证尽量生成可运行代码。三、XamlParsing 类别解析阶段诊断MAUIG1001–MAUIG1010XamlParsing 类别对应 XAML 文本被解析为节点树阶段。诊断描述符统一定义在 Descriptors.cs 的Descriptors静态类中消息文案来自 MauiGResources.resx。MAUIG1001 XamlParsingFailed —— XAML 解析失败所有解析器未能消化 XAML 文本的兜底错误消息格式为An error occured while parsing Xaml: {0}.。典型触发点包括XAML 文件缺少x:Class特性源码在 CodeBehindCodeWriter.cs 中直接报告Xaml file {path} does not have a Class attributeXAML 中使用了{Binding}但找不到BindingExtension见 CompiledBindingMarkup.cs解析异常被 GeneratorHelpers.cs 捕获后以该 ID 上报。对应测试见 XmlParserErrorTests.cs 与 SourceGenXamlCodeBehindTests.cs。MAUIG1002 AmbiguousType —— 类型歧义当 XAML 中引用的类型名可同时匹配多个类型例如不同命名空间下的同名类型时触发级别为 Error。修复方式是使用完整的xmlns前缀限定例如将{local:MyType}写为{ns1:MyType}。MAUIG1003 ExpressionNotClosed —— 表达式未闭合消息为Expression must end with }.即花括号表达式markup extension 或 C# 表达式缺少右花括号。例如Text{Binding Name会触发此错误。检查点在于表达式以{开头必须以}结尾。MAUIG1010 ConversionFailed —— 字符串到类型转换失败这是覆盖面最广的一条规则XAML 属性值本质是字符串需经类型转换器转为目标类型转换失败统一报MAUIG1010。在 Descriptors.cs 中它被复用了十余次每个具体类型有专属消息模板全部集中在 MauiGResources.resx目标类型期望格式resx 原文Rectx, y, w, hPointx, yThicknessh, v或l, t, r, b或lCornerRadiustl, tr, bl, br或lEasingLinear,SinOut,CubicInOut,BounceOut,SpringIn等枚举名FlexBasisAuto或n%、nn 为数值FlowDirectionrtl,ltr,inherit,MatchParent,LeftToRight,RightToLeftGridLength*,n*,Auto或nListstringx, y, zColumnDefinitionCollection / RowDefinitionCollection*,n*,Auto,n的组合逗号分隔LayoutOptionsStart,Center,End,Fill上述转换逻辑的实现分布在 TypeConverters 目录下如 RectConverter.cs、GridLengthConverter.cs、EasingConverter.cs 等注册中心是 TypeConverterRegistry.cs。例如!-- 错误GridLength 期望 *、n*、Auto 或数值 -- Grid ColumnDefinitionsa,b,c修复为ColumnDefinitions*,2*,Auto即可消除 MAUIG1010。四、XamlInflation 类别符号解析与对象图构建诊断MAUIX2000–MAUIX2005XamlInflation 阶段将解析好的节点树转换为可执行的构建代码涉及类型/成员/事件查找、资源字典与命名空间检查。这一批描述符同样在 Descriptors.cs 定义。规则 ID描述符消息含义修复方向MAUIX2000 TypeResolutionFailedTypeResolutionCannot resolve type {0}.无法按 xmlns 类型名解析出 CLR 类型检查 xmlns 声明、类型所在程序集引用、类型名拼写MAUIX2001DuplicateTypeErrorMultiple Types found for {0}.同类型名映射到多个类型使用更具体的 xmlns 前缀消除歧义MAUIX2002MemberResolutionNo accessible property, BindableProperty, or event found for {0}, or mismatching type between value and property.属性/BindableProperty/事件均不可访问或值与属性类型不匹配核对成员名与可访问性public、值类型与属性类型一致性MAUIX2003MethodResolutionNo method found for {0}.找不到对应方法/构造函数核对方法签名、可见性与所在类型MAUIX2004DuplicateKeyInRDduplicate key in resource dictionary资源字典键重复检查 [ResourceDictionary] 中重复的x:KeyMAUIX2005WarningRequiredProperty目标属性带 C#required关键字XAML 对其支持有限消息原文提示{0} has the required keyword. Support for this in XAML is limited at the moment, avoid using it. Were still doing a best effort to provide a value.其中 MAUIX2005 是典型的软失败设计required成员在 XAML 中的赋值属于尽力而为源码生成器仍会尝试提供值因此只报 Warning 不阻断编译。类型解析失败的示例!-- x:DataType 指向的类型不存在或拼写错误 -- ContentPage x:DataTypelocal:MisspelledViewModel编译器将报 MAUIX2000Cannot resolve type local:MisspelledViewModel.。符号查找核心逻辑在 MemberResolver.cs该文件中有 9 处诊断上报点与 XmlTypeExtensions.cs。五、绑定编译诊断MAUIG2024 与 MAUIG2041–MAUIG2045这组规则专门针对**编译绑定Compiled Binding**的编译期检查。源码注释明确指出 MAUIG2041–MAUIG2045 与旧 XAML 编译器XamlC的XC0041–XC0045一一对应见 Descriptors.cs其消息模板在 MauiGResources.resx 中均以Binding: ...开头触发逻辑集中在 CompiledBindingMarkup.cs。MAUIG2041 / MAUIG2042 / MAUIG2043 —— 绑定索引器语法与类型规则消息场景示例MAUIG2041 BindingIndexerNotClosedBinding: Indexer did not contain closing bracket.{Binding Items[0}缺少]MAUIG2042 BindingIndexerEmptyBinding: Indexer did not contain arguments.{Binding Items[]}索引器为空MAUIG2043 BindingIndexerTypeUnsupportedBinding: Unsupported indexer index type: {0}.索引键类型不受支持如非字符串/数值类型上报位置在 CompiledBindingMarkup.cs 的索引器解析逻辑中{0}填充实际的索引类型名。MAUIG2045 BindingPropertyNotFoundWarning—— 绑定属性未找到回退反射绑定这是设计意图非常明确的一条警告。源码注释Descriptors.cs说明之所以是 Warning 而非 Error是因为 MAUI 源生成器不一定能看到由其他源生成器如 CommunityToolkit.Mvvm 的[ObservableProperty]生成的属性。虽然可能是拼写错误但也可能是运行期才存在的合法属性。此时绑定会回退到较慢的反射式绑定若属性确实存在则仍能正常工作。消息模板为Binding: Property {0} not found on {1}. The binding will use slower reflection-based binding at runtime...实战含义当你看到 MAUIG2045 时先确认属性是否真拼错若属性确实由另一个源生成器生成可将其视为良性告警——代价仅是运行期使用反射绑定而非编译绑定。该诊断的触发与回退路径在 CompiledBindingMarkup.cs 可见。MAUIG2024 BindingWithXDataTypeFromOuterScopeWarning—— x:DataType 来自外部作用域消息提示绑定可能被错误编译因为x:DataType注解来自外层作用域建议为所有 DataTemplate 中的 XAML 元素标注正确的x:DataType。典型场景是在DataTemplate内部使用绑定而未在模板根元素上声明x:DataType导致继承外层类型ListView ItemsSource{Binding Orders} ListView.ItemTemplate DataTemplate !-- 应在此处声明 x:DataTypelocal:Order否则报 MAUIG2024 -- Label Text{Binding Total} / /DataTemplate /ListView.ItemTemplate /ListView修复在DataTemplate根元素上补x:DataType。上报点见 KnownMarkups.cs。MAUIG2064 NamescopeDuplicate —— 命名空间重复消息为An element with the name {0} already exists in this NameScope.即同一 NameScope 内x:Name重复。错误级别的重复命名会导致生成的字段初始化相互覆盖必须修复!-- 两个元素同名触发 MAUIG2064 -- Label x:NameTitle TextA / Button x:NameTitle TextB /六、C# 表达式XAML C# Expressions诊断MAUIX2006–MAUIX2014MAUIX2006–MAUIX2013这组规则服务于 XAML 中直接书写 C# 表达式的实验特性规则语义在 docs/specs/XamlCSharpExpressions.md 中有完整规格说明描述符定义见 Descriptors.cs解析实现见 ExpressionAnalyzer.cs。MAUIX2006 PropertyElementWithAttributeWarning属性元素property element如Label.Text.../Label.Text上不应再出现特性attribute消息原文为Property element has attributes。上报位置在 InitializeComponentCodeWriter.cs。例如!-- 属性元素上带特性触发 MAUIX2006 -- Label.Text Padding5Hello/Label.TextMAUIX2007 AmbiguousExpressionOrMarkupWarning—— 属性与标记扩展重名当裸标识符{Foo}既能匹配标记扩展存在FooExtension又能匹配可解析的 C# 属性时标记扩展优先同时发出警告。消息给出了明确的消歧语法Use {{ {0}}} for the property or {{local:{0}}} for the markup extension.MAUIX2008 AmbiguousMemberExpressionError—— 页面与 BindingContext 成员冲突当{Foo}同时存在于页面类型和 BindingContext 上时报错消息{0} exists on both {1} and {2}. Use this.{0} for the local member or .{0} for the binding.修复方式即二选一Label Text{this.Title} / !-- 明确取页面成员 -- Label Text{.Title} / !-- 明确取 BindingContext 成员 --MAUIX2009 MemberNotFoundError{0} not found on {1} or {2}.表达式引用的成员在页面与 BindingContext 上均不存在。检查成员拼写与可见性。MAUIX2011 AmbiguousMemberWithStaticTypeWarning{0} exists on {1} but is also a well-known static type.成员名与知名静态类型如System.*下的类型冲突用.前缀表示绑定或完全限定静态类型如System.Int32。MAUIX2010 ExpressionNotSettableInfo—— 表达式无法生成 setterExpression {0} cannot generate a setter. Two-way binding to {1} will be one-way.该规则级别为 Info不打断编译。当表达式包含运算符、方法调用或本地捕获即 ExpressionAnalyzer.cs 中IsSettable为 false 的情况无法为双向绑定生成赋值代码绑定自动降级为单向。MAUIX2012 CSharpExpressionsRequirePreviewFeaturesError—— 需要启用预览特性C# 表达式是实验特性未开启时直接报错并给出启用方法在项目文件中添加PropertyGroup EnablePreviewFeaturestrue/EnablePreviewFeatures /PropertyGroup消息原文XAML C# Expressions are an experimental feature. Add EnablePreviewFeaturestrue/EnablePreviewFeatures to your project file to enable them.MAUIX2013 AsyncLambdaNotSupportedError—— 不支持异步 lambda 事件处理事件使用{async (s, e) ...}形式的 lambda 不被支持消息建议改用普通方法处理异步事件!-- 错误触发 MAUIX2013 -- Button Clicked{async (s, e) await LoadAsync()} / !-- 正确改用普通方法 -- Button ClickedOnLoadClicked /async void OnLoadClicked(object? sender, EventArgs e) { await LoadAsync(); }MAUIX2014 MissingEventHandlerError—— 事件处理器缺失Event handler {0} with correct signature not found in type {1}.XAML 中引用的事件处理器在 code-behind 类型中不存在或签名不匹配见 MauiGResources.resx 的MissingEventHandler。七、诊断规则的测试保障这 32 条规则并非纸面清单仓库在 src/Controls/tests/SourceGen.UnitTests 下为它们建立了系统化单元测试BindingDiagnosticsTests.cs覆盖 MAUIG2024/2041/2042/2043/2045 等绑定诊断CSharpExpressionDiagnosticsTests.cs覆盖 MAUIX2007–MAUIX2013 表达式诊断XmlParserErrorTests.cs覆盖 MAUIG1001/MAUIG1003 等解析错误SourceGenXamlCodeBehindTests.cs验证 code-behind 生成与相关诊断。这些测试通过 RoslynCSharpGeneratorDriver直接驱动 Controls.SourceGen.csproj 生成的程序集项目以netstandard2.0为目标、引用Microsoft.CodeAnalysis.CSharp 4.12.0IsRoslynComponenttrue、EnforceExtendedAnalyzerRulestrue对输入 XAML 断言产生预期 ID 的诊断——这意味着新增或修改任何一条诊断规则都必须同步更新 AnalyzerReleases 文件并配套测试这正是 Release Tracking 机制的闭环。八、开发者在项目中的实用建议把严重级别当作契约Error17 条类诊断应在 CI 中保持为零Warning7 条类中 MAUIG2045 可能是良性的外部源生成器属性MAUIX2007/MAUIX2011 则提示你主动消歧用{ ...}、{this.}、{.}或全限定静态类型让意图显式化。善用 Info 级 MAUIX2010它告诉你某处双向绑定静默降级为单向在表单类 UI 中值得关注可通过改写为可赋值表达式消除。启用 C# 表达式前先开预览特性EnablePreviewFeaturestrue/EnablePreviewFeatures是 MAUIX2012 的官方解药但该特性仍处于实验阶段生产项目需自行评估。遇到转换类错误MAUIG1010时对照第五节表格Rect、GridLength、Easing 等类型的期望格式都有明确文案按格式修正字符串即可。通过本文你可以将任意一条 MAUIG/MAUIX 诊断 ID 快速映射到其定义AnalyzerReleases.Unshipped.md、描述符Descriptors.cs、消息模板MauiGResources.resx与实现/测试位置从而在开发与排障中直接定位问题根因。【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考