Conecte-se a serviços Web locais a partir de emuladores Android e simuladores iOS

Procurar o exemplo

Muitas aplicações móveis e de ambiente de trabalho consomem serviços Web. Durante a fase de desenvolvimento de software, é comum implantar um serviço Web localmente e consumi-lo a partir de um aplicativo executado no emulador Android ou simulador iOS. Isso evita a necessidade de implantar o serviço Web em um ponto de extremidade hospedado e permite uma experiência de depuração simples porque o aplicativo e o serviço Web estão sendo executados localmente.

Os aplicativos .NET Multi-platform App UI (.NET MAUI) executados no Windows ou MacCatalyst podem consumir serviços Web ASP.NET Core executados localmente por HTTP ou HTTPS sem qualquer trabalho adicional, desde que você tenha confiado em seu certificado de desenvolvimento. No entanto, é necessário trabalho adicional quando o aplicativo está sendo executado no emulador Android ou no simulador iOS, e o processo é diferente, dependendo se o serviço Web está sendo executado por HTTP ou HTTPS.

Endereço da máquina local

O emulador Android e o simulador iOS fornecem acesso a serviços Web executados por HTTP ou HTTPS em sua máquina local. No entanto, o endereço da máquina local é diferente para cada um.

Android

Cada instância do emulador Android é isolada das interfaces de rede da máquina de desenvolvimento e é executada atrás de um roteador virtual. Portanto, um dispositivo emulado não pode ver sua máquina de desenvolvimento ou outras instâncias do emulador na rede.

No entanto, o router virtual para cada emulador gere um espaço de rede especial que inclui endereços pré-alocados, sendo o endereço 10.0.2.2 um alias para a interface de loopback do host (127.0.0.1 na sua máquina de desenvolvimento). Portanto, dado um serviço Web local que expõe uma operação GET por meio do /api/todoitems/ URI relativo, um aplicativo em execução no emulador Android pode consumir a operação enviando uma solicitação GET para http://10.0.2.2:<port>/api/todoitems/ ou https://10.0.2.2:<port>/api/todoitems/.

iOS

O simulador iOS usa a rede da máquina host. Portanto, os aplicativos executados no simulador podem se conectar a serviços da Web em execução em sua máquina local através do endereço IP da máquina ou através do nome do localhost host. Por exemplo, dado um serviço Web local que expõe uma operação GET por meio do /api/todoitems/ URI relativo, um aplicativo em execução no simulador do iOS pode consumir a operação enviando uma solicitação GET para http://localhost:<port>/api/todoitems/ ou https://localhost:<port>/api/todoitems/.

Serviços Web locais em execução via HTTP

Um aplicativo .net maui executado no emulador Android ou simulador iOS pode consumir um serviço Web ASP.NET Core que está sendo executado localmente por HTTP. Isso pode ser conseguido configurando seu projeto de aplicativo .NET MAUI e seu projeto de serviço Web ASP.NET Core para permitir tráfego HTTP de texto não criptografado.

No código que define a URL do serviço Web local no aplicativo .NET MAUI, verifique se a URL do serviço Web especifica o esquema HTTP e o nome de host correto. A DeviceInfo classe pode ser usada para detetar a plataforma em que o aplicativo está sendo executado. O nome de host correto pode ser definido da seguinte forma:

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

Para obter mais informações sobre a classe, consulte Informações do DeviceInfodispositivo.

Além disso, para executar seu aplicativo no Android, você deve adicionar a configuração de rede necessária e, para executar seu aplicativo no iOS, você deve desativar o Apple Transport Security (ATS). Para obter mais informações, consulte Configuração de rede Android e Configuração ATS do iOS.

Você também deve garantir que seu serviço Web ASP.NET Core esteja configurado para permitir tráfego HTTP. Isso pode ser feito adicionando um perfil HTTP à profiles seção de launchSettings.json em seu projeto de serviço Web ASP.NET Core:

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

Um aplicativo .NET MAUI em execução no emulador Android ou no simulador iOS pode então consumir um serviço web ASP.NET Core a ser executado localmente via HTTP, desde que o serviço web seja iniciado com o perfil http.

Configuração de rede Android

Existem duas abordagens principais para habilitar o tráfego local de texto não criptografado no Android:

• Habilite o tráfego de rede de texto não criptografado para comunicação com todos os domínios. Para obter mais informações, consulte Habilitar tráfego de rede de texto não criptografado para todos os domínios.
• Habilite o tráfego de rede de texto não criptografado para comunicação com o localhost domínio. Para obter mais informações, consulte Habilitar tráfego de rede de texto não criptografado para o domínio localhost.

Habilitar tráfego de rede de texto não criptografado para todos os domínios

