[apidiff] Add nullability support to mono-api-info and mono-api-html by rolfbjarne · Pull Request #25603 · dotnet/macios

rolfbjarne · 2026-06-01T16:34:50Z

mono-api-info now reads NullableAttribute and NullableContextAttribute
metadata from assemblies and appends '?' to type names for nullable
reference types in the XML output (parameters, return types, properties,
fields, and events).

mono-api-html now:

Strips nullability annotations when matching methods (so nullability-
only changes don't cause false removed/added entries)
Detects nullability-only changes and renders them under a separate
'(nullability)' subsection header to indicate they are non-breaking
Handles the '?' suffix in type name resolution (GetTypeName)

mono-api-info now reads NullableAttribute and NullableContextAttribute metadata from assemblies and appends '?' to type names for nullable reference types in the XML output (parameters, return types, properties, fields, and events). mono-api-html now: - Strips nullability annotations when matching methods (so nullability- only changes don't cause false removed/added entries) - Detects nullability-only changes and renders them under a separate '(nullability)' subsection header to indicate they are non-breaking - Handles the '?' suffix in type name resolution (GetTypeName) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds nullable reference type awareness to the apidiff tooling. mono-api-info now reads NullableAttribute / NullableContextAttribute metadata and emits a trailing ? on type names for nullable reference types (parameters, return types, properties, fields, events). mono-api-html strips these annotations for member matching to avoid false add/remove pairs and groups nullability-only differences under a separate (nullability) subsection so they are clearly identified as non-breaking.

Changes:

mono-api-info: new NullabilityHelper reads NullableAttribute / NullableContextAttribute and appends ? to nullable reference type names.
mono-api-html: Helper.StripNullability / DiffersOnlyByNullability, plus GetTypeName handling of the trailing ?.
mono-api-html: MemberComparer.Modify splits modifications into regular and (nullability) buckets; MethodComparer.Find matches return types ignoring nullability.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/api-tools/mono-api-info/mono-api-info.cs	Emits `?` suffix on nullable reference type names for fields, properties, events, return types and parameters via new `NullabilityHelper`.
tools/api-tools/mono-api-html/Helpers.cs	`GetTypeName` recognizes trailing `?`; new `StripNullability` / `DiffersOnlyByNullability` helpers.
tools/api-tools/mono-api-html/MethodComparer.cs	Compare return types after stripping nullability so nullability-only changes don't break method matching.
tools/api-tools/mono-api-html/MemberComparer.cs	Splits modified members into normal and `(nullability)` sections.
tools/api-tools/mono-api-html/ApiChange.cs	Flags an `ApiChange` as nullability-only by recursively comparing source/target attributes and children.

+		static byte? GetNullableContextFromParent (ICustomAttributeProvider? provider)
+		{
+			if (provider is MethodDefinition method)
+				return GetNullableContextFlag (method.DeclaringType);
+			if (provider is PropertyDefinition prop)
+				return GetNullableContextFlag (prop.DeclaringType);
+			if (provider is FieldDefinition field)
+				return GetNullableContextFlag (field.DeclaringType);
+			if (provider is EventDefinition evt)
+				return GetNullableContextFlag (evt.DeclaringType);
+			if (provider is TypeDefinition type && type.DeclaringType is not null)
+				return GetNullableContextFlag (type.DeclaringType);
+			return null;
+		}


rolfbjarne · 2026-06-02T10:20:28Z

/azp run

azure-pipelines · 2026-06-02T10:20:57Z

Azure Pipelines successfully started running 3 pipeline(s).

rolfbjarne · 2026-06-03T07:33:38Z

/azp run

azure-pipelines · 2026-06-03T07:34:05Z

Azure Pipelines successfully started running 3 pipeline(s).

Instead of highlighting the entire type name as modified, only the added or removed '?' character is rendered with the change span. For example: NSRunLoopMode[]? (added nullability) NSRunLoopMode[]? (removed nullability) Dictionary<string?, string?> (mixed) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

rolfbjarne · 2026-06-03T10:20:08Z

/azp run

azure-pipelines · 2026-06-03T10:20:38Z

Azure Pipelines successfully started running 3 pipeline(s).

This reverts commit 24d1d58.

rolfbjarne · 2026-06-03T13:07:03Z

/review

github-actions · 2026-06-03T13:07:39Z

✅ .NET for Apple Platforms PR Reviewer completed successfully!

rolfbjarne · 2026-06-03T13:08:59Z

/azp run

azure-pipelines · 2026-06-03T13:09:34Z

Azure Pipelines successfully started running 3 pipeline(s).

github-actions

Review Summary

This PR adds nullability annotation support to the API diff tooling — a valuable improvement for tracking C# nullable reference type changes.

⚠️ Issues Found

Performance (3 warnings)

Character-by-character string allocations in AppendNullabilityModified (lines 67, 92, 102). These allocations add up when processing large API surfaces. Append chars directly or batch substrings.

Correctness (1 warning)

IsNullabilitySuffix only checks the first character of HTML entities like & and >, which may not correctly identify nullability suffixes in HTML-encoded contexts.

Code organization (2 suggestions)

Potential duplication between XElement-level and string-level DiffersOnlyByNullability methods
Incomplete comment about generic parameter handling in IsNullableReferenceType

✅ Strengths

Clean separation: Nullability-only changes are rendered under "(nullability)" subsections, clearly distinguishing them from breaking changes
Backward compatible: Proper stripping of nullability annotations during method matching prevents false positive removed/added entries
Comprehensive coverage: Handles fields, properties, events, method return types, and parameters
Well-structured: The NullabilityHelper class provides clear single-purpose methods with good separation of concerns

Verdict

The core logic is sound and the feature works as described. The performance concerns are worth addressing to ensure good behavior on large assemblies, and the HTML entity check should be validated. Otherwise, this is a solid enhancement to the API diff infrastructure.

CI is still running — ensure all checks pass before merge.

Generated by .NET for Apple Platforms PR Reviewer for issue #25603 · sonnet45 1.1M
_{Comment /review to run again}

- Fix DiffersOnlyByNullability to always check children even when parent attributes differ by nullability (prevents misclassifying non-nullability child changes as nullability-only) - Add module-level NullableContextAttribute fallback for types that rely on assembly-wide nullable context - Fix per-character string allocations: add TextChunk.Append(char) overload and use it instead of ToString() per character - Improve IsNullabilitySuffix comment to document HTML entity assumption - Fix misleading comment in IsNullableReferenceType Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

rolfbjarne · 2026-06-03T13:50:32Z

/azp run

azure-pipelines · 2026-06-03T13:51:03Z

Azure Pipelines successfully started running 3 pipeline(s).

vs-mobiletools-engineering-service2 · 2026-06-03T14:05:46Z

✅ [PR Build #ec909e3] Build passed (Detect API changes) ✅

Pipeline on Agent
Hash: ec909e312a35dc37796948c5b395f3574186d17b [PR build]

vs-mobiletools-engineering-service2 · 2026-06-03T14:09:32Z

✅ [PR Build #ec909e3] Build passed (Build packages) ✅

Pipeline on Agent
Hash: ec909e312a35dc37796948c5b395f3574186d17b [PR build]

vs-mobiletools-engineering-service2 · 2026-06-03T14:18:36Z

✅ API diff for current PR / commit

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

✅ API diff vs stable

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

ℹ️ Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent
Hash: ec909e312a35dc37796948c5b395f3574186d17b [PR build]

vs-mobiletools-engineering-service2 · 2026-06-03T14:31:50Z

✅ [PR Build #ec909e3] Build passed (Build macOS tests) ✅

Pipeline on Agent
Hash: ec909e312a35dc37796948c5b395f3574186d17b [PR build]

vs-mobiletools-engineering-service2 · 2026-06-03T18:47:31Z

🚀 [CI Build #ec909e3] Test results 🚀

Test results

✅ All tests passed on VSTS: test results.

🎉 All 193 tests passed 🎉

Tests counts

✅ cecil: All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (iOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (MacCatalyst): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (macOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (Multiple platforms): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (tvOS): All 1 tests passed. Html Report (VSDrops) Download
✅ framework: All 2 tests passed. Html Report (VSDrops) Download
✅ fsharp: All 4 tests passed. Html Report (VSDrops) Download
✅ generator: All 5 tests passed. Html Report (VSDrops) Download
✅ interdependent-binding-projects: All 4 tests passed. Html Report (VSDrops) Download
✅ introspection: All 6 tests passed. Html Report (VSDrops) Download
✅ linker (iOS): All 11 tests passed. Html Report (VSDrops) Download
✅ linker (MacCatalyst): All 11 tests passed. Html Report (VSDrops) Download
✅ linker (macOS): All 11 tests passed. Html Report (VSDrops) Download
✅ linker (tvOS): All 11 tests passed. Html Report (VSDrops) Download
✅ monotouch (iOS): All 20 tests passed. Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 23 tests passed. [attempt 2] Html Report (VSDrops) Download
✅ monotouch (macOS): All 23 tests passed. [attempt 2] Html Report (VSDrops) Download
✅ monotouch (tvOS): All 20 tests passed. Html Report (VSDrops) Download
✅ msbuild: All 2 tests passed. Html Report (VSDrops) Download
✅ sharpie: All 1 tests passed. Html Report (VSDrops) Download
✅ windows: All 3 tests passed. Html Report (VSDrops) Download
✅ xcframework: All 4 tests passed. [attempt 3] Html Report (VSDrops) Download
✅ xtro: All 1 tests passed. Html Report (VSDrops) Download

macOS tests

✅ Tests on macOS Monterey (12): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Ventura (13): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sonoma (14): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sequoia (15): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Tahoe (26): All 5 tests passed. Html Report (VSDrops) Download

Linux Build Verification

✅ Linux build succeeded

Pipeline on Agent
Hash: ec909e312a35dc37796948c5b395f3574186d17b [PR build]

rolfbjarne requested a review from Copilot June 1, 2026 16:34

Copilot started reviewing on behalf of rolfbjarne June 1, 2026 16:35 View session

Copilot AI reviewed Jun 1, 2026

View reviewed changes