Freigeben über

Xamarin.Forms Zuordnungsinitialisierung und Konfiguration

  • Artikel

Das Map-Steuerelement verwendet das native Kartensteuerelement auf jeder Plattform. Dies bietet eine schnelle, vertraute Kartenumgebung für Benutzer, bedeutet jedoch, dass einige Konfigurationsschritte erforderlich sind, um die API-Anforderungen der einzelnen Plattformen einzuhalten.

Karteninitialisierung

Das Map Steuerelement wird von der Xamarin.FormsKARTEN NuGet-Paket, das jedem Projekt in der Projektmappe hinzugefügt werden soll.

Nach der Installation der Xamarin.FormsKARTEN NuGet-Paket muss in jedem Plattformprojekt initialisiert werden.

Unter iOS sollte dies in AppDelegate.cs auftreten, indem sie die Xamarin.FormsMaps.Init Methode nach der Xamarin.Forms.Forms.Init Methode aufruft:

Xamarin.FormsMaps.Init();

Unter Android sollte dies in MainActivity.cs auftreten, indem Sie die Xamarin.FormsMaps.Init Methode nach der Xamarin.Forms.Forms.Init Methode aufrufen:

Xamarin.FormsMaps.Init(this, savedInstanceState);

Auf dem Universelle Windows-Plattform (UWP) sollte dies in MainPage.xaml.cs auftreten, indem sie die Xamarin.FormsMaps.Init Methode aus dem MainPage Konstruktor aufruft:

Xamarin.FormsMaps.Init("INSERT_AUTHENTICATION_TOKEN_HERE");

Informationen zum für UWP erforderlichen Authentifizierungstoken finden Sie unter Universelle Windows-Plattform.

Sobald das NuGet-Paket hinzugefügt wurde und die Initialisierungsmethode innerhalb jeder Anwendung aufgerufen wird, Xamarin.Forms.Maps können APIs im freigegebenen Codeprojekt verwendet werden.

Plattformkonfiguration

Zusätzliche Konfiguration ist unter Android und der Universelle Windows-Plattform (UWP) erforderlich, bevor die Karte angezeigt wird. Darüber hinaus erfordert der Zugriff auf den Standort des Benutzers unter iOS, Android und UWP Standortberechtigungen, die der Anwendung erteilt wurden.

iOS

Das Anzeigen und Interagieren mit einer Karte unter iOS erfordert keine zusätzliche Konfiguration. Um jedoch auf Standortdienste zuzugreifen, müssen Sie die folgenden Schlüssel in Info.plist festlegen:

Zur Unterstützung von iOS 11 und früheren Versionen können Sie alle drei Schlüssel einschließen: NSLocationWhenInUseUsageDescription, , NSLocationAlwaysAndWhenInUseUsageDescriptionund NSLocationAlwaysUsageDescription.

Die XML-Darstellung für diese Schlüssel in Info.plist wird unten angezeigt. Sie sollten die string Werte aktualisieren, um anzugeben, wie Ihre Anwendung die Standortinformationen verwendet:

<key>NSLocationAlwaysUsageDescription</key>
<string>Can we use your location at all times?</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Can we use your location when your application is being used?</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Can we use your location at all times?</string>

Die Info.plist-Einträge können auch in der Quellansicht beim Bearbeiten der Info.plist-Datei hinzugefügt werden:

Info.plist für iOS 8

Eine Eingabeaufforderung wird dann angezeigt, wenn die Anwendung versucht, auf den Standort des Benutzers zuzugreifen und Zugriff anzufordern:

Screenshot der Standortberechtigungsanforderung unter iOS

Android

Der Konfigurationsprozess zum Anzeigen und Interagieren mit einer Karte auf Android lautet:

  1. Rufen Sie einen Google Karten-API-Schlüssel ab, und fügen Sie ihn dem Manifest hinzu.
  2. Geben Sie die Versionsnummer der Google Play-Dienste im Manifest an.
  3. Geben Sie die Anforderung für die Apache HTTP Legacy-Bibliothek im Manifest an.
  4. [optional] Geben Sie die WRITE_EXTERNAL_STORAGE Berechtigung im Manifest an.
  5. [optional] Geben Sie Standortberechtigungen im Manifest an.
  6. [optional] Fordern Sie Die Berechtigungen für den Laufzeitspeicherort in der MainActivity Klasse an.

Ein Beispiel für eine ordnungsgemäß konfigurierte Manifestdatei finden Sie unter AndroidManifest.xml aus der Beispielanwendung.

Rufen Sie einen Google Maps-API-Schlüssel ab

Um die Google Karten-API unter Android zu verwenden, müssen Sie einen API-Schlüssel generieren. Befolgen Sie dazu die Anweisungen unter Abrufen eines Google Karten-API-Schlüssels.