O tráfego de rede de texto não cifrado para todos os domínios pode ser ativado definindo a propriedade UsesCleartextTrafficApplication como true. Isso deve ser executado no arquivo Platforms > Android > MainApplication.cs em seu projeto de aplicativo .NET MAUI e deve ser encapsulado em um #if DEBUG para garantir que ele não seja ativado acidentalmente em um aplicativo de produção:

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

Habilitar tráfego de rede de texto não criptografado para o domínio localhost

O tráfego de rede de texto em claro para o domínio localhost pode ser habilitado criando um ficheiro de configuração de segurança de rede. Isso pode ser conseguido adicionando um novo arquivo XML chamado network_security_config.xml à pasta Platforms\Android\Resources\xml em seu projeto de aplicativo .NET MAUI. O arquivo XML deve especificar a seguinte configuração:

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

Em seguida, configure a propriedade networkSecurityConfig no nó do aplicativo no arquivo Platforms\Android\AndroidManifest.xml em seu projeto de aplicativo .NET MAUI:

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

Para obter mais informações sobre arquivos de configuração de segurança de rede, consulte Configuração de segurança de rede em developer.android.com.

Configuração do iOS ATS

Para ativar o tráfego local de texto não criptografado no iOS, você deve desativar o Apple Transport Security (ATS) em seu aplicativo .NET MAUI. Isso pode ser conseguido adicionando a seguinte configuração ao arquivo Platforms\iOS\Info.plist em seu projeto de aplicativo .NET MAUI:

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

Para obter mais informações sobre ATS, consulte Impedindo conexões de rede inseguras no developer.apple.com.

Serviços Web locais em execução via HTTPS

Um aplicativo .net maui executado no emulador Android ou simulador iOS pode consumir um serviço Web ASP.NET Core que está sendo executado localmente por HTTPS. O processo para permitir isso é o seguinte:

1. Confie no certificado de desenvolvimento autoassinado em sua máquina. Para obter mais informações, consulte Confiar no seu certificado de desenvolvimento.
2. Especifique o endereço da sua máquina local. Para obter mais informações, consulte Especificar o endereço da máquina local.
3. Ignore a verificação de segurança do certificado de desenvolvimento local. Para obter mais informações, consulte Ignorar a verificação de segurança do certificado.

Cada ponto será discutido sucessivamente.

Confie no seu certificado de desenvolvimento

A instalação do SDK do .NET Core instala o certificado de desenvolvimento HTTPS do ASP.NET Core no repositório de certificados do utilizador local. No entanto, embora o certificado tenha sido instalado, ele não é confiável. Para confiar no certificado, execute a seguinte etapa única para executar a ferramenta dotnet dev-certs :

dotnet dev-certs https --trust

O comando a seguir fornece ajuda sobre a ferramenta dev-certs:

dotnet dev-certs https --help

Como alternativa, quando você executa um projeto ASP.NET Core 2.1 (ou superior), que usa HTTPS, o Visual Studio detetará se o certificado de desenvolvimento está ausente e se oferecerá para instalá-lo e confiar nele.

Para obter mais informações sobre como habilitar HTTPS local em sua máquina, consulte Habilitar HTTPS local.

Especifique o endereço da máquina local

No código que define a URL do serviço Web local no aplicativo .NET MAUI, verifique se a URL do serviço Web especifica o esquema HTTPS e o nome de host correto. A DeviceInfo classe pode ser usada para detetar a plataforma em que o aplicativo está sendo executado. O nome de host correto pode ser definido da seguinte forma:

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

Para obter mais informações sobre a classe, consulte Informações do DeviceInfodispositivo.

Ignorar a verificação de segurança do certificado

A tentativa de invocar um serviço Web seguro local a partir de uma aplicação .NET MAUI a correr num emulador Android resultará num java.security.cert.CertPathValidatorException a ser lançado, com uma mensagem indicando que a âncora de confiança para o caminho de certificação não foi encontrada. Da mesma forma, tentar invocar um serviço Web seguro local de um aplicativo .NET MAUI em execução em um simulador iOS resultará em um NSURLErrorDomain erro com uma mensagem indicando que o certificado para o servidor é inválido. Esses erros ocorrem porque o certificado de desenvolvimento HTTPS local é autoassinado e os certificados autoassinados não são confiáveis pelo Android ou iOS. Portanto, é necessário ignorar erros SSL quando um aplicativo consome um serviço Web seguro local.

Isso pode ser feito configurando uma instância de HttpClientHandler com um ServerCertificateCustomValidationCallback personalizado, que instrui a classe HttpClient a confiar na comunicação localhost sobre HTTPS. O exemplo a seguir mostra como criar uma instância que ignorará erros de validação de certificado localhost HttpClientHandler :

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);

Um aplicativo .net maui executado no emulador Android ou simulador iOS pode consumir um serviço Web ASP.NET Core que está sendo executado localmente por HTTPS.