Introduzione ad Azure SDK e Apache Maven

  • Articolo

Questo articolo illustra come usare Apache Maven per creare applicazioni con Azure SDK per Java. In questo articolo si configura un nuovo progetto con Maven, si compilano progetti con Maven e si usano gli strumenti di immagine nativa graalVM per creare file binari nativi specifici della piattaforma.

Il progetto Azure SDK per Java include un archetipo Maven che può accelerare il bootstrap di un nuovo progetto. Azure SDK per Java Maven archetipo crea una nuova applicazione, con file e una struttura di directory che segue le procedure consigliate. In particolare, Azure SDK per Java Maven archetipo crea un nuovo progetto Maven con le funzionalità seguenti:

  • Una dipendenza dalla versione bom più recente azure-sdk-bom , che garantisce che tutte le dipendenze per Azure SDK per Java siano allineate e offre la migliore esperienza di sviluppo possibile.
  • Supporto predefinito per la compilazione di immagini native graalVM.
  • Supporto per la generazione di un nuovo progetto con un set specificato di librerie client di Azure SDK per Java.
  • Integrazione con gli strumenti di compilazione di Azure SDK per Java, che fornisce l'analisi in fase di compilazione del progetto per garantire che vengano seguite molte procedure consigliate.

Prerequisiti

Creare un nuovo progetto Maven

L'archetipo Azure SDK per Java Maven viene pubblicato in Maven Central. Ciò significa che è possibile usare direttamente l'archetipo per eseguire il bootstrap di una nuova applicazione con il comando seguente:

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

Dopo aver immesso questo comando, una serie di prompt richiede dettagli sul progetto in modo che l'archetipo possa generare automaticamente l'output corretto. Nella tabella seguente vengono descritte le proprietà per cui è necessario specificare i valori:

Nome Descrizione
groupId (Obbligatorio) Maven groupId da usare nel file POM creato per il progetto generato.
artifactId (Obbligatorio) Maven artifactId da usare nel file POM creato per il progetto generato.
package (Facoltativo) Nome del pacchetto in cui inserire il codice generato. Dedotto da groupId se non è specificato.
azureLibraries (Facoltativo) Elenco delimitato da virgole delle librerie di Azure SDK per Java, usando gli ID artefatto Maven. Per un elenco di tali ID artefatti, vedere Versioni di Azure SDK.
enableGraalVM (Facoltativo) false per indicare che il file POM maven generato non deve includere il supporto per la compilazione dell'applicazione in un'immagine nativa usando GraalVM; in caso contrario, true. Il valore predefinito è true.
javaVersion (Facoltativo) Versione minima di JDK di destinazione durante la compilazione del progetto generato, ad esempio 8, 11 o 17. Il valore predefinito è la versione LTS più recente (attualmente 17). Il valore minimo è 8.
junitVersion (Facoltativo) Versione di JUnit da includere come dipendenza. Il valore predefinito è 5. Valori validi 4 e 5.

In alternativa, è possibile specificare questi valori quando si chiama il comando archetipo illustrato in precedenza. Questo approccio è utile, ad esempio, a scopo di automazione. È possibile specificare i valori come parametri usando la sintassi Maven standard di aggiunta -D al nome del parametro, ad esempio:

-DjavaVersion=17

Supporto della versione Java

Come procedura consigliata, è consigliabile usare una versione Java LTS durante la distribuzione nell'ambiente di produzione. Per impostazione predefinita, l'archetipo Maven di Azure SDK seleziona la versione LTS più recente, che attualmente imposta una baseline Java 17. Tuttavia, è possibile eseguire l'override del comportamento predefinito impostando il javaVersion parametro .

Usare lo strumento di compilazione azure SDK per Java

Il progetto Azure SDK per Java include uno strumento di compilazione Maven che è possibile includere nei progetti. Questo strumento viene eseguito localmente e non trasmette dati a Microsoft. È possibile configurare lo strumento per generare un report o interrompere la compilazione quando vengono soddisfatte determinate condizioni, utile per garantire la conformità a numerose procedure consigliate, ad esempio le procedure seguenti:

  • Convalida dell'uso corretto della azure-sdk-for-java distinta base, incluso l'uso della versione più recente e affidamento su di esso per definire le versioni delle dipendenze nelle librerie client di Azure SDK per Java. Per altre informazioni, vedere la sezione Aggiungere Azure SDK per Java a un progetto esistente.
  • Convalida che le librerie client di Azure cronologiche non vengono usate quando esistono versioni più recenti e migliorate.

