Menyambungkan ke layanan web lokal dari emulator Android dan simulator iOS

Telusuri sampel.Telusuri contoh

Banyak aplikasi seluler dan desktop menggunakan layanan web. Selama fase pengembangan perangkat lunak, umum untuk menyebarkan layanan web secara lokal dan menggunakannya dari aplikasi yang berjalan di emulator Android atau simulator iOS. Ini menghindari keharusan menyebarkan layanan web ke titik akhir yang dihosting, dan memungkinkan pengalaman debugging yang mudah karena aplikasi dan layanan web berjalan secara lokal.

Petunjuk / Saran

Jika Anda menggunakan .NET 10 atau yang lebih baru, pertimbangkan untuk menggunakan integrasi Aspire untuk menyederhanakan menyambungkan ke layanan web lokal. Aspire secara otomatis menangani konfigurasi jaringan khusus platform, penemuan layanan, dan terowongan pengembangan, menghilangkan banyak konfigurasi manual yang dijelaskan dalam artikel ini.

Aplikasi .NET Multi-platform App UI (.NET MAUI) yang berjalan di Windows atau Mac Catalyst dapat menggunakan layanan web ASP.NET Core yang dioperasikan secara lokal melalui HTTP atau HTTPS tanpa usaha tambahan, asalkan Anda telah mempercayai sertifikat pengembangan Anda. Namun, pekerjaan tambahan diperlukan ketika aplikasi berjalan di emulator Android atau simulator iOS, dan prosesnya berbeda tergantung pada apakah layanan web berjalan melalui HTTP atau HTTPS.

Alamat komputer lokal

Emulator Android dan simulator iOS menyediakan akses ke layanan web yang berjalan melalui HTTP atau HTTPS di komputer lokal Anda. Namun, alamat komputer lokal berbeda untuk masing-masing.

Android

Setiap instans emulator Android diisolasi dari antarmuka jaringan mesin pengembangan Anda, dan berjalan di belakang router virtual. Oleh karena itu, perangkat yang ditimulasikan tidak dapat melihat mesin pengembangan Anda atau instans emulator lainnya di jaringan.

Namun, router virtual untuk setiap emulator mengelola ruang jaringan khusus yang mencakup alamat yang telah dialokasikan sebelumnya, dengan 10.0.2.2 alamat yang merupakan alias ke antarmuka loopback host Anda (127.0.0.1 pada komputer pengembangan Anda). Oleh karena itu, dengan adanya layanan web lokal yang mengekspos operasi GET melalui URI relatif /api/todoitems/, aplikasi yang berjalan di emulator Android dapat menggunakan operasi ini dengan mengirimkan permintaan GET ke http://10.0.2.2:<port>/api/todoitems/ atau https://10.0.2.2:<port>/api/todoitems/.

iOS

Simulator iOS menggunakan jaringan komputer host. Oleh karena itu, aplikasi yang berjalan di simulator dapat terhubung ke layanan web yang berjalan di komputer lokal Anda melalui alamat IP komputer atau melalui nama host. Misalnya, mengingat layanan web lokal yang mengekspos operasi GET melalui /api/todoitems/ URI relatif, aplikasi yang berjalan di simulator iOS dapat mengakses operasi dengan mengirim permintaan GET ke http://localhost:<port>/api/todoitems/ atau https://localhost:<port>/api/todoitems/.

Catatan

Saat menjalankan aplikasi .NET MAUI di simulator iOS dari Windows, aplikasi ditampilkan di simulator iOS jarak jauh untuk Windows. Namun, aplikasi berjalan di Mac yang dipasangkan. Oleh karena itu, tidak ada akses localhost ke layanan web yang berjalan di Windows untuk aplikasi iOS yang berjalan di Mac.

Layanan web lokal yang berjalan melalui HTTP

Aplikasi .NET MAUI yang berjalan di emulator Android atau simulator iOS dapat menggunakan layanan web ASP.NET Core yang berjalan secara lokal melalui HTTP. Ini dapat dicapai dengan mengonfigurasi proyek aplikasi .NET MAUI dan proyek layanan web ASP.NET Core Anda untuk memungkinkan lalu lintas HTTP teks yang jelas.

Dalam kode yang menentukan URL layanan web lokal Anda di aplikasi .NET MAUI Anda, pastikan bahwa URL layanan web menentukan skema HTTP, dan nama host yang benar. Kelas DeviceInfo dapat digunakan untuk mendeteksi platform tempat aplikasi berjalan. Nama host yang benar kemudian dapat diatur sebagai berikut:

public static string BaseAddress =
    DeviceInfo.Platform == DevicePlatform.Android ? "http://10.0.2.2:5000" : "http://localhost:5000";
public static string TodoItemsUrl = $"{BaseAddress}/api/todoitems/";

Untuk informasi selengkapnya tentang kelas DeviceInfo lihat Informasi perangkat.

Selain itu, untuk menjalankan aplikasi di Android, Anda harus menambahkan konfigurasi jaringan yang diperlukan, dan untuk menjalankan aplikasi di iOS, Anda harus menolak Apple Transport Security (ATS). Untuk informasi selengkapnya, lihat Konfigurasi jaringan Android dan konfigurasi ATS iOS.

Anda juga harus memastikan bahwa layanan web ASP.NET Core Anda dikonfigurasi untuk mengizinkan lalu lintas HTTP. Ini dapat dicapai dengan menambahkan profil HTTP ke profiles bagian launchSettings.json di proyek layanan web ASP.NET Core Anda.

{
  ...
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "api/todoitems",
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    ...
  }
}

Aplikasi .NET MAUI yang berjalan di emulator Android atau simulator iOS kemudian dapat menggunakan layanan web ASP.NET Core yang berjalan secara lokal melalui HTTP, asalkan layanan web diluncurkan dengan profil http.

Konfigurasi jaringan Android

Ada dua pendekatan utama untuk mengaktifkan lalu lintas lokal teks-jelas di Android:

Mengaktifkan lalu lintas jaringan teks jelas untuk semua domain

Lalu lintas jaringan teks dalam bentuk jelas untuk semua domain dapat diaktifkan dengan mengatur properti UsesCleartextTraffic dari atribut Application ke true. Ini harus dilakukan dalam Platform > Android > MainApplication.cs di proyek aplikasi .NET MAUI Anda, dan harus dibungkus dalam #if DEBUG untuk memastikan bahwa itu tidak diaktifkan secara tidak sengaja dalam aplikasi produksi.

#if DEBUG
[Application(UsesCleartextTraffic = true)]
#else
[Application]
#endif
public class MainApplication : MauiApplication
{
    public MainApplication(IntPtr handle, JniHandleOwnership ownership)
        : base(handle, ownership)
    {
    }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

Catatan

Properti UsesCleartextTraffic diabaikan pada Android 7.0 (API 24) dan versi yang lebih tinggi jika ada file konfigurasi keamanan jaringan.

Mengaktifkan lalu lintas jaringan teks biasa untuk domain localhost

Lalu lintas jaringan teks biasa untuk domain localhost dapat diaktifkan dengan membuat file konfigurasi keamanan jaringan. Ini dapat dicapai dengan menambahkan file XML baru bernama network_security_config.xml ke folder Platforms\Android\Resources\xml di proyek aplikasi .NET MAUI Anda. File XML harus menentukan konfigurasi berikut:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="true">10.0.2.2</domain>
  </domain-config>
</network-security-config>

Catatan

Pastikan bahwa tindakan build dari file network_security_config.xml diatur ke AndroidResource.

Kemudian, konfigurasikan properti networkSecurityConfig pada simpul aplikasi di file Platforms\Android\AndroidManifest.xml di proyek aplikasi .NET MAUI Anda:

<?xml version="1.0" encoding="utf-8"?>
<manifest>
    <application android:networkSecurityConfig="@xml/network_security_config" ...>
        ...
    </application>
</manifest>

Untuk informasi selengkapnya tentang file konfigurasi keamanan jaringan, lihat Konfigurasi keamanan jaringan di developer.android.com.

Konfigurasi ATS iOS

Untuk mengizinkan lalu lintas lokal dengan teks-jelas di iOS, Anda perlu menonaktifkan Apple Transport Security (ATS) di aplikasi .NET MAUI Anda. Ini dapat dicapai dengan menambahkan konfigurasi berikut ke file Platforms\iOS\Info.plist di proyek aplikasi .NET MAUI Anda:

<key>NSAppTransportSecurity</key>    
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

Untuk informasi selengkapnya tentang ATS, lihat Mencegah Koneksi Jaringan yang Tidak Aman di developer.apple.com.

Layanan web lokal yang berjalan melalui HTTPS

Aplikasi .NET MAUI yang berjalan di emulator Android atau simulator iOS dapat menggunakan layanan web ASP.NET Core yang berjalan secara lokal melalui HTTPS. Proses untuk mengaktifkan ini adalah sebagai berikut:

  1. Percayai sertifikat pengembangan yang ditandatangani sendiri di komputer Anda. Untuk informasi selengkapnya, lihat Percayai sertifikat pengembangan Anda.
  2. Tentukan alamat komputer lokal Anda. Untuk informasi selengkapnya, lihat Menentukan alamat mesin lokal.
  3. Membypass pemeriksaan keamanan sertifikat pengembangan lokal. Untuk informasi selengkapnya, lihat Melewati pemeriksaan keamanan sertifikat.

Setiap item akan dibahas secara bergantian.

Percayai sertifikat pengembangan Anda

Menginstal .NET Core SDK menginstal sertifikat pengembangan ASP.NET Core HTTPS ke penyimpanan sertifikat pengguna lokal Anda. Namun, saat sertifikat telah diinstal, sertifikat tersebut tidak tepercaya. Untuk mempercayai sertifikat, lakukan langkah berikut ini satu kali untuk menjalankan alat dotnet dev-certs.

dotnet dev-certs https --trust

Perintah berikut memberikan bantuan tentang tool dev-certs:

dotnet dev-certs https --help

Atau, ketika Anda menjalankan proyek ASP.NET Core 2.1 (atau lebih tinggi), yang menggunakan HTTPS, Visual Studio akan mendeteksi apakah sertifikat pengembangan hilang dan akan menawarkan untuk menginstalnya dan mempercayainya.

Catatan

Sertifikat pengembangan ASP.NET Core HTTPS ditandatangani sendiri.

Untuk informasi selengkapnya tentang mengaktifkan HTTPS lokal di komputer Anda, lihat Mengaktifkan HTTPS lokal.

Tentukan alamat komputer lokal

Dalam kode yang menentukan URL layanan web lokal Anda di aplikasi .NET MAUI Anda, pastikan bahwa URL layanan web menentukan skema HTTPS, dan nama host yang benar. Kelas DeviceInfo dapat digunakan untuk mendeteksi platform tempat aplikasi berjalan. Nama host yang benar kemudian dapat diatur sebagai berikut:

public static string BaseAddress =
    DeviceInfo.Platform == DevicePlatform.Android ? "https://10.0.2.2:5001" : "https://localhost:5001";
public static string TodoItemsUrl = $"{BaseAddress}/api/todoitems/";

Untuk informasi selengkapnya tentang kelas DeviceInfo lihat Informasi perangkat.

Mengabaikan pemeriksaan keamanan sertifikat

Mencoba memanggil layanan web aman lokal dari aplikasi .NET MAUI yang berjalan di emulator Android akan mengakibatkan java.security.cert.CertPathValidatorException dilemparkan, dengan pesan yang menunjukkan bahwa jangkar kepercayaan untuk jalur sertifikasi belum ditemukan. Demikian pula, mencoba memanggil layanan web aman lokal dari aplikasi .NET MAUI yang berjalan di simulator iOS akan mengakibatkan terjadinya kesalahan NSURLErrorDomain dengan pesan yang menunjukkan bahwa sertifikat untuk server tidak valid. Kesalahan ini terjadi karena sertifikat pengembangan HTTPS lokal ditandatangani sendiri, dan sertifikat yang ditandatangani sendiri tidak dipercaya oleh Android atau iOS. Oleh karena itu, perlu untuk mengabaikan kesalahan SSL saat aplikasi menggunakan layanan web aman lokal.

Ini dapat dicapai dengan mengonfigurasi instance HttpClientHandler dengan ServerCertificateCustomValidationCallback kustom, yang menginstruksikan HttpClient class agar mempercayai komunikasi localhost melalui HTTPS. Contoh berikut menunjukkan cara membuat instans HttpClientHandler yang akan mengabaikan kesalahan validasi sertifikat pada localhost:

var handler = new HttpClientHandler();

#if DEBUG
handler.ServerCertificateCustomValidationCallback = (message, cert, chain, errors) =>
{
    if (cert != null && cert.Issuer.Equals("CN=localhost"))
        return true;
    return errors == System.Net.Security.SslPolicyErrors.None;
};
#endif

var client = new HttpClient(handler);

Penting

Kode di atas mengabaikan kesalahan validasi sertifikat localhost, tetapi hanya dalam build debug. Pendekatan ini menghindari insiden keamanan dalam build produksi.

Aplikasi .NET MAUI yang berjalan di emulator Android atau simulator iOS kemudian dapat menggunakan layanan web ASP.NET Core yang berjalan secara lokal melalui HTTPS.

  • Last updated on