Aan de slag met Azure SDK en Apache Maven

  • Artikel

In dit artikel leest u hoe u Apache Maven gebruikt om toepassingen te bouwen met de Azure SDK voor Java. In dit artikel stelt u een nieuw project in met Maven, bouwt u projecten met Maven en gebruikt u de systeemeigen hulpprogramma's voor installatiekopieën van GraalVM om platformspecifieke systeemeigen binaire bestanden te maken.

Het Azure SDK voor Java-project bevat een Maven-archetype waarmee het opstarten van een nieuw project kan worden versneld. Met de Azure SDK voor Java Maven-archetype wordt een nieuwe toepassing gemaakt, met bestanden en een mapstructuur die de aanbevolen procedures volgt. Met name de Azure SDK voor Java Maven-archetype maakt een nieuw Maven-project met de volgende functies:

  • Een afhankelijkheid van de nieuwste azure-sdk-bom BOM-release, die ervoor zorgt dat alle afhankelijkheden voor Azure SDK voor Java zijn uitgelijnd en u de beste ontwikkelaarservaring biedt.
  • Ingebouwde ondersteuning voor systeemeigen graalVM-installatiekopiecompilatie.
  • Ondersteuning voor het genereren van een nieuw project met een opgegeven set Azure SDK voor Java-clientbibliotheken.
  • Integratie met de Azure SDK voor Java-buildhulpprogramma's, die build-time-analyse van uw project biedt om ervoor te zorgen dat er veel aanbevolen procedures worden gevolgd.

Vereisten

Een nieuw Maven-project maken

De Azure SDK voor Java Maven-archetype wordt gepubliceerd naar Maven Central. Dit betekent dat u het archetype rechtstreeks kunt gebruiken om een nieuwe toepassing te bootstrapen met de volgende opdracht:

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

Nadat u deze opdracht hebt ingevoerd, vraagt een reeks prompts om details over uw project, zodat het archetype de juiste uitvoer voor u kan genereren. In de volgende tabel worden de eigenschappen beschreven waarvoor u waarden moet opgeven:

Name Beschrijving
groupId (Vereist) De Maven groupId die moet worden gebruikt in het POM-bestand dat is gemaakt voor het gegenereerde project.
artifactId (Vereist) De Maven artifactId die moet worden gebruikt in het POM-bestand dat is gemaakt voor het gegenereerde project.
package (Optioneel) De pakketnaam waar de gegenereerde code in moet worden geplaatst. Afgeleid van de groupId waarde als deze niet is opgegeven.
azureLibraries (Optioneel) Een door komma's gescheiden lijst met Azure SDK voor Java-bibliotheken met behulp van hun Maven-artefact-id's. Zie Azure SDK-releases voor een lijst met dergelijke artefact-id's.
enableGraalVM (Optioneel) false om aan te geven dat het gegenereerde Maven POM-bestand geen ondersteuning moet bevatten voor het compileren van uw toepassing naar een systeemeigen installatiekopieën met behulp van GraalVM; anders waar. De standaardwaarde is waar.
javaVersion (Optioneel) De minimale versie van de JDK die moet worden gebruikt bij het bouwen van het gegenereerde project, zoals 8, 11 of 17. De standaardwaarde is de nieuwste LTS-release (momenteel 17). De minimumwaarde is 8.
junitVersion (Optioneel) De versie van JUnit die moet worden opgenomen als een afhankelijkheid. De standaardwaarde is 5. Geldige waarden 4 en 5.

U kunt deze waarden ook opgeven wanneer u de eerder weergegeven archetypeopdracht aanroept. Deze benadering is bijvoorbeeld handig voor automatiseringsdoeleinden. U kunt de waarden opgeven als parameters met behulp van de standaard-Maven-syntaxis voor het toevoegen -D aan de parameternaam, bijvoorbeeld:

-DjavaVersion=17

Ondersteuning voor Java-versies

Als best practice moet u een Java LTS-release gebruiken bij het implementeren in productie. Standaard selecteert het Azure SDK Maven-archetype de nieuwste LTS-release, waarmee momenteel een Java 17-basislijn wordt ingesteld. U kunt het standaardgedrag echter overschrijven door de javaVersion parameter in te stellen.

Het hulpprogramma Azure SDK voor Java-build gebruiken

Met de Azure SDK voor Java-project wordt een Maven-buildhulpprogramma geleverd dat u in uw projecten kunt opnemen. Dit hulpprogramma wordt lokaal uitgevoerd en verzendt geen gegevens naar Microsoft. U kunt het hulpprogramma configureren om een rapport te genereren of de build uit te voeren wanneer aan bepaalde voorwaarden wordt voldaan. Dit is handig om te zorgen voor naleving van talloze aanbevolen procedures, zoals de volgende procedures:

  • Validatie van het juiste gebruik van de azure-sdk-for-java bom, inclusief het gebruik van de nieuwste versie, en het vertrouwen erop om afhankelijke versies te definiëren in Azure SDK voor Java-clientbibliotheken. Zie de Sectie Azure SDK voor Java toevoegen aan een bestaand project voor meer informatie.
  • Validatie dat historische Azure-clientbibliotheken niet worden gebruikt wanneer er nieuwere en verbeterde versies bestaan.