Nachdem Sie einen API-Schlüssel abgerufen haben, muss er innerhalb des <application> Elements der Datei "Properties/AndroidManifest.xml " hinzugefügt werden:

<application ...>
    <meta-data android:name="com.google.android.geo.API_KEY" android:value="PASTE-YOUR-API-KEY-HERE" />
</application>

Dadurch wird der API-Schlüssel in das Manifest eingebettet. Ohne einen gültigen API-Schlüssel zeigt das Map-Steuerelement ein leeres Raster an.

Hinweis

com.google.android.geo.API_KEY ist der empfohlene Metadatenname für den API-Schlüssel. Aus Gründen der Abwärtskompatibilität kann der com.google.android.maps.v2.API_KEY-Metadatenname verwendet werden. Dies ermöglicht jedoch nur die Authentifizierung für die Android Maps API v2.

Damit Ihre APK auf Google Karten zugreifen kann, müssen Sie SHA-1-Fingerabdrücke und Paketnamen für jeden Keystore (Debug und Release) einschließen, den Sie zum Signieren Ihrer APK verwenden. Wenn Sie beispielsweise einen Computer für das Debuggen und einen anderen Computer zum Generieren der Release-APK verwenden, müssen Sie den Fingerabdruck des SHA-1-Zertifikats aus dem Debug-Keystore des ersten Computers und den Fingerabdruck des SHA-1-Zertifikats aus dem Release-Keystore des zweiten Computers angeben. Denken Sie auch daran, die wichtigsten Anmeldeinformationen zu bearbeiten, wenn sich der Paketname der App ändert. Siehe Abrufen eines Google Karten-API-Schlüssels.

Geben Sie die Versionsnummer der Google Play-Dienste an

Fügen Sie die folgende Deklaration im <application>-Element von AndroidManifest.xml hinzu:

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />

Dadurch wird die Version der Google Play-Dienste eingebettet, mit denen die Anwendung kompiliert wurde, in das Manifest.

Angeben der Anforderung für die Apache HTTP Legacy-Bibliothek

Wenn Ihre Xamarin.Forms Anwendung auf API 28 oder höher ausgerichtet ist, müssen Sie die folgende Deklaration innerhalb des <application> Elements von AndroidManifest.xml hinzufügen:

<uses-library android:name="org.apache.http.legacy" android:required="false" />

Dies weist die Anwendung an, die Apache Http-Clientbibliothek zu verwenden, die aus dem bootclasspath in Android 9 entfernt wurde.

Angeben der WRITE_EXTERNAL_STORAGE-Berechtigung

Wenn Ihre Anwendung auf API 22 oder niedriger ausgerichtet ist, kann es erforderlich sein, die WRITE_EXTERNAL_STORAGE Berechtigung zum Manifest als untergeordnetes <manifest> Element des Elements hinzuzufügen:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Dies ist nicht erforderlich, wenn Ihre Anwendung auf API 23 oder höher ausgerichtet ist.

Angeben von Standortberechtigungen

Wenn Ihre Anwendung auf den Speicherort des Benutzers zugreifen muss, müssen Sie die Berechtigung anfordern, indem Sie das ACCESS_COARSE_LOCATIONACCESS_FINE_LOCATION Manifest (oder beide) als untergeordnetes Element hinzufügen <manifest> :

<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.companyname.myapp">
  ...
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

Die ACCESS_COARSE_LOCATION-Berechtigung ermöglicht der API die Verwendung der WLAN- oder mobilen Datenverbindung oder beide, um den Standort des Geräts zu bestimmen. Die ACCESS_FINE_LOCATION-Berechtigungen ermöglichen der API die Verwendung des globalen Positionierungssystems (GPS), der WLAN- oder mobilen Datenverbindung, den Standort so genau wie möglich zu bestimmen.

Alternativ können diese Berechtigungen mithilfe des Manifest-Editors aktiviert werden, um die folgenden Berechtigungen hinzuzufügen:

  • AccessCoarseLocation
  • AccessFineLocation

Diese werden im folgenden Screenshot gezeigt:

Erforderliche Berechtigungen für Android

Anfordern von Berechtigungen für den Laufzeitspeicherort

Wenn Ihre Anwendung auf API 23 oder höher ausgerichtet ist und auf den Standort des Benutzers zugreifen muss, muss überprüft werden, ob sie zur Laufzeit über die erforderliche Berechtigung verfügt, und sie anfordern, wenn sie sie nicht hat. Dies kann folgendermaßen erfüllt werden:

  1. Fügen Sie in der MainActivity Klasse die folgenden Felder hinzu:

    const int RequestLocationId = 0;

