Kom igång med Azure SDK och Apache Maven

Artikel
01/20/2025

Den här artikeln visar hur du använder Apache Maven för att skapa program med Azure SDK för Java. I den här artikeln konfigurerar du ett nytt projekt med Maven, skapar projekt med Maven och använder graalVM-avbildningsverktyget för att skapa plattformsspecifika interna binärfiler.

Azure SDK för Java-projektet innehåller en Maven-arketyp som kan påskynda start av ett nytt projekt. Azure SDK för Java Maven-arketypen skapar ett nytt program med filer och en katalogstruktur som följer bästa praxis. I synnerhet skapar Azure SDK för Java Maven-arketypen ett nytt Maven-projekt med följande funktioner:

Ett beroende av den senaste azure-sdk-bom BOM-versionen, som säkerställer att alla beroenden för Azure SDK för Java är anpassade och ger dig bästa möjliga utvecklarupplevelse.
Inbyggt stöd för GraalVM-intern bildkompilering.
Stöd för att generera ett nytt projekt med en angiven uppsättning Azure SDK för Java-klientbibliotek.
Integrering med Azure SDK för Java-byggverktyg, vilket ger byggtidsanalys av projektet för att säkerställa att många metodtips följs.

Förutsättningar

Java Developer Kit, version 8 eller senare. Vi rekommenderar version 17 för bästa möjliga upplevelse.
Apache Maven

Skapa ett nytt Maven-projekt

Azure SDK för Java Maven-arketypen publiceras till Maven Central. Det innebär att du kan använda arketypen direkt för att starta ett nytt program med följande kommando:

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

När du har angett det här kommandot ber en serie frågor om information om projektet så att arketypen kan generera rätt utdata åt dig. I följande tabell beskrivs de egenskaper som du behöver ange värden för:

Namn	Beskrivning
`groupId`	(Krävs) Maven-`groupId` som ska användas i POM-filen som skapats för det genererade projektet.
`artifactId`	(Krävs) Maven `artifactId` som ska användas i POM-filen för det skapade projektet.
`package`	(Valfritt) Paketnamnet som den genererade koden ska placeras i. Härleds från `groupId` om den inte har angetts.
`azureLibraries`	(Valfritt) En kommaavgränsad lista över Azure SDK för Java-bibliotek med hjälp av deras Maven-artefakt-ID:n. En lista över sådana artefakt-ID:n finns i Azure SDK-versioner.
`enableGraalVM`	(Valfritt) `false` för att indikera att den genererade Maven POM-filen inte bör innehålla stöd för att kompilera ditt program till en intern avbildning med GraalVM; annars `true`. Standardvärdet är `true`.
`javaVersion`	(Valfritt) Den lägsta versionen av JDK som ska användas när det genererade projektet byggs, till exempel `8`, `11`eller `17`. Standardvärdet är den senaste LTS-versionen (för närvarande `17`). Minimivärdet är `8`.
`junitVersion`	(Valfritt) Den version av JUnit som ska inkluderas som ett beroende. Standardvärdet är `5`. Giltiga värden `4` och `5`.

Alternativt kan du ange dessa värden när du anropar arketypkommandot som visades tidigare. Den här metoden är till exempel användbar i automatiseringssyfte. Du kan ange värdena som parametrar med maven-standardsyntaxen för att lägga till -D till parameternamnet, till exempel:

-DjavaVersion=17

Stöd för Java-version

Vi rekommenderar att du använder en Java LTS-version när du distribuerar till produktion. Som standard väljer Azure SDK Maven-arketypen den senaste LTS-versionen, som för närvarande anger en Java 17-baslinje. Du kan dock åsidosätta standardbeteendet genom att ange parametern javaVersion.

Använda Azure SDK för Java-kompileringsverktyget

Azure SDK för Java-projektet levererar ett Maven-byggverktyg som du kan inkludera i dina projekt. Det här verktyget körs lokalt och överför inga data till Microsoft. Du kan konfigurera verktyget för att generera en rapport eller misslyckas med bygget när vissa villkor uppfylls, vilket är användbart för att säkerställa efterlevnad av många metodtips, till exempel följande metoder:

Validering av korrekt användning av azure-sdk-for-java BOM, inklusive användning av den senaste versionen och förlitande på den för att definiera beroendeversioner på Azure SDK för Java-klientbibliotek. Mer information finns i avsnittet Lägg till Azure SDK för Java i ett befintligt projekt.
Validering av att historiska Azure-klientbibliotek inte används när det finns nyare och förbättrade versioner.

Rapporten ger också insikt i användningen av beta-API:er.

Du kan konfigurera byggverktyget i en Maven POM-projektfil enligt följande exempel. Se till att ersätta platshållaren för {latest_version} med den senaste versionen som finns listad online.

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

När du har lagt till byggverktyget i ett Maven-projekt kan du köra verktyget genom att anropa mvn compile azure:run. Beroende på vilken konfiguration som tillhandahålls kan du förvänta dig byggfel eller att rapporteringsfiler genereras, vilka kan informera dig om potentiella problem innan de utvecklas till allvarligare problem. Vi rekommenderar att du kör det här verktyget som en del av din CI/CD-pipeline. När byggverktyget utvecklas publicerar vi nya versioner, och vi rekommenderar att utvecklare ofta söka efter nya versioner och uppdatera efter behov.

Det är möjligt att konfigurera byggverktyget för att aktivera eller inaktivera vissa funktioner. För den här konfigurationen lägger du till ett configuration-segment i den tidigare visade XML. I det avsnittet konfigurerar du inställningarna som visas i följande tabell. Alla konfigurationer som inte uttryckligen nämns tar det standardvärde som anges i tabellen.

Egenskapsnamn	Standardvärde	Beskrivning
`validateAzureSdkBomUsed`	sann	Säkerställer att projektet har azure-sdk-for-java BOM refererat korrekt, så att beroenden för Azure SDK för Java-klientbibliotek kan hämta sina versioner från BOM.
`validateLatestBomVersionUsed`	sann	Säkerställer att beroenden hålls uppdaterade genom att rapportera tillbaka (eller stoppar bygget) om en nyare azure-sdk-for-java BOM finns. Du hittar alltid den senaste versionen online.
`validateBomVersionsAreUsed`	sann	Ser till att, där ett beroende är tillgängligt från azure-sdk-for-java BOM, att versionen inte åsidosätts manuellt.
`validateNoDeprecatedMicrosoftLibraryUsed`	sann	Säkerställer att projektet inte använder tidigare generationens Azure-bibliotek. Att använda de nya biblioteken och föregående generations bibliotek i ett enda projekt kommer sannolikt inte att orsaka något problem, men resulterar i en suboptimal utvecklarupplevelse.
`validateNoBetaLibraryUsed`	falsk	Vissa Azure SDK för Java-klientbibliotek har betaversioner, med versionssträngar i formatet `x.y.z-beta.n`. Om du aktiverar den här funktionen ser du till att inga betabibliotek används.
`validateNoBetaApiUsed`	sann	Azure SDK för Java-klientbibliotek har ibland GA-versioner med metoder som kommenterats med `@Beta`. Den här kontrollen ser ut att se om sådana metoder används.
`sendToMicrosoft`	sann	Anger om byggrapporten ska skickas till Microsoft i telemetrisyfte. Detta hjälper utvecklingsteamet att prioritera dokumentation, exempel och förbättrade API:er för bekvämlighet. Inget användar identifierbart innehåll skickas.
`reportFile`	-	(Valfritt) Anger den plats som byggrapporten ska skrivas ut till i JSON-format. Om den inte anges skrivs ingen rapport, och en sammanfattning av bygget, eller lämpliga byggfel, visas i terminalen.

Lägga till Azure SDK för Java i ett befintligt projekt

För att förenkla hanteringen av beroendeversioner publicerar Azure SDK för Java-teamet Azure SDK för Java klient-BOM varje månad. Den här BOM-filen innehåller alla Allmänt tillgängliga Azure SDK för Java-klientpaket med sin kompatibla beroendeversion.

