# macOS Installation Commands

## Xcode

### Install Xcode

**Do not install Xcode from the App Store** — it can auto-update to a version newer than what .NET MAUI supports.

Download a specific version from [Apple Developer Downloads](https://developer.apple.com/download/all/), matching the `xcode.version` range from WorkloadDependencies.json.

> **Note**: Downloading from Apple Developer Downloads requires signing in with an Apple ID (with two-factor authentication). Xcode is approximately 12 GB and may take 30 minutes or more to download. The agent cannot automate this — tell the user to download Xcode manually, set expectations for the download size and wait time, then continue with the remaining steps.

### Install Command Line Tools

```bash
xcode-select --install
```

### List Xcode Installations

```bash
ls -d /Applications/Xcode*.app 2>/dev/null
xcodebuild -version
xcode-select -p
```

### Set Active Xcode Version

```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

### Accept Xcode License

```bash
sudo xcodebuild -license accept
```

### Verify Xcode Installation

```bash
xcodebuild -version
xcrun simctl list devices available
```

---

## iOS Simulators

Only create a simulator if none exist. Prefer a recent iPhone device type with the latest available runtime.

```bash
# Check if any simulators already exist
xcrun simctl list devices available

# If none exist, find the latest iPhone device type and runtime
xcrun simctl list devicetypes | grep iPhone
xcrun simctl list runtimes | grep iOS

# Create one using a chosen device type and runtime from the lists above
# Replace <DEVICE_TYPE_ID> and <RUNTIME_ID> with identifiers from the commands above
xcrun simctl create "My iPhone Simulator" "<DEVICE_TYPE_ID>" "<RUNTIME_ID>"
```

# Windows Installation Commands

## Windows SDK

The Windows SDK is required for WinUI 3 / Windows targets. It is typically installed automatically as part of the .NET MAUI workload or via the Visual Studio Installer.

For standalone installation, see: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/

# Installation Commands Reference

Commands for installing and validating .NET MAUI development dependencies.

**See also platform-specific references:**
- macOS: `installation-commands-macos.md`
- Windows: `installation-commands-windows.md`

---

**Important**: All specific versions shown below are placeholders. Always discover the actual versions to use:
- **SDK/Workload versions**: Query releases-index.json and NuGet APIs (see `workload-dependencies-discovery.md`)
- **Android SDK packages**: From `androidsdk` in WorkloadDependencies.json
- **JDK version**: From `jdk.version` in WorkloadDependencies.json

## .NET SDK

For installation instructions, see the official docs: https://dotnet.microsoft.com/download

For scripted/CI installs, use the [dotnet-install scripts](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-install-script).

---

## .NET Workloads

**Always use explicit workload set version** to ensure consistent, reproducible installs.

First, find the latest workload set version:
```bash
# Use the CLI to discover the latest workload version for your SDK
dotnet workload search version --format json --take 1
# Returns: [{"workloadVersion":"10.0.103"}]
```

Then install with explicit version:
```bash
# Full MAUI installation (recommended)
dotnet workload install maui --version $WORKLOAD_VERSION

# Individual workloads
dotnet workload install android --version $WORKLOAD_VERSION
dotnet workload install ios --version $WORKLOAD_VERSION           # macOS only meaningful
dotnet workload install maccatalyst --version $WORKLOAD_VERSION   # macOS only meaningful

# Multiple at once
dotnet workload install maui android ios maccatalyst --version $WORKLOAD_VERSION
```

### List Installed Workloads

```bash
dotnet workload list
```

### ⚠️ Commands to Avoid

**Never use these commands** - they can cause version inconsistencies:
- ❌ `dotnet workload update` - Can introduce mixed versions
- ❌ `dotnet workload repair` - May not fix version issues
- ❌ `dotnet workload install` without `--version` - Gets unpredictable versions

**Instead**: Always reinstall with explicit `--version` to fix workload issues.

---

## Java JDK (Microsoft OpenJDK ONLY)

**CRITICAL: Only Microsoft Build of OpenJDK is supported.** Other JDK vendors (Oracle, Azul, Amazon Corretto, Temurin, etc.) are NOT supported for .NET MAUI development.

> Use the JDK version recommended by WorkloadDependencies.json (`jdk.recommendedVersion`), ensuring it satisfies the `jdk.version` range. Do not hardcode JDK versions.

See `microsoft-openjdk.md` for detection paths, identification, and JAVA_HOME guidance.

For installation instructions, see the official docs: https://learn.microsoft.com/en-us/java/openjdk/install

After installing, verify it is Microsoft OpenJDK:
```bash
# MUST show "Microsoft" in output
java -version
```

---

## Android SDK

### Detecting Existing Android SDK

```bash
# Check common environment variables
echo $ANDROID_HOME
echo $ANDROID_SDK_ROOT

# Known SDK locations by platform:
# macOS: ~/Library/Android/sdk
# Linux: ~/Android/Sdk or /usr/lib/android-sdk
# Windows: $env:LOCALAPPDATA\Android\Sdk

# Check known paths directly
ls -d ~/Library/Android/sdk 2>/dev/null    # macOS
ls -d ~/Android/Sdk 2>/dev/null            # Linux

# Check if sdkmanager is available
# macOS/Linux
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --version

# Windows (PowerShell)
& "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" --version
```

### Installing Android SDK Command-Line Tools

If no Android SDK exists, download the command-line tools:

1. Download from: https://developer.android.com/studio#command-line-tools-only
2. Extract to your SDK root:

```bash
# macOS/Linux
export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"  # macOS
# export ANDROID_SDK_ROOT="$HOME/Android/Sdk"        # Linux
mkdir -p "$ANDROID_SDK_ROOT/cmdline-tools"
# Extract downloaded zip, move contents to:
# $ANDROID_SDK_ROOT/cmdline-tools/latest/
```

```powershell
# Windows
$env:ANDROID_SDK_ROOT = "$env:LOCALAPPDATA\Android\Sdk"
New-Item -ItemType Directory -Force -Path "$env:ANDROID_SDK_ROOT\cmdline-tools"
# Extract downloaded zip, move contents to:
# $env:ANDROID_SDK_ROOT\cmdline-tools\latest\
```

### Install Required Packages with sdkmanager

Get exact versions from WorkloadDependencies.json (`androidsdk.packages`, `androidsdk.buildToolsVersion`, `androidsdk.apiLevel`).

```bash
# macOS/Linux
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager "platform-tools"
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager "build-tools;$BUILD_TOOLS_VERSION"
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager "platforms;android-$API_LEVEL"
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager "cmdline-tools;$CMDLINE_TOOLS_VERSION"

# Accept all licenses
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --licenses
```

```powershell
# Windows
& "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" "platform-tools"
& "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" "build-tools;$BUILD_TOOLS_VERSION"
& "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" "platforms;android-$API_LEVEL"
& "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" "cmdline-tools;$CMDLINE_TOOLS_VERSION"

# Accept all licenses
& "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" --licenses
```

### Verify Android SDK

```bash
# Check ADB
adb --version

# List installed packages (macOS/Linux)
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --list_installed

# List installed packages (Windows)
# & "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" --list_installed
```

# Microsoft OpenJDK Requirements

.NET MAUI requires **Microsoft Build of OpenJDK** for Android development. Other JDK distributions (Oracle, Azul, Amazon Corretto, etc.) are **not supported**.

> Use the JDK version recommended by WorkloadDependencies.json (`jdk.recommendedVersion`), ensuring it satisfies the `jdk.version` range. Do not hardcode JDK versions.

## Why Microsoft OpenJDK Only?

- Tested and validated with .NET MAUI toolchain
- Consistent behavior across all platforms
- Long-term support with security updates
- Official recommendation from Microsoft documentation

## Identifying Microsoft OpenJDK

Run `java -version`. Microsoft OpenJDK output contains `Microsoft` in the runtime line:

```
openjdk version "21.0.6" 2025-01-21 LTS
OpenJDK Runtime Environment Microsoft-XXXXXXX (build 21.0.6+7-LTS)
OpenJDK 64-Bit Server VM Microsoft-XXXXXXX (build 21.0.6+7-LTS, mixed mode, sharing)
```

If the output does NOT contain "Microsoft", the wrong JDK is installed or selected.

## Known Installation Paths

These paths are useful for detecting whether Microsoft OpenJDK is already installed.

### macOS

```
/Library/Java/JavaVirtualMachines/microsoft-{VERSION}.jdk/Contents/Home
```

Detection:
```bash
ls -d /Library/Java/JavaVirtualMachines/microsoft-*.jdk 2>/dev/null
/usr/libexec/java_home -V 2>&1 | grep -i microsoft
```

### Windows

```
C:\Program Files\Microsoft\jdk-{VERSION}\
```

Registry: `HKLM\SOFTWARE\Microsoft\JDK\{VERSION}`

Detection:
```powershell
Get-ChildItem "$env:ProgramFiles\Microsoft" -Filter "jdk-*" -ErrorAction SilentlyContinue
java -version 2>&1 | Select-String "Microsoft"
```

### Linux

```
/usr/lib/jvm/msopenjdk-{VERSION}/
```

Detection:
```bash
ls -d /usr/lib/jvm/msopenjdk-* 2>/dev/null
java -version 2>&1 | grep -i "Microsoft"
```

---

## Installation

For installation instructions, refer to the official Microsoft documentation:

- [Microsoft OpenJDK Installation Guide](https://learn.microsoft.com/en-us/java/openjdk/install)
- [Microsoft OpenJDK Download](https://learn.microsoft.com/en-us/java/openjdk/download)

---

## JAVA_HOME Guidance

**JAVA_HOME is NOT required.** .NET MAUI tools auto-detect JDK installations.

| State | OK? | Action |
|-------|-----|--------|
| Not set | ✅ | None needed, auto-detection works |
| Set to Microsoft JDK path | ✅ | None needed |
| Set to non-Microsoft JDK | ⚠️ | Report as anomaly — let user decide to unset or redirect |

Report a non-Microsoft JAVA_HOME as an anomaly: "JAVA_HOME is set to a non-Microsoft JDK. .NET MAUI auto-detects Microsoft OpenJDK, so JAVA_HOME is not needed and may cause build issues."

If the user decides to unset:
```bash
# macOS/Linux
unset JAVA_HOME

# Windows PowerShell
Remove-Item Env:JAVA_HOME
```

### Multiple JDKs Installed

1. Run `java -version` and check for "Microsoft" in output
2. If wrong vendor and `JAVA_HOME` is set → report as anomaly; user should unset or redirect to Microsoft JDK path
3. If wrong vendor and `JAVA_HOME` is NOT set → the non-Microsoft JDK may be first in PATH; install Microsoft JDK and it should take precedence
4. Restart terminal after changes

---

## Official Resources

- [Microsoft OpenJDK Installation Guide](https://learn.microsoft.com/en-us/java/openjdk/install)
- [Microsoft OpenJDK Download](https://learn.microsoft.com/en-us/java/openjdk/download)
- [Microsoft OpenJDK GitHub](https://github.com/microsoft/openjdk)

# Linux Platform Requirements

⚠️ **Linux has limited support** - Android targets only.

## Required Components

| Component | Requirement | Notes |
|-----------|-------------|-------|
| .NET SDK | Active support | Query releases-index.json |
| Java JDK | Per WorkloadDependencies | Microsoft OpenJDK **only** |
| Android SDK | Per WorkloadDependencies | Use packages array |

## Required Workloads

| Workload | Required | Purpose |
|----------|----------|---------|
| `maui-android` | ✅ Yes | MAUI for Android |
| `android` | ✅ Yes | Android targets |

**Important**: Use `maui-android` NOT `maui` on Linux. The `maui` workload is a meta-workload that includes iOS/Mac dependencies which won't install on Linux.

## Limitations

- ❌ No iOS support (requires macOS)
- ❌ No Mac Catalyst support (requires macOS)
- ❌ No Windows support (requires Windows)

## Android Development

| Component | Source | Notes |
|-----------|--------|-------|
| Java JDK | `jdk.version` from WorkloadDependencies | Microsoft OpenJDK **only** |
| Android SDK | `androidsdk` from WorkloadDependencies | Use packages array |
| Platform Tools | `androidsdk.packages` | ADB, fastboot |
| Build Tools | `androidsdk.buildToolsVersion` | AAPT2, dx |
| KVM | Enabled | For emulator acceleration |

# macOS Platform Requirements

## Required Components

| Component | Requirement | Notes |
|-----------|-------------|-------|
| macOS | Recent version | ARM64 or Intel |
| .NET SDK | Active support | Query releases-index.json for latest |
| Xcode | Per WorkloadDependencies | From [Apple Developer Downloads](https://developer.apple.com/download/all/) |
| Command Line Tools | Match Xcode | `xcode-select --install` |

## Required Workloads

| Workload | Required | Purpose |
|----------|----------|---------|
| `maui` | ✅ Yes | Core MAUI framework |
| `android` | ✅ Yes | Android targets |
| `ios` | ✅ Yes | iOS targets |
| `maccatalyst` | Recommended | Mac Catalyst targets |

## Android Development

| Component | Source | Notes |
|-----------|--------|-------|
| Java JDK | `jdk.version` from WorkloadDependencies | Microsoft OpenJDK **only** |
| Android SDK | `androidsdk` from WorkloadDependencies | Use packages array |
| Platform Tools | `androidsdk.packages` | ADB, fastboot |
| Build Tools | `androidsdk.buildToolsVersion` | AAPT2, dx |

## iOS/macOS Development

| Component | Source | Notes |
|-----------|--------|-------|
| Xcode | `xcode.version` from WorkloadDependencies | From iOS workload manifest |
| iOS SDK | `sdk.version` from WorkloadDependencies | Bundled with Xcode |
| iOS Simulator | Any | At least one device |

# Windows Platform Requirements

## Required Components

| Component | Requirement | Notes |
|-----------|-------------|-------|
| Windows | 10 or later | 64-bit required |
| .NET SDK | Active support | Query releases-index.json for latest |
| Windows App SDK | Current | Required for WinUI 3 / Windows targets |

## Required Workloads

| Workload | Required | Purpose |
|----------|----------|---------|
| `maui` or `maui-windows` | ✅ Yes | Core MAUI framework |
| `android` | ✅ Yes | Android targets |
| `ios` | Optional | iOS targets (requires Mac build host) |
| `maccatalyst` | Optional | Mac Catalyst (requires Mac build host) |

## Android Development

| Component | Source | Notes |
|-----------|--------|-------|
| Java JDK | `jdk.version` from WorkloadDependencies | Microsoft OpenJDK **only** |
| Android SDK | `androidsdk` from WorkloadDependencies | Use packages array |
| Android Emulator | Latest | With HAXM or Hyper-V |
| Platform Tools | `androidsdk.packages` | ADB, fastboot |
| Build Tools | `androidsdk.buildToolsVersion` | AAPT2, dx |

## Windows App Development

| Component | Requirement | Notes |
|-----------|-------------|-------|
| Windows App SDK | Current | Required for WinUI 3 |
| Windows SDK | Recent | Windows 10+ SDK |

# macOS Troubleshooting

## Xcode Issues

### "xcode-select: error: no developer tools found"

**Solution**:
```bash
xcode-select --install
```

### "Xcode not found at expected location"

**Solution**:
```bash
# List Xcode installations
ls -d /Applications/Xcode*.app 2>/dev/null

# Set active Xcode
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

### "Unable to boot simulator"

**Causes & Solutions**:

1. **No simulators installed**:
   ```bash
   xcrun simctl list devices available
   xcrun simctl create "iPhone 16" "com.apple.CoreSimulator.SimDeviceType.iPhone-16"
   ```

2. **Simulator runtime not installed**:
   - Download an iOS runtime via `xcodebuild -downloadPlatform iOS` or from Xcode → Settings → Platforms

3. **Corrupted simulator**:
   ```bash
   xcrun simctl erase all
   ```

### "Code signing error"

**Cause**: Missing or invalid provisioning profile.

**Solution**:
1. Open Xcode → Settings → Accounts
2. Add/refresh Apple Developer account
3. Download provisioning profiles

---

## macOS Performance

### Slow iOS simulator

1. Close other resource-intensive apps
2. Use recent simulator device (not legacy)
3. Reduce debugger verbosity
4. Use physical device for performance testing

---

## macOS Diagnostic Commands

```bash
# Xcode info
xcodebuild -version
xcode-select -p

# JDK detection (macOS-specific)
/usr/libexec/java_home -V

# Android SDK location
echo $ANDROID_SDK_ROOT
# Default: ~/Library/Android/sdk

# Logs
# ~/Library/Logs/Xamarin/
```

# Windows Troubleshooting

## Emulator Issues

### Hyper-V conflict with Android Emulator

**Cause**: HAXM and Hyper-V cannot coexist.

**Solution**:
- Use Android Emulator Hypervisor Driver instead of HAXM
- Or disable Hyper-V: `bcdedit /set hypervisorlaunchtype off`

---

## Windows Diagnostic Commands

```powershell
# JDK detection (Windows-specific)
Get-ChildItem "$env:ProgramFiles\Microsoft" -Filter "jdk-*" -ErrorAction SilentlyContinue
java -version 2>&1 | Select-String "Microsoft"

# Android SDK location
echo $env:ANDROID_SDK_ROOT
# Known paths: $env:LOCALAPPDATA\Android\Sdk
ls "$env:LOCALAPPDATA\Android\Sdk" -ErrorAction SilentlyContinue

# Android SDK list installed (Windows)
& "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" --list_installed

# Logs
# %LOCALAPPDATA%\Xamarin\Logs\
```

# Troubleshooting .NET MAUI Environment Issues

Common problems and solutions when setting up or using .NET MAUI.

**See also platform-specific troubleshooting:**
- macOS: `troubleshooting-macos.md`
- Windows: `troubleshooting-windows.md`

## .NET SDK Issues

### "dotnet: command not found"

**Cause**: .NET SDK not installed or not in PATH.

**Solution**:
```bash
# Check if dotnet exists
which dotnet

# macOS/Linux - Add to PATH if installed via dotnet-install script
export PATH="$PATH:$HOME/.dotnet"
```

If not installed, see: https://dotnet.microsoft.com/download

### "The required workload is not installed"

**Cause**: MAUI workload not installed.

**Solution**:
```bash
dotnet workload install maui --version $WORKLOAD_VERSION
```

### "Workload version mismatch"

**Cause**: Workloads from different SDK versions or incomplete installation.

**Solution**: Reinstall workloads with explicit version:
```bash
# First, find the correct workload set version for your SDK
# Query NuGet APIs (see workload-dependencies-discovery.md)

# Then reinstall with explicit version (macOS example — omit ios/maccatalyst on Linux)
dotnet workload install maui android ios maccatalyst --version $WORKLOAD_VERSION
```

**Note**: Avoid `dotnet workload update` or `dotnet workload repair` as they can cause version inconsistencies.

### SDK version conflict with global.json

**Cause**: Project requires specific SDK version not installed.

**Solution**:
```bash
# Check required version
cat global.json

# Install specific version
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --version X.Y.Z
```

---

## Java JDK Issues

**IMPORTANT: Only Microsoft Build of OpenJDK is supported.** Other JDK vendors (Oracle, Azul, Amazon Corretto, Temurin) are NOT supported for .NET MAUI development.

See `microsoft-openjdk.md` for complete installation paths by platform.

### "JAVA_HOME is not set"

**This is usually NOT a problem.** The .NET MAUI toolchain auto-detects JDK installations without needing `JAVA_HOME`.

**When JAVA_HOME matters:**
- ⚠️ `JAVA_HOME` is set but points to a **non-Microsoft JDK** → Report as anomaly; user should unset or redirect to Microsoft JDK
- ✅ `JAVA_HOME` is not set → Fine, tools will auto-detect
- ✅ `JAVA_HOME` points to Microsoft JDK → Fine

**Solution (only if JAVA_HOME is set to wrong JDK):**

Report this as an anomaly to the user: "JAVA_HOME is set to a non-Microsoft JDK. .NET MAUI auto-detects Microsoft OpenJDK, so JAVA_HOME is not needed and may cause build issues."

The user can then decide to:
- Unset JAVA_HOME (lets auto-detection work)
- Point it to Microsoft JDK if they have a specific reason to keep it set

### "Unsupported Java version" or "Wrong JDK vendor"

**Cause**: JDK version outside required range OR non-Microsoft JDK installed.

> Use the JDK version recommended by WorkloadDependencies.json (`jdk.recommendedVersion`), ensuring it satisfies the `jdk.version` range. Do not hardcode JDK versions.

**Solution**: Install the recommended Microsoft OpenJDK version using the [official installation guide](https://learn.microsoft.com/en-us/java/openjdk/install).

### Non-Microsoft JDK detected

**Cause**: Oracle, Azul, Corretto, or other non-Microsoft JDK is installed and selected.

**How to identify**: Run `java -version` - if output does NOT contain "Microsoft", wrong JDK is selected.

**Solution**:
1. Install the recommended Microsoft OpenJDK version (see commands above)
2. If `JAVA_HOME` is set and points to a non-Microsoft JDK, report this as an anomaly — the user should unset it or point it to the Microsoft JDK path
3. Optionally uninstall the non-Microsoft JDK

### Multiple JDKs installed, wrong one selected

**Solution**:
```bash
# macOS - find Microsoft JDK
/usr/libexec/java_home -V 2>&1 | grep -i microsoft

# Linux - set Microsoft as default
sudo update-java-alternatives --set msopenjdk-{VERSION}-amd64
```

---

## Android SDK Issues

### "Android SDK not found"

**Cause**: SDK not installed or path not configured.

**Solution**:
```bash
# Check environment variables
echo $ANDROID_HOME
echo $ANDROID_SDK_ROOT

# Common SDK locations:
# macOS: ~/Library/Android/sdk
# Linux: ~/Android/Sdk
# Windows: %LOCALAPPDATA%\Android\Sdk

# If no SDK found, download command-line tools from:
# https://developer.android.com/studio#command-line-tools-only
```

### "Failed to find Build Tools"

**Cause**: Required build-tools package not installed.

**Solution**:
```bash
# Get build tools version from WorkloadDependencies.json (androidsdk.buildToolsVersion)

# Use sdkmanager (macOS/Linux)
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager "build-tools;$BUILD_TOOLS_VERSION"

# Windows
# & "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" "build-tools;$BUILD_TOOLS_VERSION"
```

### "License not accepted"

**Cause**: Android SDK licenses not accepted.

**Solution**:
```bash
# macOS/Linux
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --licenses

# Windows
# & "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" --licenses
```

### "Platform not found: android-XX"

**Cause**: Target platform not installed.

**Solution**:
```bash
# Get required API level from WorkloadDependencies.json (androidsdk.apiLevel)

# macOS/Linux
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager "platforms;android-$API_LEVEL"

# Windows
# & "$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin\sdkmanager.bat" "platforms;android-$API_LEVEL"
```

### Emulator won't start

**Causes & Solutions**:

1. **HAXM/KVM not enabled**:
   ```bash
   # Linux - check KVM
   kvm-ok

   # Enable KVM
   sudo modprobe kvm
   ```

2. **Insufficient disk space**:
   - Clear AVD cache: `~/.android/avd/`

See also: `troubleshooting-windows.md` for Hyper-V conflicts.

---

## Build Errors

### "The target framework 'net10.0-android' is not available"

**Cause**: Android workload not installed for this SDK.

**Solution**:
```bash
dotnet workload install android --version $WORKLOAD_VERSION
```

### "Could not find android.jar"

**Cause**: Android platform not installed.

**Solution**:
```bash
# Discover required API level from WorkloadDependencies.json, then:
$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager "platforms;android-$API_LEVEL"
```

### "MSB4019: The imported project was not found"

**Cause**: Workload not properly installed.

**Solution**: Reinstall with explicit version:
```bash
# Get correct workload version for your SDK band from NuGet APIs, then:
dotnet workload install maui --version $WORKLOAD_VERSION
```

### "NETSDK1147: To build this project, the following workloads must be installed"

**Solution**: Install the listed workloads with explicit version:
```bash
dotnet workload install [workload-name] --version $WORKLOAD_VERSION
```

---

## Performance Issues

### Slow builds

**Solutions**:
1. Enable incremental builds (default)
2. Use Hot Reload during development
3. Build only necessary platforms:
   ```bash
   dotnet build -f net10.0-android
   ```

### Slow Android emulator

**Solutions**:
1. Enable hardware acceleration (HAXM/KVM/Hyper-V)
2. Use x86_64 system image (not ARM on Intel)
3. Increase emulator RAM in AVD settings
4. Use physical device for testing

---

## Environment Variable Reference

| Variable | Purpose | Required | Notes |
|----------|---------|----------|-------|
| `JAVA_HOME` | JDK location | No | Report as anomaly if set to non-Microsoft JDK |
| `ANDROID_HOME` | Android SDK location | No | Auto-detected |
| `ANDROID_SDK_ROOT` | Android SDK location | No | Alternative to ANDROID_HOME |
| `DOTNET_ROOT` | .NET SDK location | No | Usually auto-detected |
| `PATH` | Must include dotnet | Yes | Required for CLI access |

**Key point about JAVA_HOME:**
- ✅ Not set → Fine, tools auto-detect Microsoft JDK
- ✅ Set to Microsoft JDK path → Fine
- ⚠️ Set to non-Microsoft JDK → Anomaly — report to user

**Note**: The .NET MAUI toolchain auto-detects most paths. Only set these manually if auto-detection fails or wrong JDK is being selected.

---

## Getting Help

### Diagnostic Commands

```bash
# Full .NET info
dotnet --info

# Workload status
dotnet workload list

# JDK info
java -version
```

See platform-specific troubleshooting files for additional diagnostic commands.

### Resources

- [.NET MAUI GitHub Issues](https://github.com/dotnet/maui/issues)
- [Stack Overflow - maui tag](https://stackoverflow.com/questions/tagged/maui)
- [.NET MAUI Documentation](https://learn.microsoft.com/en-us/dotnet/maui/)

# Workload Dependencies Discovery

This reference describes how to discover authoritative version requirements from NuGet APIs. All JDK, Android SDK, and Xcode requirements come from WorkloadDependencies.json - never hardcode versions.

## Workload Aliases

| Alias | Full ID |
|-------|---------|
| ios | microsoft.net.sdk.ios |
| android | microsoft.net.sdk.android |
| maccatalyst | microsoft.net.sdk.maccatalyst |
| macos | microsoft.net.sdk.macos |
| tvos | microsoft.net.sdk.tvos |
| maui | microsoft.net.sdk.maui |

---

## Discovery Process

### Step 1: Get Latest SDK Version

**Bash:**
```bash
curl -s "https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json" | \
  jq '.["releases-index"][] | select(.["channel-version"]=="{MAJOR}.0")'
```

**PowerShell:**
```powershell
$releases = Invoke-RestMethod "https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json"
$releases.'releases-index' | Where-Object { $_.'channel-version' -eq '{MAJOR}.0' }
```

Response fields:
| Field | Description |
|-------|-------------|
| `channel-version` | Major.minor (e.g., "10.0") |
| `latest-sdk` | Current stable SDK version |
| `support-phase` | "active", "maintenance", "eol" |

Extract `latest-sdk` and derive SDK band:
- `10.0.102` → band `10.0.100` (hundreds digit)
- `10.0.205` → band `10.0.200`

### Step 2: Find Workload Set Version

Use the `dotnet workload search version` command to discover the latest workload set version:

```bash
dotnet workload search version --format json --take 1
# Returns: [{"workloadVersion":"10.0.103"}]
```

```powershell
dotnet workload search version --format json --take 1 | ConvertFrom-Json
```

The returned `workloadVersion` is the CLI version to use with `--version` flag.

To convert this to the NuGet package version (needed for Steps 3-4):
- CLI `10.0.102` → NuGet `10.102.0` (remove middle `.0.`, combine)
- The NuGet package is: `Microsoft.NET.Workloads.{band}` where band = CLI version (e.g., `Microsoft.NET.Workloads.10.0.100`)

### Step 3: Download Workload Set Manifest

**Bash:**
```bash
curl -o workloadset.nupkg "https://api.nuget.org/v3-flatcontainer/microsoft.net.workloads.{band}/{version}/microsoft.net.workloads.{band}.{version}.nupkg"
unzip -p workloadset.nupkg data/microsoft.net.workloads.workloadset.json
```

**PowerShell:**
```powershell
Invoke-WebRequest "https://api.nuget.org/v3-flatcontainer/microsoft.net.workloads.{band}/{version}/microsoft.net.workloads.{band}.{version}.nupkg" -OutFile workloadset.nupkg
Add-Type -AssemblyName System.IO.Compression.FileSystem
$zip = [System.IO.Compression.ZipFile]::OpenRead("workloadset.nupkg")
$entry = $zip.Entries | Where-Object { $_.FullName -eq "data/microsoft.net.workloads.workloadset.json" }
$reader = [System.IO.StreamReader]::new($entry.Open())
$reader.ReadToEnd() | ConvertFrom-Json
$reader.Dispose(); $zip.Dispose()
```

Contents format: `"{workload_id}": "{manifestVersion}/{sdkBand}"`

Example:
```json
{
  "microsoft.net.sdk.android": "35.0.50/9.0.100",
  "microsoft.net.sdk.ios": "26.2.10191/10.0.100",
  "microsoft.net.sdk.maui": "10.0.10/10.0.100"
}
```

### Step 4: Download Workload Manifest

Build package id: `{WorkloadId}.Manifest-{sdkBand}`

Examples:
- `Microsoft.NET.Sdk.iOS.Manifest-10.0.100`
- `Microsoft.NET.Sdk.Android.Manifest-9.0.100`

**Bash:**
```bash
curl -o manifest.nupkg "https://api.nuget.org/v3-flatcontainer/{packageid}/{version}/{packageid}.{version}.nupkg"
unzip -p manifest.nupkg data/WorkloadDependencies.json
```

**PowerShell:**
```powershell
Invoke-WebRequest "https://api.nuget.org/v3-flatcontainer/{packageid}/{version}/{packageid}.{version}.nupkg" -OutFile manifest.nupkg
Add-Type -AssemblyName System.IO.Compression.FileSystem
$zip = [System.IO.Compression.ZipFile]::OpenRead("manifest.nupkg")
$entry = $zip.Entries | Where-Object { $_.FullName -eq "data/WorkloadDependencies.json" }
$reader = [System.IO.StreamReader]::new($entry.Open())
$reader.ReadToEnd() | ConvertFrom-Json
$reader.Dispose(); $zip.Dispose()
```

### Step 5: Parse WorkloadDependencies.json

**Android workload** (`microsoft.net.sdk.android`):
```json
{
  "microsoft.net.sdk.android": {
    "jdk": {
      "version": "[17.0,22.0)",
      "recommendedVersion": "21.0.8"
    },
    "androidsdk": {
      "packages": ["build-tools;35.0.0", "platform-tools", "platforms;android-35", "cmdline-tools;13.0"],
      "apiLevel": "35",
      "buildToolsVersion": "35.0.0",
      "cmdLineToolsVersion": "13.0"
    }
  }
}
```

**iOS workload** (`microsoft.net.sdk.ios`):
```json
{
  "microsoft.net.sdk.ios": {
    "xcode": {
      "version": "[26.2,)",
      "recommendedVersion": "26.2"
    },
    "sdk": {
      "version": "26.2"
    }
  }
}
```

### Version Range Notation

| Notation | Meaning |
|----------|---------|
| `[17.0,22.0)` | >= 17.0 AND < 22.0 |
| `[26.2,)` | >= 26.2 (no upper bound) |

Brackets: `[` = inclusive, `(` = exclusive

---

## Complete Example

**Goal**: Find requirements for .NET 10

### Bash

```bash
# Step 1: Get SDK info
curl -s "https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json" | \
  jq '.["releases-index"][] | select(.["channel-version"]=="10.0") | .["latest-sdk"]'
# Result: "10.0.102" → band "10.0.100"

# Step 2: Get latest workload set version
dotnet workload search version --format json --take 1
# Result: [{"workloadVersion":"10.0.102"}]
# NuGet version: 10.102.0

# Step 3: Download workload set manifest
curl -so workloadset.nupkg "https://api.nuget.org/v3-flatcontainer/microsoft.net.workloads.10.0.100/10.102.0/microsoft.net.workloads.10.0.100.10.102.0.nupkg"
unzip -p workloadset.nupkg data/microsoft.net.workloads.workloadset.json | jq '."microsoft.net.sdk.android"'
# Result: "35.0.50/9.0.100"

# Step 4: Download Android manifest
curl -so android.nupkg "https://api.nuget.org/v3-flatcontainer/microsoft.net.sdk.android.manifest-9.0.100/35.0.50/microsoft.net.sdk.android.manifest-9.0.100.35.0.50.nupkg"
unzip -p android.nupkg data/WorkloadDependencies.json | jq '.["microsoft.net.sdk.android"]'
```

### PowerShell

```powershell
# Step 1: Get SDK info
$releases = Invoke-RestMethod "https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json"
$sdkInfo = $releases.'releases-index' | Where-Object { $_.'channel-version' -eq '10.0' }
$latestSdk = $sdkInfo.'latest-sdk'
# Result: "10.0.102" → band "10.0.100"

# Step 2: Get latest workload set version
$workloadVersion = (dotnet workload search version --format json --take 1 | ConvertFrom-Json).workloadVersion
# Result: "10.0.102"
# NuGet version: 10.102.0

# Step 3: Download workload set manifest and extract
Invoke-WebRequest "https://api.nuget.org/v3-flatcontainer/microsoft.net.workloads.10.0.100/10.102.0/microsoft.net.workloads.10.0.100.10.102.0.nupkg" -OutFile workloadset.nupkg
Add-Type -AssemblyName System.IO.Compression.FileSystem
$zip = [System.IO.Compression.ZipFile]::OpenRead("workloadset.nupkg")
$entry = $zip.Entries | Where-Object { $_.FullName -eq "data/microsoft.net.workloads.workloadset.json" }
$reader = [System.IO.StreamReader]::new($entry.Open())
$manifest = $reader.ReadToEnd() | ConvertFrom-Json
$reader.Dispose(); $zip.Dispose()
$manifest.'microsoft.net.sdk.android'
# Result: "35.0.50/9.0.100"

# Step 4: Download Android manifest and extract WorkloadDependencies
Invoke-WebRequest "https://api.nuget.org/v3-flatcontainer/microsoft.net.sdk.android.manifest-9.0.100/35.0.50/microsoft.net.sdk.android.manifest-9.0.100.35.0.50.nupkg" -OutFile android.nupkg
$zip = [System.IO.Compression.ZipFile]::OpenRead("android.nupkg")
$entry = $zip.Entries | Where-Object { $_.FullName -eq "data/WorkloadDependencies.json" }
$reader = [System.IO.StreamReader]::new($entry.Open())
$reader.ReadToEnd() | ConvertFrom-Json
$reader.Dispose(); $zip.Dispose()
```

**Result**: Authoritative JDK, Android SDK, and Xcode requirements from live NuGet data.

---

## NuGet API Reference

| Operation | Endpoint |
|-----------|----------|
| .NET releases | `https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json` |
| NuGet service index | `https://api.nuget.org/v3/index.json` |
| Download package | `https://api.nuget.org/v3-flatcontainer/{id}/{version}/{id}.{version}.nupkg` |

**Workload version discovery**: Use `dotnet workload search version --format json --take 1` instead of querying NuGet search APIs directly. The NuGet download URLs are still needed for Steps 3-4 (manifest extraction).

**Important**: Package IDs must be lowercase in download URLs.

---

## Best Practices

- **ALWAYS** fetch live data from NuGet APIs
- **NEVER** hardcode version requirements
- **ALWAYS** include SDK band with manifest versions
- Show exact URLs used for transparency