Erste Schritte mit Azure SDK und Maven

In diesem Artikel erfahren Sie, wie Sie Apache Maven zum Erstellen von Anwendungen mit dem Azure SDK für Java verwenden. In diesem Artikel richten Sie ein neues Projekt mit Maven ein, erstellen Projekte mit Maven und verwenden die nativen GraalVM-Imagetools, um plattformspezifische native Binärdateien zu erstellen.

Das Azure SDK für Java-Projekt enthält einen Maven-Archetyp, der das Bootstrapping eines neuen Projekts beschleunigen kann. Das Azure SDK für Java Maven Archetype erstellt eine neue Anwendung mit Dateien und einer Verzeichnisstruktur, die bewährte Methoden befolgt. Insbesondere erstellt das Azure SDK für Java Maven Archetype ein neues Maven-Projekt mit den folgenden Features:

  • Eine Abhängigkeit von der neuesten azure-sdk-bom-BOM-Version, die sicherstellt, dass alle Abhängigkeiten für Azure SDK for Java aufeinander abgestimmt sind, und Ihnen die bestmögliche Erfahrung für Entwickler bietet.
  • Integrierte Unterstützung für die Kompilierung nativer Images von GraalVM.
  • Unterstützung für das Generieren eines neuen Projekts mit einer bestimmten Gruppe von Azure SDK für Java-Clientbibliotheken.
  • Integration mit dem Azure SDK für Java-Build-Tools, die eine Analyse Ihres Projekts zur Buildzeit ermöglicht, um sicherzustellen, dass viele bewährte Methoden eingehalten werden.

Voraussetzungen

Erstellen eines neuen Maven-Projekts

Die Azure SDK für Java Maven Archetype ist auf Maven Central verfügbar. Sie können den Archetyp direkt verwenden, um eine neue Anwendung zu bootstrapieren, indem Sie den folgenden Befehl ausführen:

mvn archetype:generate \
    -DarchetypeGroupId=com.azure.tools \
    -DarchetypeArtifactId=azure-sdk-archetype

Nachdem Sie diesen Befehl eingegeben haben, werden in einer Reihe von Eingabeaufforderungen Details zu Ihrem Projekt angefordert, damit der Archetyp die richtige Ausgabe für Sie generieren kann. In der folgenden Tabelle werden die Eigenschaften beschrieben, für die Sie Werte bereitstellen müssen:

Name Beschreibung
groupId (Erforderlich) Das Maven groupId, das in der für das generierte Projekt erstellten POM-Datei verwendet werden soll.
artifactId (Erforderlich) Das Maven artifactId, das in der für das generierte Projekt erstellten POM-Datei verwendet werden soll.
package (Optional) Der Paketname, in den der generierte Code eingefügt werden soll. Wird von groupId abgeleitet, wenn nicht angegeben.
azureLibraries (Optional) Eine durch Komma getrennte Liste von Azure SDK for Java-Bibliotheken unter Verwendung ihrer Maven Artefakt-IDs. Eine Liste solcher Artefakt-IDs finden Sie unter Azure SDK Releases.
enableGraalVM (Optional) false um anzugeben, dass die generierte Maven POM-Datei keine Unterstützung für die Kompilierung Ihrer Anwendung in ein natives Image mit GraalVM enthalten soll; andernfalls true. Der Standardwert ist true.
javaVersion (Optional) Die Mindestversion des JDK, die beim Erstellen des generierten Projekts als Ziel festgelegt werden soll, z. B. 8, 11oder 17. Der Standardwert ist die neueste LTS-Version (derzeit 17). Der Minimalwert ist 8.
junitVersion (Optional) Die Version von JUnit, die als Abhängigkeit eingebunden werden soll. Der Standardwert ist 5. Gültige Werte sind 4 und 5.

Alternativ können Sie diese Werte angeben, wenn Sie den zuvor gezeigten Archetypbefehl aufrufen. Dieser Ansatz ist z. B. für Automatisierungszwecke nützlich. Sie können die Werte als Parameter angeben, indem Sie z. B. die standardmäßige Maven-Syntax zum Anfügen -D an den Parameternamen verwenden:

-DjavaVersion=17

Unterstützung für Java-Versionen

Verwenden Sie als bewährte Methode beim Bereitstellen in der Produktion eine Java LTS-Version. Standardmäßig wählt der Azure SDK Maven Archetyp die neueste LTS-Version aus, die derzeit einen Java 17-Standard festlegt. Sie können das Standardverhalten jedoch außer Kraft setzen, indem Sie den javaVersion-Parameter festlegen.

Verwenden des Azure SDK für Java-Buildtools

Die Azure SDK für Java Projekt enthält ein Maven-Buildtool, das Sie Ihren Projekten hinzufügen können. Dieses Tool wird lokal ausgeführt und sendet keine Daten an Microsoft. Sie können das Tool so konfigurieren, dass ein Bericht generiert wird oder der Build fehlschlägt, wenn bestimmte Bedingungen erfüllt sind. Dieses Feature trägt dazu bei, die Einhaltung bewährter Methoden wie die folgenden Methoden sicherzustellen:

  • Validierung der korrekten Verwendung der azure-sdk-for-java-BOM, einschließlich der Verwendung der neuesten Version und der Festlegung von Abhängigkeitsversionen auf Azure SDK für Java Client-Bibliotheken. Weitere Informationen finden Sie im Abschnitt Hinzufügen von Azure SDK für Java zu einem vorhandenen Projekt.
  • Überprüfung, dass historische Azure Clientbibliotheken nicht verwendet werden, wenn neuere und verbesserte Versionen vorhanden sind.

Der Bericht bietet auch Einblicke in die Verwendung von Beta-APIs.

Sie können das Buildtool in einer Maven POM-Projektdatei konfigurieren, wie im folgenden Beispiel gezeigt. Stellen Sie sicher, dass Sie den {latest_version}-Platzhalter durch die neueste online aufgelistete Version ersetzen.

<build>
  <plugins>
    <plugin>
      <groupId>com.azure.tools</groupId>
      <artifactId>azure-sdk-build-tool</artifactId>
      <version>{latest_version}</version>
    </plugin>
  </plugins>
</build>

Nachdem Sie das Build-Tool zu einem Maven-Projekt hinzugefügt haben, führen Sie das Build-Tool aus, indem Sie mvn compile azure:run aufrufen. Abhängig von der von Ihnen bereitgestellten Konfiguration können Sie davon ausgehen, dass Buildfehler oder generierte Dateien angezeigt werden, die Sie über potenzielle Probleme informieren können, bevor sie ernster werden. Führen Sie dieses Tool als Teil Ihrer CI/CD-Pipeline aus. Während sich das Buildtool weiterentwickelt, veröffentlicht das Entwicklungsteam neue Versionen. Suchen Sie häufig nach neuen Versionen und aktualisieren Sie nach Bedarf.

Sie können das Buildtool so konfigurieren, dass bestimmte Features aktiviert oder deaktiviert werden. Fügen Sie für diese Konfiguration einen configuration Abschnitt im zuvor gezeigten XML-Code hinzu. Konfigurieren Sie in diesem Abschnitt die einstellungen, die in der folgenden Tabelle angezeigt werden. Jede nicht explizit erwähnte Konfiguration verwendet den in der Tabelle angegebenen Standardwert.

