Preparar Avalonia para Android con Rider (.NET 10)¶
Esta guía permite crear y ejecutar en Windows una aplicación de Avalonia Cross Platform Application en un emulador Android, usando JetBrains Rider, .NET 10 y comandos de PowerShell.
Antes de comenzar
- Los comandos se ejecutan en PowerShell (terminal de Rider o terminal de Windows).
- Trabajaremos con el Android SDK en
C:\Android\Sdk, unificándolo para evitar problemas de rutas. AvaloniaApplication1es un nombre de ejemplo. Sustitúyelo por el nombre real de tu solución y de tus proyectos.- Si ya tienes una herramienta instalada, verifica su versión y pasa al siguiente apartado.
1. Instalar .NET SDK 10¶
Comprobar si ya tenemos el SDK:
Si no aparece una versión 10.0, instalar desde PowerShell:
Alternativa desde la web: descargar .NET 10 SDK. Hay que instalar el SDK, no únicamente el Runtime.
Si winget no se reconoce
Instala o actualiza App Installer / Instalador de aplicaciones desde Microsoft Store. También puedes evitar winget y usar el instalador web de .NET.
Cerrar y volver a abrir la terminal para que Windows actualice las variables de entorno. Volver a comprobar:
2. Instalar las plantillas de Avalonia¶
Comprobar que están disponibles:
Las plantillas son los modelos iniciales de proyectos que Rider puede crear.
3. Crear una aplicación multiplataforma en Rider¶
- Abrir Rider y seleccionar New Solution.
- Elegir Avalonia Cross Platform Application (no una aplicación solo para escritorio).
- Indicar un nombre; en los ejemplos usaremos
AvaloniaApplication1. - Crear la solución.
La plantilla genera varios proyectos, normalmente uno compartido, otro de escritorio, uno de Android y otro de navegador (además de otros destinos según la plantilla).
Plugin de Rider
En Settings → Plugins → Marketplace, instalar AvaloniaRider si no está instalado. Aporta, entre otras funciones, vista previa de XAML; no es el Android SDK ni sustituye las cargas de trabajo de .NET.
4. Restaurar las cargas de trabajo de la solución¶
Abrir una terminal en la carpeta que contiene la solución y ejecutar:
También podemos señalar expresamente el archivo de solución:
No es necesario ejecutar ambos comandos: hacen la misma operación si estamos en la carpeta correcta. workload restore detecta e instala las cargas de trabajo de .NET que necesitan los proyectos.
En Rider, hacer clic derecho sobre la solución y seleccionar Reload All Projects para actualizar su estado tras la instalación.
Si solo queremos instalar Android explícitamente, otra opción es:
Comprobar las cargas instaladas:
5. Preparar Java JDK 21¶
Java es necesario para compilar aplicaciones Android. Podemos instalar Microsoft OpenJDK 21 manualmente, aunque también podemos permitir que la tarea del apartado 6 descargue el JDK requerido a una carpeta del usuario.
Si prefieres instalarlo manualmente:
Alternativa web: descargar Microsoft OpenJDK 21.
Si lo instalas manualmente, cierra y vuelve a abrir la terminal y comprueba java -version. Esta comprobación no garantiza que exista el JDK en la carpeta $jdk que usaremos abajo.
Elegir una carpeta de JDK sin permisos de administrador¶
Para evitar el error «Please set JavaSdkDirectory to a valid non-administrator path» al instalar las dependencias de Android, utilizaremos una ruta dentro del perfil del usuario en lugar de la carpeta protegida C:\Program Files\Microsoft.
Ejecuta esta línea en PowerShell:
$env:LOCALAPPDATA apunta a la carpeta de datos locales del usuario de Windows. $jdk contendrá la ruta elegida para el JDK. No es necesario que el directorio exista todavía: el paso InstallAndroidDependencies puede descargar allí el JDK requerido.
Sobre la instalación con winget
Si instalaste Java con winget install Microsoft.OpenJDK.21, puedes mantenerlo para otros proyectos. En esta guía, JavaSdkDirectory usará la ruta del usuario ($jdk), no la instalación bajo Program Files. Por eso no es obligatorio instalar Java con winget si dejas que InstallAndroidDependencies descargue sus dependencias.
Configurar las variables de entorno¶
[Environment]::SetEnvironmentVariable("JAVA_HOME", $jdk, "User")
[Environment]::SetEnvironmentVariable("ANDROID_HOME", "C:\Android\Sdk", "User")
[Environment]::SetEnvironmentVariable("ANDROID_SDK_ROOT", "C:\Android\Sdk", "User")
$env:JAVA_HOME = $jdk
$env:ANDROID_HOME = "C:\Android\Sdk"
$env:ANDROID_SDK_ROOT = "C:\Android\Sdk"
$env:Path = "$jdk\bin;C:\Android\Sdk\platform-tools;$env:Path"
| Variable | ¿Para qué sirve? |
|---|---|
JAVA_HOME |
Ubicación del JDK que usarán las herramientas de Android. |
ANDROID_HOME |
Carpeta donde se instala el Android SDK. |
ANDROID_SDK_ROOT |
Nombre alternativo que algunas herramientas siguen consultando; debe coincidir con ANDROID_HOME. |
Path |
Facilita ejecutar java y adb sin escribir sus rutas completas. |
SetEnvironmentVariable(..., "User") guarda las variables para futuras terminales del usuario. Las asignaciones $env:... las aplican inmediatamente a esta sesión. El cambio de Path mostrado es solo para esta terminal; más adelante usaremos rutas completas para no depender de él.
6. Instalar las dependencias del Android SDK¶
Desde la carpeta de la solución, ejecutar cambiando AvaloniaApplication1 por el nombre real de la app:
dotnet build `
.\AvaloniaApplication1.Android\AvaloniaApplication1.Android.csproj `
-t:InstallAndroidDependencies `
-f net10.0-android `
-p:AndroidSdkDirectory="C:\Android\Sdk" `
-p:JavaSdkDirectory="$jdk" `
-p:AcceptAndroidSdkLicenses=True
Importante
En PowerShell, el símbolo **** al final de una línea permite continuar el comando en la siguiente. No pongas espacios después de él. Si la aplicación usa otroTargetFramework, consulta su.Android.csprojy adaptanet10.0-android`.
El JDK se instalará o utilizará en la carpeta $env:LOCALAPPDATA\Android\Jdk, evitando intentar escribir dentro de Program Files.
Qué hace cada parte:
dotnet build: invoca la compilación de .NET/MSBuild..Android.csproj: identifica el proyecto Android de nuestra solución.-t:InstallAndroidDependencies: instala los componentes de Android necesarios para ese proyecto.-f net10.0-android: selecciona el destino Android de .NET 10.AndroidSdkDirectoryyJavaSdkDirectory: indican explícitamente las carpetas del SDK y el JDK.AcceptAndroidSdkLicenses=True: acepta las licencias del SDK durante la instalación.
Este paso puede descargar varios componentes y tardar según la conexión. No es necesario repetirlo para cada ejecución; sí puede hacer falta si cambia la versión objetivo de Android.
7. Comprobar el Android SDK y localizar sus herramientas¶
Podemos ver qué carpetas se han instalado (comprobación opcional):
También se puede buscar sdkmanager.bat para comprobar que existen las Command-line Tools:
Si no aparece sdkmanager.bat
Necesitas instalar las Android SDK Command-line Tools. Se pueden descargar desde Android Developers o instalar con Android Studio → SDK Manager → SDK Tools. Después, repite la búsqueda. No podremos crear el emulador sin estas herramientas.
Para no buscar dos veces, localizamos sdkmanager y obtenemos avdmanager desde la misma carpeta:
$herramienta = Get-ChildItem "C:\Android\Sdk\cmdline-tools" -Recurse -Filter sdkmanager.bat |
Select-Object -First 1
if (-not $herramienta) { throw "No aparece sdkmanager.bat. Instala Android SDK Command-line Tools." }
$sdkmanager = $herramienta.FullName
$avdmanager = Join-Path (Split-Path $sdkmanager) "avdmanager.bat"
sdkmanager: descarga y actualiza componentes del Android SDK.avdmanager: crea y administra los dispositivos virtuales Android (AVD).
8. Descargar los componentes del emulador¶
| Componente | Función |
|---|---|
platform-tools |
Incluye adb para comunicarnos con el emulador o un teléfono físico. |
emulator |
Programa que ejecuta dispositivos virtuales Android. |
system-images;android-36;google_apis;x86_64 |
Imagen de Android API 36, con APIs de Google y arquitectura x86-64, para el emulador. |
El operador & ejecuta en PowerShell el programa cuya ruta está guardada en una variable. Si se solicitan licencias, aceptarlas; también se pueden revisar con & $sdkmanager --licenses.
Requisitos del equipo
Para el emulador x86-64 necesitamos un ordenador compatible y virtualización por hardware activada. En equipos ARM puede necesitarse una imagen diferente. La descarga de la imagen ocupa espacio en disco.
9. Crear el emulador Android¶
Creamos un dispositivo virtual llamado CICLO_API36:
-n: nombre del emulador (podemos elegir otro).-k: imagen de sistema que utilizará."no" |: responde no a la pregunta opcional de crear un perfil de hardware personalizado; se usa el perfil predeterminado.
Comprobar si se ha creado:
Si ya existe un AVD con el mismo nombre, no hay que volver a crearlo.
10. Arrancar el emulador y comprobar la conexión¶
Abrir una terminal y arrancar el emulador:
Dejar esa terminal abierta y esperar a que Android termine de arrancar. Desde otra terminal:
La salida debería mostrar un identificador similar a emulator-5554 con estado device. Si aparece offline, espera a que el emulador arranque completamente y comprueba de nuevo.
11. Ejecutar la aplicación Android desde Rider¶
- Dejar el emulador encendido.
- Abrir la solución en Rider y verificar que no hay errores de restauración.
- Seleccionar la configuración correspondiente al proyecto
AvaloniaApplication1.Androidy el emulador. - Pulsar Run.
Si el emulador no aparece en Rider, comprobar primero adb devices. Si el proyecto falla por componentes ausentes, repetir dotnet workload restore y el apartado 6.
Resumen: ¿qué pasos se ejecutan una sola vez?¶
| Paso | ¿Cuándo? |
|---|---|
| Instalar .NET, Avalonia Templates, plugin y JDK | Una vez por equipo (o cuando se actualicen). |
| Crear solución y restaurar workloads | Al crear una solución; repetir la restauración si faltan cargas. |
Variables JAVA_HOME y Android |
Una vez por usuario, y para la sesión actual. |
InstallAndroidDependencies |
Al preparar el SDK o si cambian dependencias/versiones. |
| Instalar imagen y crear AVD | Una vez por emulador. |
| Arrancar emulador y ejecutar desde Rider | Cada vez que queramos probar la aplicación. |
¿Y si queremos ejecutar la aplicación en un navegador?¶
Continúa con Avalonia en navegador (WebAssembly). Es un destino diferente de Android y necesita wasm-tools, pero no necesita arrancar el emulador.