Het rapport biedt ook inzicht in het gebruik van bèta-API's.

U kunt het buildhulpprogramma configureren in een Maven POM-bestand van een project, zoals wordt weergegeven in het volgende voorbeeld. Vervang de {latest_version} tijdelijke aanduiding door de nieuwste versie die online wordt vermeld.

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

Nadat u het build-hulpprogramma hebt toegevoegd aan een Maven-project, kunt u het hulpprogramma uitvoeren door het aan te roepen mvn compile azure:run. Afhankelijk van de opgegeven configuratie kunt u verwachten dat er buildfouten optreden of rapportbestanden die u kunnen informeren over mogelijke problemen voordat ze ernstiger worden. U wordt aangeraden dit hulpprogramma uit te voeren als onderdeel van uw CI/CD-pijplijn. Naarmate het buildhulpprogramma zich ontwikkelt, publiceren we nieuwe releases en raden we ontwikkelaars aan regelmatig te controleren op nieuwe releases en updates.

Het is mogelijk om het buildhulpprogramma te configureren om bepaalde functies in of uit te schakelen. Voeg voor deze configuratie een configuration sectie toe in de XML die eerder is weergegeven. Configureer in die sectie de instellingen die worden weergegeven in de volgende tabel. Elke configuratie die niet expliciet wordt vermeld, gebruikt de standaardwaarde die is opgegeven in de tabel.

Eigenschapsnaam Standaardwaarde Beschrijving
validateAzureSdkBomUsed true Zorgt ervoor dat voor het project de azure-sdk-for-java BOM correct wordt verwezen, zodat afhankelijkheden van de Azure SDK voor Java-clientbibliotheek hun versies van de BOM kunnen overnemen.
validateLatestBomVersionUsed true Zorgt ervoor dat afhankelijkheden up-to-date blijven door terug te rapporteren (of mislukt de build) als er een nieuwere azure-sdk-for-java-BOM bestaat. U kunt altijd de nieuwste versie online vinden.
validateBomVersionsAreUsed true Zorgt ervoor dat, wanneer een afhankelijkheid beschikbaar is vanuit de azure-sdk-for-java BOM, de versie niet handmatig wordt overschreven.
validateNoDeprecatedMicrosoftLibraryUsed true Zorgt ervoor dat het project geen gebruik maakt van Azure-bibliotheken van de vorige generatie. Het is onwaarschijnlijk dat het gebruik van de nieuwe en vorige generatie bibliotheken in één project een probleem veroorzaakt, maar resulteert in een suboptimale ontwikkelaarservaring.
validateNoBetaLibraryUsed false Sommige Azure SDK voor Java-clientbibliotheken hebben bètaversies, met versietekenreeksen in de vorm x.y.z-beta.n. Als u deze functie inschakelt, zorgt u ervoor dat er geen bètabibliotheken worden gebruikt.
validateNoBetaApiUsed true Azure SDK voor Java-clientbibliotheken hebben soms GA-releases met methoden met aantekeningen @Beta. Met deze controle wordt gecontroleerd of dergelijke methoden worden gebruikt.
sendToMicrosoft true Hiermee geeft u op of het buildrapport naar Microsoft moet worden verzonden voor telemetriedoeleinden. Dit helpt het ontwikkelteam te helpen bij het prioriteren van documentatie, voorbeelden en verbeterde api's voor gemak. Er wordt geen door de gebruiker identificeerbare inhoud verzonden.
reportFile - (Optioneel) Hiermee geeft u de locatie op waar het buildrapport naar moet worden geschreven, in JSON-indeling. Als dit niet is opgegeven, wordt er geen rapport geschreven en wordt er een samenvatting van de build of de juiste buildfouten weergegeven in de terminal.

Azure SDK voor Java toevoegen aan een bestaand project

Om versiebeheer van afhankelijkheden eenvoudiger te maken, publiceert het Azure SDK voor Java-team elke maand de Azure SDK voor Java-clientlijst . Dit BOM-bestand bevat alle Algemeen beschikbare Azure SDK voor Java-clientpakketten met hun compatibele afhankelijkheidsversie.