Eigenschaftenname Standardwert Beschreibung
validateAzureSdkBomUsed Wahr Stellt sicher, dass das Projekt entsprechend auf das azure-sdk-for-java BOM verweist, sodass Azure SDK für Java Clientbibliotheksabhängigkeiten ihre Versionen aus der BOM abrufen.
validateLatestBomVersionUsed Wahr Stellt sicher, dass Abhängigkeiten auf dem neuesten Stand bleiben, indem sie den Build zurückmelden (oder fehlschlagen), wenn ein neuerer azure-sdk-for-java BOM vorhanden ist. Sie können die neueste Version immer online finden.
validateBomVersionsAreUsed Wahr Stellt sicher, dass die Version, in der eine Abhängigkeit aus dem azure-sdk-for-java BOM verfügbar ist, nicht manuell außer Kraft gesetzt wird.
validateNoDeprecatedMicrosoftLibraryUsed Wahr Stellt sicher, dass das Projekt keine Bibliotheken der vorherigen Generation Azure verwendet. Die Verwendung der neuen und der Bibliotheken der vorherigen Generation in einem einzigen Projekt ist unwahrscheinlich, dass ein Problem verursacht wird, was jedoch zu einer suboptimalen Entwicklererfahrung führt.
validateNoBetaLibraryUsed Falsch Einige Azure SDK für Java-Clientbibliotheken verfügen über Betaversionen mit Versionszeichenfolgen in form x.y.z-beta.n. Durch aktivieren dieses Feature wird sichergestellt, dass keine Betabibliotheken verwendet werden.
validateNoBetaApiUsed Wahr Azure SDK für Java Client-Bibliotheken haben manchmal AV-Versionen mit Methoden, die mit @Beta angemerkt sind. Bei dieser Überprüfung wird überprüft, ob solche Methoden verwendet werden.
sendToMicrosoft Wahr Gibt an, ob der Buildbericht zu Telemetriezwecken an Microsoft gesendet werden soll. Dieser Bericht hilft ihnen dabei, das Entwicklungsteam zu unterstützen, wo Dokumentation, Beispiele und verbesserte Komfort-APIs priorisiert werden sollen. Es werden keine benutzeridentifizierbaren Inhalte übermittelt.
reportFile - (Optional) Gibt den Speicherort an, an den der Build-Bericht im JSON-Format geliefert werden soll. Wenn nicht angegeben, wird kein Bericht geschrieben, und im Terminal wird eine Zusammenfassung des Builds oder der entsprechenden Buildfehler angezeigt.

Hinzufügen des Azure SDK für Java zu einem vorhandenen Projekt

Um die Verwaltung der Abhängigkeitsversion zu vereinfachen, veröffentlicht das Azure SDK für Java Team die Azure SDK für Java Client-BOM jeden Monat. Diese BOM-Datei enthält alle allgemein verfügbaren (GA)-Azure SDK für Java Clientpakete mit ihren kompatiblen Abhängigkeitsversionen.

Wenn Sie die Abhängigkeitsversionen für eine Clientbibliothek des Azure SDK für Java verwenden möchten, die im BOM aufgeführt ist, fügen Sie der Datei pom.xml des Projekts den folgenden Codeausschnitt hinzu. Ersetzen Sie den {bom_version_to_target}-Platzhalter durch die neueste Version der Azure SDK for Java-BOM. Ersetzen Sie den {artifactId} Platzhalter durch den Azure-Service-SDK-Paketnamen.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>{bom_version_to_target}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>{artifactId}</artifactId>
  </dependency>
</dependencies>

Sie finden alle Versionen der Azure SDK for Java Client-BOM unter azure-sdk-bom. Verwenden Sie die neueste Version, um die neuesten Features des Azure SDK für Java Clientbibliotheken zu nutzen.

Die Verwendung von Maven zum Definieren von Projektabhängigkeiten kann die Verwaltung Ihrer Projekte vereinfachen. Mithilfe der Azure SDK BOM und Azure SDK Maven Archetype können Sie Ihr Projekt beschleunigen und gleichzeitig langfristig sicherer über ihre Abhängigkeitsversionsverwaltung sein. Verwenden Sie die BOM, um Abhängigkeiten abgestimmt und auf dem neuesten Stand zu halten.

Zusätzlich zum Hinzufügen der Azure SDK BOM sollten Sie auch das Buildtool des Azure SDK für Java einbinden. Dieses Tool hilft bei der Diagnose vieler Probleme, die beim Erstellen von Anwendungen auftreten, wie zuvor in diesem Artikel beschrieben.

Ein Paket einbeziehen, das nicht in der BOM enthalten ist

