Připojení k místním webovým službám z emulátorů Androidu a simulátorů iOS

Projděte si ukázku. Procházení ukázky

Mnoho mobilních a desktopových aplikací využívá webové služby. Během fáze vývoje softwaru je běžné nasadit webovou službu místně a využívat ji z aplikace spuštěné v emulátoru Androidu nebo simulátoru iOS. Tím se zabrání nasazení webové služby do hostovaného koncového bodu a umožňuje jednoduché ladění, protože aplikace i webová služba běží místně.

Návod

Pokud používáte .NET 10 nebo novější, zvažte použití integrace Aspire ke zjednodušení připojení k místním webovým službám. Aspire automaticky zpracovává konfiguraci sítí specifickou pro platformu, zjišťování služeb a vývojové tunely a eliminuje většinu ruční konfigurace popsané v tomto článku.

Aplikace .NET Multi-Platform App UI (.NET MAUI), které běží na Windows nebo MacCatalyst, můžou využívat webové služby ASP.NET Core spuštěné místně přes protokol HTTP nebo HTTPS bez jakékoli další práce, za předpokladu, že důvěřujete svému vývojovému certifikátu. Pokud ale aplikace běží v emulátoru Androidu nebo simulátoru iOS, vyžaduje se další práce a proces se liší v závislosti na tom, jestli webová služba běží přes PROTOKOL HTTP nebo HTTPS.

Adresa místního počítače

Emulátor Androidu i simulátor iOS poskytují přístup k webovým službám běžícím přes PROTOKOL HTTP nebo HTTPS na místním počítači. Adresa místního počítače se ale pro každý z nich liší.

Android

Každá instance emulátoru Androidu je izolovaná od síťových rozhraní vývojového počítače a běží za virtuálním směrovačem. Emulované zařízení proto nevidí váš vývojový počítač ani jiné instance emulátoru v síti.

Virtuální směrovač pro každý emulátor ale spravuje speciální síťový prostor, který obsahuje předem přidělené adresy, přičemž adresa 10.0.2.2 je aliasem pro rozhraní localhost na hostitelském počítači (127.0.0.1 na vašem vývojovém stroji). Vzhledem k tomu, že místní webová služba nabízí operaci GET prostřednictvím relativního URI /api/todoitems/, může aplikace spuštěná v emulátoru Androidu tuto operaci využívat odesláním požadavku GET na http://10.0.2.2:<port>/api/todoitems/ nebo https://10.0.2.2:<port>/api/todoitems/.

iOS

Simulátor iOSu používá síť hostitelského počítače. Aplikace spuštěné v simulátoru se proto můžou připojit k webovým službám, které běží na místním počítači, prostřednictvím IP adresy počítače nebo názvu hostitele localhost. Například, má-li místní webová služba operaci GET dostupnou prostřednictvím relativní URI, může aplikace spuštěná v simulátoru iOS tuto operaci využívat odesláním GET požadavku na http://localhost:<port>/api/todoitems/ nebo https://localhost:<port>/api/todoitems/.

Poznámka:

Při spuštění aplikace .NET MAUI v simulátoru iOS z Windows se aplikace zobrazí ve vzdáleném simulátoru iOS pro Windows. Aplikace je ale spuštěná na spárovaných počítačích Mac. Proto neexistuje přístup místního hostitele k webové službě spuštěné ve Windows pro aplikaci pro iOS běžící na Macu.

Místní webové služby spuštěné přes HTTP

Aplikace .NET MAUI spuštěná v emulátoru Androidu nebo simulátoru iOS může využívat webovou službu ASP.NET Core spuštěnou místně přes protokol HTTP. Toho lze dosáhnout tak, že nakonfigurujete projekt aplikace .NET MAUI a projekt webové služby ASP.NET Core tak, aby umožňoval přenosy HTTP s vymazáním textu.

V kódu, který definuje adresu URL místní webové služby v aplikaci .NET MAUI, ujistěte se, že adresa URL webové služby určuje schéma HTTP a správný název hostitele. Třída DeviceInfo může být použita k detekci platformy, na které aplikace běží. Správný název hostitele pak můžete nastavit takto:

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

Další informace o třídě DeviceInfo najdete v části Informace o zařízení.

Pokud chcete aplikaci spustit na Androidu, musíte přidat požadovanou konfiguraci sítě a spustit aplikaci v iOSu, musíte se odhlásit ze služby Apple Transport Security (ATS). Další informace najdete v tématu Konfigurace sítě Android a konfigurace ATS pro iOS.

Musíte také zajistit, aby webová služba ASP.NET Core byla nakonfigurovaná tak, aby povolovala provoz HTTP. Toho lze dosáhnout přidáním profilu HTTP do profiles části launchSettings.json v projektu webové služby ASP.NET Core.

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

Aplikace .NET MAUI spuštěná v emulátoru Androidu nebo simulátoru iOS pak může využívat webovou službu ASP.NET Core spuštěnou místně přes protokol HTTP, za předpokladu, že je webová služba spuštěná s profilem http.

Konfigurace sítě Pro Android

Existují dva hlavní přístupy k povolení místního provozu s jasným textem v Androidu:

• Povolte pro komunikaci se všemi doménami přenosy v síti s jasným textem. Další informace najdete v tématu Povolení síťového provozu s čitelným textem pro všechny domény.
• Povolit síťový provoz v otevřeném textu pro komunikaci s doménou localhost. Další informace naleznete v tématu Povolení prostého textového síťového provozu pro doménu localhost.

Povolit nešifrovaný síťový provoz pro všechny domény