Il report fornisce anche informazioni dettagliate sull'uso delle API beta.

È possibile configurare lo strumento di compilazione in un file POM del progetto Maven, come illustrato nell'esempio seguente. Assicurarsi di sostituire il {latest_version} segnaposto con la versione più recente elencata online.

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

Dopo aver aggiunto lo strumento di compilazione in un progetto Maven, è possibile eseguire lo strumento chiamando mvn compile azure:run. A seconda della configurazione fornita, è possibile prevedere che vengano visualizzati errori di compilazione o file di report generati che possono informare l'utente sui potenziali problemi prima che diventino più gravi. È consigliabile eseguire questo strumento come parte della pipeline CI/CD. Man mano che lo strumento di compilazione si evolve, verranno pubblicate nuove versioni ed è consigliabile che gli sviluppatori controllino frequentemente le nuove versioni e aggiornino in base alle esigenze.

È possibile configurare lo strumento di compilazione per abilitare o disabilitare funzionalità specifiche. Per questa configurazione, aggiungere una configuration sezione nel codice XML illustrato in precedenza. In questa sezione configurare le impostazioni illustrate nella tabella seguente. Qualsiasi configurazione non indicata in modo esplicito accetta il valore predefinito specificato nella tabella.

Nome della proprietà Valore predefinito Descrizione
validateAzureSdkBomUsed vero Assicura che il progetto disponga di azure-sdk-for-java bom a cui si fa riferimento in modo appropriato, in modo che le dipendenze della libreria client di Azure SDK per Java possano accettare le relative versioni dalla distinta base.
validateLatestBomVersionUsed vero Garantisce che le dipendenze vengano mantenute aggiornate segnalando (o non superato la compilazione) se esiste un BOM azure-sdk-for-java più recente. È sempre possibile trovare la versione più recente online.
validateBomVersionsAreUsed vero Garantisce che, in cui una dipendenza sia disponibile nella distinta base azure-sdk-for-java, la versione non viene sottoposta a override manuale.
validateNoDeprecatedMicrosoftLibraryUsed vero Garantisce che il progetto non usi le librerie di Azure di generazione precedente. L'uso delle librerie di nuova e precedente generazione in un singolo progetto è improbabile che causi problemi, ma comporta un'esperienza di sviluppo non ottimale.
validateNoBetaLibraryUsed false Alcune librerie client di Azure SDK per Java hanno versioni beta, con stringhe di versione nel formato x.y.z-beta.n. L'abilitazione di questa funzionalità garantisce che non vengano usate librerie beta.
validateNoBetaApiUsed vero Le librerie client di Azure SDK per Java talvolta hanno versioni ga con metodi annotati con @Beta. Questo controllo cerca di verificare se vengono usati metodi di questo tipo.
sendToMicrosoft vero Specifica se inviare il report di compilazione a Microsoft per scopi di telemetria. Ciò consente al team di sviluppo di definire le priorità per la documentazione, gli esempi e le API di praticità migliorate. Non viene inviato alcun contenuto identificabile dall'utente.
reportFile - (Facoltativo) Specifica il percorso in cui scrivere il report di compilazione, in formato JSON. Se non specificato, nel terminale non viene scritto alcun report e viene visualizzato un riepilogo della compilazione o degli errori di compilazione appropriati.

Aggiungere Azure SDK per Java a un progetto esistente

Per semplificare la gestione delle versioni delle dipendenze, il team di Azure SDK per Java pubblica ogni mese il bom del client Azure SDK per Java. Questo file DBA include tutti i pacchetti client azure SDK disponibili a livello generale per Java con la versione compatibile delle dipendenze.