Om du vill använda beroendeversioner för ett Azure SDK för Java-klientbibliotek som finns i strukturlistan, inkluderar du följande kodfragment i projektet pom.xml fil. Ersätt platshållaren {bom_version_to_target} med den senaste versionen av Azure SDK för Java BOM. Ersätt platshållaren {artifactId} med Azure Service SDK-paketnamnet.

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

Du hittar alla versioner av Azure SDK för Java BOM på azure-sdk-bom. Vi rekommenderar att du använder den senaste versionen för att dra nytta av de senaste funktionerna i Azure SDK för Java-klientbibliotek.

Att använda Maven för att definiera projektberoenden kan göra det enklare att hantera dina projekt. Med Azure SDK BOM och Azure SDK Maven-arketypen kan du påskynda projektet samtidigt som du är mer säker på din beroendeversion på lång sikt. Vi rekommenderar att du använder BOM för att ha beroenden i linje och uppdaterade.

Förutom att lägga till Azure SDK BOM rekommenderar vi även att du inkluderar Azure SDK för Java-byggverktyget. Det här verktyget hjälper till att diagnostisera många problem som ofta uppstår när du skapar program, enligt beskrivningen tidigare i den här artikeln.

Inkludera ett paket som inte finns i strukturlistan

Azure SDK för Java-klientens BOM innehåller endast allmänt tillgängliga bibliotek, vilka är GA. Om du vill vara beroende av ett paket som fortfarande är i betaversion eller på en annan biblioteksversion än den som ingår i strukturlistan kan du ange Maven-beroendeversionen tillsammans med groupId och artifactId i beroendeavsnittet. Du kan välja att ha beroenden som använder BOM-versioner och beroenden med åsidosatta versioner i samma PROJEKT POM-fil, som du ser i följande exempel:

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

Om du använder den här metoden och anger versioner direkt i projektet kan du få konflikter i beroendeversioner. Dessa konflikter uppstår eftersom olika paket kan vara beroende av olika versioner av vanliga beroenden, och dessa versioner kanske inte är kompatibla med varandra. När konflikter uppstår kan du uppleva oönskat beteende vid kompileringstillfälle eller vid körningstid. Vi rekommenderar att du förlitar dig på versioner som finns i Azure SDK BOM om det inte behövs. Mer information om hur du hanterar beroenden när du använder Azure SDK för Java finns i Felsöka beroendeversionskonflikter.

Skapa en inbyggd bild med GraalVM

Du kan använda GraalVM för att skapa en intern avbildning av ett Java-program. GraalVM kompilerar Java-koden i förväg till inbyggd datorkod, vilket kan ge drastiska prestandavinster i vissa situationer. Azure SDK för Java tillhandahåller nödvändiga metadata i vart och ett av sina klientbibliotek för att stödja GraalVM-intern bildkompilering.

För att komma igång måste du installera GraalVM och förbereda utvecklingssystemet för kompilering av native bilder. Installationsprocessen för GraalVM är enkel och GraalVM-dokumentationen innehåller steg-för-steg-instruktioner för installation av GraalVM samt använda GraalVM för att installera native-image. Följ avsnittet förutsättningar noggrant för att installera nödvändiga interna kompilatorer för operativsystemet.

Azure SDK för Java Maven-arketyp kan konfigurera din version för att stödja GraalVM-intern bildkompilering, men du kan också lägga till den i en befintlig Maven-version. Du hittar anvisningar för Maven på GraalVM-webbplatsen.

Nu är du redo att köra en inbyggd avbildningsversion. Du kan använda Maven-standardverktyg för att använda graalVM-inbyggda avbildningar. Använd följande kommando för Maven:

mvn clean package -Pnative

När du har kört det här kommandot matar GraalVM ut en intern körbar fil för den plattform som den körs på. Den körbara filen finns i katalogen Maven /target i ditt projekt. Nu kan du köra ditt program med den här körbara filen och den bör fungera på samma sätt som ett Java-standardprogram.

Nästa steg

Kom igång med Azure-tillägg för IntelliJ och Eclipse

Dela via