Skip to content

Add guides for iOS home screen widgets and App Intents#3216

Open
jfversluis wants to merge 3 commits intomainfrom
apple-platform-guides
Open

Add guides for iOS home screen widgets and App Intents#3216
jfversluis wants to merge 3 commits intomainfrom
apple-platform-guides

Conversation

@jfversluis
Copy link
Member

@jfversluis jfversluis commented Mar 6, 2026 •
edited by github-actions bot
Loading

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

@jfversluis
Add guides for iOS widgets and App Intents in .NET MAUI
397726e 
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>
@jfversluis jfversluis requested a review from a team as a code owner March 6, 2026 20:18
@learn-build-service-prod
Copy link
Contributor

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

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
Copy link
Contributor

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

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.

@jfversluis
Polish guides with 5 rounds of multi-persona review
acfce86 
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
Copy link
Contributor

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

Learn Build status updates of commit acfce86:

✅ Validation status: passed

File Status Preview URL Details
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
Copy link
Contributor

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

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.

@jfversluis jfversluis requested a review from Redth March 7, 2026 09:50
@jfversluis
Add Xcode project creation steps and blog post reference
9a10e19 
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>
@jfversluis jfversluis mentioned this pull request Mar 9, 2026
Closed
@learn-build-service-prod
Copy link
Contributor

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

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
Copy link
Contributor

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

Learn Build status updates of commit 9a10e19:

✅ Validation status: passed

File Status Preview URL Details
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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Redth Redth Awaiting requested review from Redth

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jfversluis