Přenosy nezabezpečeného textu pro všechny domény lze povolit nastavením vlastnosti UsesCleartextTraffic atributu Application na true. To by se mělo provést v Platforms > Android > MainApplication.cs souboru ve vašem .NET MAUI projektu aplikace a mělo by se obalit do bloku #if DEBUG #if DEBUG, aby bylo zajištěno, že není omylem povolena v produkční aplikaci.

#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();
}

Poznámka:

Vlastnost UsesCleartextTraffic je ignorována na Androidu 7.0 (API 24) a novějších verzích, pokud je přítomen konfigurační soubor zabezpečení sítě.

Povolení nešifrovaného síťového provozu pro doménu localhost

Nešifrovaný přenos v síti pro localhost je možné povolit vytvořením konfiguračního souboru zabezpečení sítě. Toho lze dosáhnout přidáním nového souboru XML s názvem network_security_config.xml do složky Platforms\Android\Resources\xml v projektu aplikace .NET MAUI. Soubor XML by měl zadat následující konfiguraci:

<?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>

Poznámka:

Ujistěte se, že je akce sestavení souboru network_security_config.xml nastavená na AndroidResource.

Potom nakonfigurujte vlastnost networkSecurityConfig na uzlu aplikace v souboru Platforms\Android\AndroidManifest.xml v projektu aplikace .NET MAUI:

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

Pro více informací o konfiguračních souborech zabezpečení sítě viz Konfigurace zabezpečení sítě na developer.android.com.

Konfigurace ATS pro iOS

Pokud chcete povolit přenosy čistého textu na iOS, měli byste ve své aplikaci .NET MAUI vypnout Apple Transport Security (ATS). Toho lze dosáhnout přidáním následující konfigurace do souboru Platforms\iOS\Info.plist v projektu aplikace .NET MAUI:

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

Další informace o ATS naleznete na webu developer.apple.com v dokumentu Prevence nezabezpečených síťových připojení.

Místní webové služby spuštěné přes HTTPS

Aplikace .NET MAUI spuštěná v emulátoru Androidu nebo simulátoru iOS může využívat webovou službu ASP.NET Core, která běží místně přes PROTOKOL HTTPS. Postup povolení je následující:

1. Důvěřujte svépomocí podepsanému vývojovému certifikátu na vašem počítači. Další informace viz Důvěřujte svému vývojovému certifikátu.
2. Zadejte adresu místního počítače. Další informace naleznete v tématu Určení adresy místního počítače.
3. Obejít kontrolu zabezpečení místního vývojového certifikátu. Další informace najdete v tématu Obejití zabezpečení certifikátu.

Jednotlivé položky budou probrány po řadě.

Důvěřovat vývojovému certifikátu

Instalace sady .NET Core SDK nainstaluje vývojový certifikát ASP.NET Core HTTPS do místního úložiště certifikátů uživatele. I když je však certifikát nainstalovaný, není důvěryhodný. Pokud chcete certifikátu důvěřovat, proveďte následující jednorázový krok ke spuštění nástroje dotnet dev-certs:

dotnet dev-certs https --trust

Následující příkaz poskytuje nápovědu k nástroji dev-certs:

dotnet dev-certs https --help

Případně když spustíte projekt ASP.NET Core 2.1 (nebo novější), který používá HTTPS, Visual Studio zjistí, jestli chybí vývojový certifikát, a nabídne instalaci a důvěřování.

Poznámka:

Vývojový certifikát ASP.NET Core HTTPS je podepsaný svým držitelem.

Další informace o povolení místního HTTPS na počítači najdete v tématu Povolení místního HTTPS.

Zadejte adresu místního počítače.

V kódu, který definuje adresu URL místní webové služby v aplikaci .NET MAUI, ujistěte se, že adresa URL webové služby určuje schéma HTTPS a správný název hostitele. Třída DeviceInfo může být použita k detekci platformy, na které aplikace běží. Správný název hostitele pak můžete nastavit takto:

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

Další informace o třídě DeviceInfo najdete v části Informace o zařízení.

Obejití kontroly zabezpečení certifikátu

Pokus o vyvolání místní zabezpečené webové služby z aplikace .NET MAUI spuštěné v emulátoru Androidu způsobí vyhození java.security.cert.CertPathValidatorException, s oznámením, že nebyl nalezen kořen důvěry pro certifikační řetěz. Podobně pokus o vyvolání místní zabezpečené webové služby z aplikace .NET MAUI spuštěné v simulátoru iOS způsobí NSURLErrorDomain chybu se zprávou, že certifikát pro server je neplatný. K těmto chybám dochází, protože místní vývojový certifikát HTTPS je podepsaný svým držitelem a certifikáty podepsané svým držitelem nejsou důvěryhodné pro Android nebo iOS. Proto je nutné ignorovat chyby SSL, když aplikace využívá místní zabezpečenou webovou službu.

Toho lze dosáhnout konfigurací instance HttpClientHandler s vlastním ServerCertificateCustomValidationCallback. Tento nastavení dává třídě HttpClient pokyn, aby důvěřovala komunikaci přes localhost přes HTTPS. Následující příklad ukazuje, jak vytvořit instanci HttpClientHandler, která bude ignorovat chyby ověření certifikátu pro 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);

Důležité

Kód ignoruje chyby ověření certifikátu localhost, ale pouze v ladicích sestaveních. Tento přístup zabraňuje incidentům zabezpečení v produkčních buildech.

Aplikace .NET MAUI spuštěná v emulátoru Androidu nebo simulátoru iOS pak může využívat webovou službu ASP.NET Core spuštěnou místně přes PROTOKOL HTTPS.