| name | setup-sample |
| description | Help users set up and run the .NET MAUI cross-platform sample project. Use when asked to run the sample, set up the project, or get started with Nutrient .NET for iOS and Android via MAUI. |
Set Up and Run the MAUI Cross-Platform Sample Project
Guides the user through setting up and running the dotnet-pdf-library-for-mobiles .NET MAUI sample project, which demonstrates Nutrient PDF viewing on Android, iOS, and Mac Catalyst from a single codebase.
Important Rules
- Always check prerequisites first before attempting to build.
- Stop on errors and help the user diagnose before proceeding.
- macOS is required for iOS and Mac Catalyst targets. Android can be built on any OS.
- This project uses NuGet packages directly -- no binding project build is required.
Workflow
Step 1: Check Prerequisites
Verify the development environment is ready:
dotnet --version
dotnet workload list | grep maui
Required:
- .NET SDK 9.0+
- .NET MAUI workload
If the MAUI workload is missing:
dotnet workload install maui
Platform-specific requirements:
For Android:
dotnet workload list | grep android
java -version
adb devices
For iOS (macOS only):
dotnet workload list | grep ios
xcode-select -p
For Mac Catalyst (macOS only):
dotnet workload list | grep maccatalyst
Step 2: Choose Target Platform
Ask the user which platform they want to run on:
- Android - Emulator or connected device
- iOS - Simulator or connected device (macOS only)
- Mac Catalyst - Native macOS app (macOS only)
Step 3: Restore and Build
From the dotnet-pdf-library-for-mobiles/ directory:
For Android:
cd dotnet-pdf-library-for-mobiles
dotnet restore
dotnet build -f net10.0-android
For iOS:
cd dotnet-pdf-library-for-mobiles
dotnet restore
dotnet build -f net10.0-ios
For Mac Catalyst:
cd dotnet-pdf-library-for-mobiles
dotnet restore
dotnet build -f net10.0-maccatalyst
Step 4: Run the App
Android (emulator or device):
cd dotnet-pdf-library-for-mobiles
dotnet build -f net10.0-android -t:Install
Or if the Install target fails (APK can be ~135MB):
adb install -r bin/Debug/net10.0-android/*-Signed.apk
adb shell am start -n com.companyname.dotnetpdflibraryformobiles/crc64*/dotnet_pdf_library_for_mobiles.MainActivity
iOS Simulator:
cd dotnet-pdf-library-for-mobiles
dotnet build -f net10.0-ios -t:Run
Mac Catalyst:
cd dotnet-pdf-library-for-mobiles
dotnet build -f net10.0-maccatalyst -t:Run
Step 5: Configure License Key
The project uses trial mode by default. If the user has a license key, it needs to be set per platform:
Android - In Platforms/Android/MainApplication.cs or Platforms/Android/MainActivity.cs:
PSPDFKit.NutrientGlobal.Initialize(this, licenseKey: "YOUR_LICENSE_KEY");
iOS - In Platforms/iOS/AppDelegate.cs:
PSPDFKit.Model.PSPDFKitGlobal.SetLicenseKey("YOUR_LICENSE_KEY");
Mac Catalyst - In Platforms/MacCatalyst/AppDelegate.cs:
PSPDFKit.Model.PSPDFKitGlobal.SetLicenseKey("YOUR_LICENSE_KEY");
License keys are available from https://my.nutrient.io/.
Step 6: Verify the App Runs
The app should launch with a flyout navigation menu containing:
- Playground - Interactive PDF viewing and testing
- File Picker Example - Open PDF documents from the device
- About - App information
Test opening a document through the file picker to confirm PDF rendering works.
If the app crashes on Android, check logs:
adb logcat -d | grep -iE "AndroidRuntime|MonoDroid|UNHANDLED" | tail -20
Troubleshooting
Build fails with missing workload
dotnet workload install maui
This installs MAUI and all platform workloads (Android, iOS, Mac Catalyst).
NuGet package restore fails
Verify nuget.org is configured:
dotnet nuget list source
Android build fails with "Type X is defined multiple times"
Clean and rebuild:
cd dotnet-pdf-library-for-mobiles
rm -rf bin obj
dotnet restore
dotnet build -f net10.0-android
iOS build fails on non-macOS
iOS and Mac Catalyst targets can only be built on macOS with Xcode installed.
Large APK size on Android
This is expected (~135MB). The Nutrient SDK includes native libraries for multiple ABIs. For production, use <AndroidSupportedAbis> in the .csproj to limit architectures.
Key Files
| File | Purpose |
|---|
dotnet-pdf-library-for-mobiles/dotnet-pdf-library-for-mobiles.csproj | Multi-target MAUI project with NuGet references |
dotnet-pdf-library-for-mobiles/MauiProgram.cs | MAUI app initialization and handler registration |
dotnet-pdf-library-for-mobiles/Platforms/Android/MainActivity.cs | Android entry point |
dotnet-pdf-library-for-mobiles/Platforms/iOS/AppDelegate.cs | iOS entry point |
dotnet-pdf-library-for-mobiles/Platforms/MacCatalyst/AppDelegate.cs | Mac Catalyst entry point |
dotnet-pdf-library-for-mobiles/Views/PdfView.cs | Cross-platform PDF viewer control |
ReadMe.md | Full integration documentation |