Die Azure SDK für Java Client-BOM umfasst nur allgemein verfügbare (GA)-Bibliotheken. Wenn Sie ein Paket als Abhängigkeit verwenden möchten, das sich noch im Beta-Status befindet, oder eine andere Bibliotheksversion als die in der BOM enthaltene verwenden möchten, geben Sie im dependency-Abschnitt die Maven-Abhängigkeitsversion zusammen mit groupId und artifactId an. Sie können wählen, ob Sie Abhängigkeiten, die BOM-Versionen verwenden, und Abhängigkeiten mit überschriebenen Versionen in der gleichen Projekt-POM-Datei haben möchten, wie im folgenden Beispiel gezeigt:

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventhubs</artifactId> <!-- Use the dependency version that is in the BOM -->
  </dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-servicebus</artifactId>
    <version>7.4.0</version> <!-- Override the Service Bus dependency version specified in the BOM -->
  </dependency>
</dependencies>

Wenn Sie diesen Ansatz verwenden und die Versionen direkt in Ihrem Projekt angeben, kann es zu Versionskonflikten in den Abhängigkeiten kommen. Diese Konflikte treten auf, da unterschiedliche Pakete möglicherweise von verschiedenen Versionen gemeinsamer Abhängigkeiten abhängen, und diese Versionen sind möglicherweise nicht miteinander kompatibel. Wenn Konflikte auftreten, kann es zu unerwünschtem Verhalten bei der Kompilierung oder zur Laufzeit kommen. Verlassen Sie sich auf Versionen, die sich in der Azure SDK BOM befinden, sofern nicht erforderlich. Weitere Informationen zum Umgang mit Abhängigkeiten bei Verwendung des Azure SDK für Java finden Sie unter Problembehandlung bei Abhängigkeitsversionskonflikten.

Ein natives Image mit GraalVM erstellen

Sie können GraalVM verwenden, um ein systemeigenes Image einer Java-Anwendung zu erstellen. GraalVM kompiliert den Java-Code vorab in systemeigenen Computercode, was zu drastischen Leistungsgewinnen in bestimmten Situationen führen kann. Das Azure SDK für Java stellt die erforderlichen Metadaten in den einzelnen Clientbibliotheken zur Unterstützung der nativen GraalVM-Imagekompilierung bereit.

Um zu beginnen, installieren Sie GraalVM, und bereiten Sie Ihr Entwicklungssystem für die Kompilierung nativer Images vor. Der Installationsprozess für GraalVM ist unkompliziert und die GraalVM-Dokumentation bietet eine schrittweise Anleitung für die Installation von GraalVM und die Verwendung von GraalVM zur Installation von Native-Image. Befolgen Sie den Abschnitt Voraussetzungen sorgfältig, um die notwendigen nativen Compiler für Ihr Betriebssystem zu installieren.

Mit dem Azure SDK für Java Maven-Archetyp können Sie Ihren Build so konfigurieren, dass er die native Image-Kompilierung von GraalVM unterstützt, aber Sie können ihn auch zu einem bestehenden Maven-Build hinzufügen. Anweisungen zu Maven finden Sie auf der GraalVM-Website.

Als nächstes sind Sie bereit, einen nativen Image-Build auszuführen. Sie können standardmäßige Maven-Tools verwenden, um GraalVM Native Image zu verwenden. Verwenden Sie für Maven den folgenden Befehl:

mvn clean package -Pnative

Nachdem Sie diesen Befehl ausgeführt haben, gibt GraalVM eine native ausführbare Datei für die Plattform aus, auf der es ausgeführt wird. Die ausführbare Datei wird im Verzeichnis "Maven /target" Ihres Projekts angezeigt. Sie können Ihre Anwendung jetzt mit dieser ausführbaren Datei ausführen, und sie sollte ähnlich wie eine Standard-Java-Anwendung ausgeführt werden.

Nächste Schritte

Erste Schritte mit Azure-Erweiterungen für IntelliJ und Eclipse

  • Last updated on