Als u afhankelijkheidsversies wilt gebruiken voor een Azure SDK voor Java-clientbibliotheek die zich in de bom bevindt, neemt u het volgende codefragment op in het bestand project pom.xml . Vervang de {bom_version_to_target} tijdelijke aanduiding door de nieuwste versie van de Azure SDK voor Java BOM. Vervang de {artifactId} tijdelijke aanduiding door de naam van het Azure Service SDK-pakket.

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

U vindt alle releases van de Azure SDK voor Java-client BOM op azure-sdk-bom. U wordt aangeraden de nieuwste versie te gebruiken om te profiteren van de nieuwste functies van de Azure SDK voor Java-clientbibliotheken.

Door Maven te gebruiken om projectafhankelijkheden te definiëren, kunt u het beheer van uw projecten eenvoudiger maken. Met de Azure SDK BOM en Azure SDK Maven-archetype kunt u uw project versnellen terwijl u meer vertrouwen hebt in uw versiebeheer op de lange termijn. U wordt aangeraden de bom te gebruiken om afhankelijkheden op elkaar af te stemmen en up-to-date te houden.

Naast het toevoegen van de Azure SDK BOM, raden we u ook aan de Azure SDK voor Java-build-hulpprogramma op te tellen. Dit hulpprogramma helpt bij het vaststellen van veel problemen die vaak optreden bij het bouwen van toepassingen, zoals eerder beschreven in dit artikel.

Een pakket opnemen dat niet in de bom staat

De BOM van de Azure SDK voor Java-client bevat alleen algemeen beschikbare (GA)-bibliotheken. Als u afhankelijk wilt zijn van een pakket dat zich nog in de bètaversie bevindt of op een andere bibliotheekversie dan het pakket dat in de bom is opgenomen, kunt u de Versie van de Maven-afhankelijkheid opgeven, samen met de groupId en artifactId in de sectie Afhankelijkheid. U kunt ervoor kiezen om afhankelijkheden te hebben die gebruikmaken van BOM-versies en -afhankelijkheden met overschreven versies in hetzelfde project POM-bestand, zoals wordt weergegeven in het volgende voorbeeld:

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

Als u deze methode gebruikt en versies rechtstreeks in uw project opgeeft, kunnen er conflicten optreden met de versie van afhankelijkheden. Deze conflicten ontstaan omdat verschillende pakketten mogelijk afhankelijk zijn van verschillende versies van algemene afhankelijkheden en deze versies mogelijk niet compatibel zijn met elkaar. Wanneer er conflicten optreden, kunt u ongewenst gedrag ervaren tijdens het compileren of runtime. We raden u aan om te vertrouwen op versies die zich in de Azure SDK-BOM bevinden, tenzij dat nodig is. Zie Problemen met afhankelijkheidsversies oplossen voor meer informatie over het omgaan met afhankelijkheden bij het gebruik van de Azure SDK voor Java.

Een systeemeigen installatiekopieën bouwen met GraalVM

U kunt GraalVM gebruiken om een systeemeigen installatiekopieën van een Java-toepassing te maken. GraalVM compileert de Java-code van tevoren in systeemeigen machinecode, wat in bepaalde situaties drastische prestatieverbeteringen kan opleveren. De Azure SDK voor Java biedt de benodigde metagegevens in elk van de clientbibliotheken ter ondersteuning van graalVM systeemeigen compilatie van installatiekopieën.

Om aan de slag te gaan, moet u GraalVM installeren en uw ontwikkelsysteem voorbereiden voor het compileren van systeemeigen installatiekopieën. Het installatieproces voor GraalVM is eenvoudig en de GraalVM-documentatie bevat stapsgewijze instructies voor het installeren van GraalVM en het gebruik van GraalVM om systeemeigen installatiekopieën te installeren. Volg de sectie vereisten zorgvuldig om de benodigde systeemeigen compilers voor uw besturingssysteem te installeren.

De Azure SDK voor Java Maven-archetype kan uw build configureren ter ondersteuning van graalVM systeemeigen compilatie van installatiekopieën, maar u kunt deze ook toevoegen aan een bestaande Maven-build. U vindt instructies voor Maven op de GraalVM-website.

Vervolgens kunt u een systeemeigen installatiekopieën maken. U kunt standaard-Maven-hulpprogramma's gebruiken om de systeemeigen GraalVM-installatiekopieën te gebruiken. Gebruik voor Maven de volgende opdracht:

mvn clean package -Pnative

Nadat u deze opdracht hebt uitgevoerd, voert GraalVM een systeemeigen uitvoerbaar bestand uit voor het platform waarop deze wordt uitgevoerd. Het uitvoerbare bestand wordt weergegeven in de map Maven /target van uw project. U kunt uw toepassing nu uitvoeren met dit uitvoerbare bestand en moet op dezelfde manier worden uitgevoerd als een standaard Java-toepassing.

Volgende stappen

Aan de slag met Azure-extensies voor IntelliJ en Eclipse