Add guides for iOS home screen widgets and App Intents by jfversluis · Pull Request #3216 · dotnet/docs-maui

jfversluis · 2026-03-06T20:18:33Z

Two new documentation guides for integrating Apple platform features into .NET MAUI iOS apps, based on Maui.Apple.PlatformFeature.Samples:

iOS home screen widgets (`docs/ios/ios-widgets.md`)

Comprehensive guide covering:

Architecture: SwiftUI widget extension communicating with MAUI app via App Group shared containers
Bidirectional data exchange (app → widget via JSON + WidgetKit reload, widget → app via deep links and AppIntents buttons)
Complete Swift code for widget extension (timeline provider, shared storage, interactive buttons)
C# service layer with platform abstraction and DI
MSBuild integration for automatic widget extension building
Entitlements setup, project configuration, and troubleshooting

App Intents for Siri and Shortcuts (`docs/ios/app-intents.md`)

Comprehensive guide covering:

Three-project architecture (Swift framework → .NET binding library → MAUI app)
Why Swift is required (compile-time metadata extraction)
Bridge protocol pattern (@objc protocol → C# implementation)
AppIntent, AppEntity, and AppEnum definitions
Binding library with <XcodeProject> MSBuild integration
C# bridge implementation with type marshaling
Intent donation for proactive Siri suggestions
Metadata extraction and app bundle configuration

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

Internal previews

📄 File	🔗 Preview link
docs/ios/app-intents.md	docs/ios/app-intents
docs/ios/ios-widgets.md	docs/ios/ios-widgets

Two new documentation guides for integrating Apple platform features: - iOS home screen widgets: SwiftUI widget extensions with App Group shared containers, bidirectional communication, interactive buttons, MSBuild integration, and troubleshooting - App Intents for Siri and Shortcuts: Three-project architecture (Swift framework + binding library + MAUI app), bridge protocol pattern, intent donation, metadata extraction, and build integration Based on: https://github.com/Redth/Maui.Apple.PlatformFeature.Samples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

learn-build-service-prod · 2026-03-06T20:20:06Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-03-06T20:22:03Z

Learn Build status updates of commit 397726e:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
docs/ios/ios-widgets.md	⚠️Warning	View (>=net-maui-8.0)	Details
docs/ios/app-intents.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

docs/ios/ios-widgets.md

Line 749, Column 135: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#sharedstorageeswift--file-io-via-app-group' in 'ios/ios-widgets.md', did you mean '#sharedstorageswift--file-io-via-app-group'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Fixes from review rounds: - Fix C# heading escapes and broken anchors - Fix NSDate <-> DateTime conversions (DateTimeOffset cast) - Fix enum name mismatches (TaskPriorityLevel/TaskCategoryType) - Add missing class declaration for AppIntentsBridgeProvider - Add ITaskService interface, TaskItem model, and C# enum definitions - Add cross-references to existing entitlements/capabilities docs - Add Info.plist URL scheme registration - Add CI/signing/provisioning notes - Add minimum viable implementation tips - Add UserDefaults vs file-based I/O explanation - Add developer portal App Group note - Add Xcode project creation instructions - Add SchemeName and ForceLoad/SmartLink explanations - Fix MSBuild path separators and split PropertyGroup values - Add WidgetCenterProxy package comment Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

learn-build-service-prod · 2026-03-06T20:55:32Z

Learn Build status updates of commit acfce86:

✅ Validation status: passed

File	Status	Preview URL
docs/ios/app-intents.md	✅Succeeded	View (>=net-maui-8.0)
docs/ios/ios-widgets.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

learn-build-service-prod · 2026-03-06T20:56:07Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

Pull in step-by-step Xcode widget creation instructions from #3169 and add link to Toine-db's blog post on building iOS widgets with .NET MAUI. Also add widget component descriptions (WidgetBundle, Provider, TimelineEntry, etc.) for developers new to WidgetKit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

learn-build-service-prod · 2026-03-09T09:33:11Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-03-09T09:33:30Z

Learn Build status updates of commit 9a10e19:

✅ Validation status: passed

File	Status	Preview URL
docs/ios/app-intents.md	✅Succeeded	View (>=net-maui-8.0)
docs/ios/ios-widgets.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

Redth · 2026-03-26T15:44:18Z

docs/ios/app-intents.md

+Add this target to your MAUI app's `.csproj`:
+
+```xml
+<Target Name="CopyAppIntentsMetadata" AfterTargets="_CopyResourcesToBundle"


@rolfbjarne should we consider different target here to use? Then also generally speaking, is this concept something we might want to work into the SDK as well?

We have an issue open for it: dotnet/macios#24863

Added [!IMPORTANT] notes in commit 22b980b at both MSBuild target locations in app-intents.md (for _CopyResourcesToBundle, _AppBundlePath, and _BuildXcodeProjects) and ios-widgets.md (for _CompileAppManifest) noting these are internal SDK targets that may change in future releases and that built-in support may come in future SDK versions. The SDK design question about which target to use and whether to build this into the SDK is beyond the scope of the docs — deferring to @rolfbjarne on that.

rolfbjarne · 2026-03-26T16:00:23Z

docs/ios/app-intents.md

+      <ForceLoad>true</ForceLoad>
+      <SmartLink>false</SmartLink>


These two (ForceLoad+SmartLink) should not be necessary.

rolfbjarne · 2026-03-26T16:01:23Z

docs/ios/app-intents.md

+  </ItemGroup>
+
+  <ItemGroup>
+    <XcodeProject Include="../YourSwiftFramework/YourSwiftFramework.xcodeproj">


Note that XcodeProject only works when building on a Mac, it doesn't work when building from Windows.

rolfbjarne · 2026-03-26T16:06:24Z

docs/ios/app-intents.md

+<Target Name="CopyAppIntentsMetadata" AfterTargets="_CopyResourcesToBundle"
+        Condition="$(TargetFramework.Contains('-ios'))">
+  <PropertyGroup>
+    <_MetadataSrc>$(MSBuildProjectDirectory)/../YourBindingLibrary/$(IntermediateOutputPath)Metadata.appintents</_MetadataSrc>
+    <_MetadataDst>$(_AppBundlePath)/Metadata.appintents/</_MetadataDst>
+  </PropertyGroup>
+  <ItemGroup>
+    <_MetadataFiles
+      Include="$(_MetadataSrc)/**/*"
+      Condition="Exists('$(_MetadataSrc)')" />
+  </ItemGroup>
+  <Copy
+    SourceFiles="@(_MetadataFiles)"
+    DestinationFolder="$(_MetadataDst)%(RecursiveDir)"
+    Condition="@(_MetadataFiles->Count()) > 0" />
+</Target>


There's no need to copy manually to the app bundle, just add whatever you want in the app bundle to @(BundleResource): https://gist.github.com/rolfbjarne/038d82de755e0485266864a1b43b35d4

rolfbjarne · 2026-03-26T16:09:08Z

docs/ios/ios-widgets.md

+
+```xml
+<Target Name="BuildWidgetExtension"
+        BeforeTargets="_CompileAppManifest"


CollectAppManifests is a public target:

Suggested change

BeforeTargets="_CompileAppManifest"

BeforeTargets="CollectAppManifests"

rolfbjarne · 2026-03-26T16:10:25Z

docs/ios/ios-widgets.md

+
+### Simulator testing
+
+When testing on the simulator, you may need to re-sign the app after building to apply entitlements correctly:


Why is that? This sounds like something isn't configured correctly.

rolfbjarne · 2026-03-26T16:10:50Z

docs/ios/app-intents.md

+Add this target to your MAUI app's `.csproj`:
+
+```xml
+<Target Name="CopyAppIntentsMetadata" AfterTargets="_CopyResourcesToBundle"


We have an issue open for it: dotnet/macios#24863

jfversluis · 2026-03-27T13:11:16Z

@copilot address all comments

Agent-Logs-Url: https://github.com/dotnet/docs-maui/sessions/fa7b5693-6eea-4183-9cd8-dca2ec3ddea2 Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Copilot · 2026-03-27T13:14:50Z

@copilot address all comments

Addressed in commit 22b980b. Added [!IMPORTANT] cautionary notes about the internal SDK MSBuild targets referenced in both guides. The comment from @Redth about SDK design (whether to use a different target or build this into the SDK) is beyond docs scope — left for @rolfbjarne.

learn-build-service-prod · 2026-03-27T13:15:33Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-03-27T13:15:45Z

Learn Build status updates of commit 22b980b:

✅ Validation status: passed

File	Status	Preview URL
docs/ios/app-intents.md	✅Succeeded	View (>=net-maui-8.0)
docs/ios/ios-widgets.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

jfversluis requested a review from a team as a code owner March 6, 2026 20:18

jfversluis requested a review from Redth March 7, 2026 09:50

jfversluis mentioned this pull request Mar 9, 2026

Add documentation for bundling Swift widgets with .NET MAUI iOS apps #3169

Closed

Redth reviewed Mar 26, 2026

View reviewed changes

rolfbjarne reviewed Mar 26, 2026

View reviewed changes

Copilot started work on behalf of jfversluis March 27, 2026 13:11 View session

Add cautionary notes about internal SDK MSBuild targets that may change

22b980b

Agent-Logs-Url: https://github.com/dotnet/docs-maui/sessions/fa7b5693-6eea-4183-9cd8-dca2ec3ddea2 Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

Copilot finished work on behalf of jfversluis March 27, 2026 13:15

	BeforeTargets="_CompileAppManifest"
	BeforeTargets="CollectAppManifests"


		### Simulator testing

		When testing on the simulator, you may need to re-sign the app after building to apply entitlements correctly:

Conversation

jfversluis commented Mar 6, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

iOS home screen widgets (docs/ios/ios-widgets.md)

App Intents for Siri and Shortcuts (docs/ios/app-intents.md)

Internal previews

Uh oh!

learn-build-service-prod bot commented Mar 6, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod bot commented Mar 6, 2026

⚠️ Validation status: warnings

Uh oh!

learn-build-service-prod bot commented Mar 6, 2026

✅ Validation status: passed

Uh oh!

learn-build-service-prod bot commented Mar 6, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod bot commented Mar 9, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod bot commented Mar 9, 2026

✅ Validation status: passed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jfversluis commented Mar 27, 2026

Uh oh!

Copilot AI commented Mar 27, 2026

Uh oh!

learn-build-service-prod bot commented Mar 27, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod bot commented Mar 27, 2026

✅ Validation status: passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jfversluis commented Mar 6, 2026 •

edited by github-actions bot

Loading

iOS home screen widgets (`docs/ios/ios-widgets.md`)

App Intents for Siri and Shortcuts (`docs/ios/app-intents.md`)