Per usare le versioni delle dipendenze per una libreria client di Azure SDK per Java presente nella distinta base, includere il frammento di codice seguente nel file pom.xml del progetto. Sostituire il {bom_version_to_target} segnaposto con la versione più recente di Azure SDK per Java BOM. Sostituire il {artifactId} segnaposto con il nome del pacchetto di Azure Service SDK.

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

È possibile trovare tutte le versioni della distinta base del client Azure SDK per Java in azure-sdk-bom. È consigliabile usare la versione più recente per sfruttare le funzionalità più recenti delle librerie client di Azure SDK per Java.

L'uso di Maven per definire le dipendenze del progetto può semplificare la gestione dei progetti. Con l'archetipo bom di Azure SDK e Maven di Azure SDK, è possibile accelerare il progetto, garantendo al tempo stesso maggiore sicurezza sul controllo delle versioni delle dipendenze a lungo termine. È consigliabile usare la distinta base per mantenere le dipendenze allineate e aggiornate.

Oltre ad aggiungere la distinta base di Azure SDK, è consigliabile includere anche lo strumento di compilazione Azure SDK per Java. Questo strumento consente di diagnosticare molti problemi comunemente riscontrati durante la compilazione di applicazioni, come descritto in precedenza in questo articolo.

Includere un pacchetto non nella distinta base

La distinta base del client Azure SDK per Java include solo librerie disponibili a livello generale. Se si vuole dipendere da un pacchetto ancora in versione beta o da una versione di libreria diversa da quella inclusa nella distinta base, è possibile specificare la versione delle dipendenze Maven insieme groupId a e artifactId nella sezione delle dipendenze. È possibile scegliere di avere dipendenze che usano le versioni bom e le dipendenze con versioni sottoposte a override nello stesso file POM del progetto, come illustrato nell'esempio seguente:

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

Se si usa questo approccio e si specificano le versioni direttamente nel progetto, è possibile che si verifichino conflitti di versione delle dipendenze. Questi conflitti si verificano perché pacchetti diversi possono dipendere da versioni diverse delle dipendenze comuni e queste versioni potrebbero non essere compatibili tra loro. Quando si verificano conflitti, è possibile riscontrare un comportamento indesiderato in fase di compilazione o runtime. È consigliabile basarsi sulle versioni presenti nella distinta base di Azure SDK, a meno che non sia necessario. Per altre informazioni sulla gestione delle dipendenze quando si usa Azure SDK per Java, vedere Risolvere i conflitti di versione delle dipendenze.

Creare un'immagine nativa con GraalVM

È possibile usare GraalVM per creare un'immagine nativa di un'applicazione Java. GraalVM compila il codice Java in anticipo nel codice del computer nativo, che può produrre miglioramenti significativi delle prestazioni in determinate situazioni. Azure SDK per Java fornisce i metadati necessari in ognuna delle librerie client per supportare la compilazione di immagini native graalVM.

Per iniziare, è necessario installare GraalVM e preparare il sistema di sviluppo per la compilazione di immagini native. Il processo di installazione di GraalVM è semplice e la documentazione di GraalVM fornisce istruzioni dettagliate per l'installazione di GraalVM e l'uso di GraalVM per installare l'immagine nativa. Seguire attentamente la sezione prerequisiti per installare i compilatori nativi necessari per il sistema operativo.

L'archetipo Maven di Azure SDK per Java può configurare la compilazione per supportare la compilazione di immagini native graalVM, ma è anche possibile aggiungerla a una build Maven esistente. È possibile trovare le istruzioni per Maven nel sito Web graalVM.

A questo punto, si è pronti per eseguire una compilazione di immagini native. È possibile usare gli strumenti Maven standard per usare l'immagine nativa GraalVM. Per Maven, usare il comando seguente:

mvn clean package -Pnative

Dopo aver eseguito questo comando, GraalVM restituisce un eseguibile nativo per la piattaforma in cui è in esecuzione. L'eseguibile viene visualizzato nella directory Maven /target del progetto. È ora possibile eseguire l'applicazione con questo file eseguibile e dovrebbe essere eseguita in modo analogo a un'applicazione Java standard.

Passaggi successivi

Introduzione alle estensioni di Azure per IntelliJ ed Eclipse