readonly string[] LocationPermissions =
{
    Manifest.Permission.AccessCoarseLocation,
    Manifest.Permission.AccessFineLocation
};

  2. Fügen Sie in der MainActivity Klasse die folgende OnStart Außerkraftsetzung hinzu:

    protected override void OnStart()
{
    base.OnStart();

    if ((int)Build.VERSION.SdkInt >= 23)
    {
        if (CheckSelfPermission(Manifest.Permission.AccessFineLocation) != Permission.Granted)
        {
            RequestPermissions(LocationPermissions, RequestLocationId);
        }
        else
        {
            // Permissions already granted - display a message.
        }
    }
}

    Sofern die Anwendung auf API 23 oder höher ausgerichtet ist, führt dieser Code eine Laufzeitberechtigungsprüfung für die AccessFineLocation Berechtigung aus. Wenn keine Berechtigung erteilt wurde, erfolgt eine Berechtigungsanforderung durch Aufrufen der RequestPermissions Methode.

  3. Fügen Sie in der MainActivity Klasse die folgende OnRequestPermissionsResult Außerkraftsetzung hinzu:

    public override void OnRequestPermissionsResult(int requestCode, string[] permissions, [GeneratedEnum] Permission[] grantResults)
{
    if (requestCode == RequestLocationId)
    {
        if ((grantResults.Length == 1) && (grantResults[0] == (int)Permission.Granted))
            // Permissions granted - display a message.
        else
            // Permissions denied - display a message.
    }
    else
    {
        base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
    }
}

    Diese Außerkraftsetzung behandelt das Ergebnis der Berechtigungsanforderung.

Der Gesamteffekt dieses Codes lautet: Wenn die Anwendung den Standort des Benutzers anfordert, wird das folgende Dialogfeld angezeigt, in dem die Berechtigung angefordert wird:

Screenshot der Standortberechtigungsanforderung unter Android

Universelle Windows-Plattform

Auf UWP muss Ihre Anwendung authentifiziert werden, bevor sie kartendienste anzeigen und nutzen kann. Um Ihre Anwendung zu authentifizieren, müssen Sie einen Kartenauthentifizierungsschlüssel angeben. Weitere Informationen finden Sie unter Anfordern eines Kartenauthentifizierungsschlüssels. Das Authentifizierungstoken sollte dann im FormsMaps.Init("AUTHORIZATION_TOKEN") Methodenaufruf angegeben werden, um die Anwendung mit Bing Karten zu authentifizieren.

Hinweis

Wenn Sie unter UWP Kartendienste wie geocodierung verwenden möchten, müssen Sie die MapService.ServiceToken Eigenschaft auch auf den Wert des Authentifizierungsschlüssels festlegen. Dies kann mit der folgenden Codezeile erreicht werden: Windows.Services.Maps.MapService.ServiceToken = "INSERT_AUTH_TOKEN_HERE";.

Wenn Ihre Anwendung auf den Standort des Benutzers zugreifen muss, müssen Sie die Standortfunktion im Paketmanifest aktivieren. Dies kann folgendermaßen erfüllt werden:

  1. Doppelklicken Sie in Projektmappen-Explorer auf "package.appxmanifest", und wählen Sie die Registerkarte "Funktionen" aus.

  2. Aktivieren Sie in der Liste "Funktionen " das Kontrollkästchen für "Speicherort". Dadurch wird der Paketmanifestdatei die location Gerätefunktion hinzugefügt.

    <Capabilities>
  <!-- DeviceCapability elements must follow Capability elements (if present) -->
  <DeviceCapability Name="location"/>
</Capabilities>

Releasebuilds

UWP-Releasebuilds verwenden die native .NET-Kompilierung, um die Anwendung direkt in systemeigenen Code zu kompilieren. Dies hat jedoch zur Folge, dass der Renderer für das Map Steuerelement unter UWP aus der ausführbaren Datei verknüpft werden kann. Dies kann mithilfe einer UWP-spezifischen Überladung der Forms.Init Methode in App.xaml.cs behoben werden:

var assembliesToInclude = new [] { typeof(Xamarin.Forms.Maps.UWP.MapRenderer).GetTypeInfo().Assembly };
Xamarin.Forms.Forms.Init(e, assembliesToInclude);

Dieser Code übergibt die Assembly, in der sich die Xamarin.Forms.Maps.UWP.MapRenderer Klasse befindet, an die Forms.Init Methode. Dadurch wird sichergestellt, dass die Assembly nicht aus der ausführbaren Datei durch den systemeigenen Kompilierungsprozess von .NET verknüpft ist.

Wichtig

Wenn Dies nicht der Fall ist, wird das Map Steuerelement beim Ausführen eines Releasebuilds nicht angezeigt.