Condividi tramite

Installare e integrare librerie da Azure SDK per C++

Questa guida fornisce agli sviluppatori i passaggi necessari per installare le librerie da Azure SDK per C++ usando vcpkg e integrarle nei progetti con CMake. Seguendo le istruzioni, è possibile configurare l'ambiente di sviluppo e iniziare a usare i servizi di Azure nelle applicazioni C++. Se non si ha familiarità con Azure o si vuole semplificare il processo di integrazione, questa documentazione consente di iniziare rapidamente ed in modo efficiente.

Prerequisiti

Verificare l'installazione di Git e CMake

Per garantire un processo di integrazione uniforme, è importante verificare che Git e CMake siano installati correttamente nel sistema.

  1. Per verificare che Git sia installato correttamente, eseguire il comando seguente nel terminale:

    git --version

  2. Dovrebbe essere visualizzato un output che indica la versione attualmente installata per Git, come illustrato di seguito:

    git version <version>

  3. Per verificare che CMake sia installato correttamente, eseguire il comando seguente nel terminale:

    cmake --version

  4. Dovrebbe essere visualizzato un output che indica la versione attualmente installata di CMake, come illustrato di seguito:

    cmake version <version>

Installare vcpkg

Per gestire e installare le librerie di Azure SDK per C++, usare vcpkg. vcpkg è una gestione pacchetti multipiattaforma che semplifica il processo di gestione delle dipendenze.

  1. Per installare vcpkg, clonare prima il repository vcpkg. L'approccio consigliato consiste nel clonare vcpkg in una posizione centrale nell'ambiente di sviluppo e non nella directory del progetto C++. In questo esempio vcpkg viene clonato nel dir home.

    cd ~
git clone https://github.com/microsoft/vcpkg.git

  2. Dopo aver clonato il repository vcpkg, passare alla nuova directory ed eseguire lo bootstrap-vcpkg.bat script.

    cd .\vcpkg\
.\bootstrap-vcpkg.bat

  3. Dopo aver avviato vcpkg, aggiungerlo al percorso in modo da poter accedere al file eseguibile vcpkg dalla directory del progetto. Ricordarsi di sostituire <path\to\vcpkg> nell'esempio di comando con il percorso della directory vcpkg clonata in precedenza.

    $env:Path = "$env:Path;<path\to\vcpkg>"

  4. Per verificare che la directory vcpkg sia stata aggiunta al percorso, tornare alla directory del progetto ed eseguire il comando seguente:

    vcpkg --version

  5. Dovrebbe essere visualizzato l'output seguente:

    vcpkg package management program version <version>

Installare le librerie

Questa sezione illustra il processo di installazione delle librerie necessarie da Azure SDK per C++ usando vcpkg. Questa sezione illustra come usare vcpkg in modalità manifesto che crea un paio di file di progetto vcpkg per gestire le dipendenze del progetto anche se condivise con altri collaboratori.

  1. Dalla directory radice del progetto eseguire il comando seguente per avviare un nuovo progetto vcpkg in modalità manifesto:

    vcpkg new --application

  2. Dovrebbe essere presente un file vcpkg.json e un file vcpkg-configuration.json nella directory del progetto.

  3. È ora possibile aggiungere le librerie di Azure Key Vault e Identity da Azure SDK per C++ al progetto eseguendo il comando seguente:

    vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp

  4. Il filevcpkg.json dovrebbe ora avere il contenuto seguente:

    {
  "dependencies": [
    "azure-identity-cpp",
    "azure-security-keyvault-secrets-cpp"
  ]
}

Creare una risorsa di Azure Key Vault

Questa sezione illustra come usare l'interfaccia della riga di comando di Azure per creare una risorsa di Azure Key Vault. Questa risorsa di Key Vault archivia e gestisce in modo sicuro le informazioni riservate, ad esempio segreti e chiavi.

  1. Usare l'interfaccia della riga di comando di Azure per accedere immettendo il comando seguente nel terminale:

    az login

  2. Usare le finestre popup per accedere ad Azure.

  3. Dopo aver usato la finestra del browser popup per accedere, selezionare la sottoscrizione di Azure che si vuole usare nel terminale.

  4. Usare quindi il comando seguente per creare la risorsa key vault e ricordarsi di sostituire <your-resource-group-name> e <your-key-vault-name> con nomi univoci personalizzati:

    az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

  5. Nell'output dovrebbe essere visualizzato un elenco di proprietà, tra cui una proprietà vaultUri. Impostare tale valore su una variabile di ambiente da usare nel programma con il comando seguente:

    $env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
  1. Assicurarsi infine che l'account Azure disponga delle autorizzazioni appropriate per l'uso con i segreti di Key Vault. È possibile concedere le autorizzazioni appropriate assegnando a se stessi il ruolo "Key Vault Secrets Officer" nella pagina Controllo di accesso (IAM) della risorsa Key Vault nel portale di Azure. IAM è l'acronimo di Identity and Access Management.

Impostare il progetto

Questa sezione descrive il processo di creazione delle cartelle e dei file necessari per configurare il progetto Azure C++.

  1. Nella radice della directory del progetto, crea un fileCMakeLists.txt. Questo file viene usato per configurare il progetto CMake. Aggiungere il codice seguente al file CMakeLists.txt :

    # Specify the minimum version of CMake required to build this project
cmake_minimum_required(VERSION 3.30.0)

# Set the path to the vcpkg toolchain file
# Remember to replace the path below with the path where you cloned vcpkg
set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake")

# Define the project name, version, and the languages used
project(azure_sample VERSION 0.1.0 LANGUAGES C CXX)

# Find and include the azure-identity-cpp package
find_package(azure-identity-cpp CONFIG REQUIRED)

# Find and include the azure-security-keyvault-secrets-cpp package
find_package(azure-security-keyvault-secrets-cpp CONFIG REQUIRED)

# Add an executable target named 'azure_sample' built from the main.cpp source file
add_executable(azure_sample main.cpp)

# Link the azure-identity and azure-security-keyvault-secrets 
# libraries to the azure_sample target
target_link_libraries(azure_sample PRIVATE
    Azure::azure-identity
    Azure::azure-security-keyvault-secrets
)

  2. Nella radice della directory del progetto creare un file main.cpp . Aggiungere il codice seguente al file main.cpp :

    #include <azure/identity.hpp>
#include <azure/keyvault/secrets.hpp>
#include <iostream>

using namespace Azure::Security::KeyVault::Secrets;

int main()
{
    try
    {
        // Set Key Vault URL string
        auto const keyVaultUrl = std::getenv("AZURE_KEYVAULT_URL");

        // Create Default Azure Credential to Authenticate.
        // It will pick up on our AzureCLI login
        auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

        // Create Key Vault Secret Client
        SecretClient secretClient(keyVaultUrl, credential);

        // Create a Secret
        std::string secretName("MySampleSecret");
        std::string secretValue("My super secret value");
        secretClient.SetSecret(secretName, secretValue);

        // Get the Secret
        KeyVaultSecret secret = secretClient.GetSecret(secretName).Value;
        std::string valueString = secret.Value.HasValue()
                                      ? secret.Value.Value()
                                      : "NONE RETURNED";
        std::cout << "Secret is returned with name " << secret.Name
                  << " and value " << valueString << std::endl;
    }
    catch (Azure::Core::Credentials::AuthenticationException const &e)
    {
        std::cout << "Authentication Exception happened:" << std::endl
                  << e.what() << std::endl;
        return 1;
    }
    catch (Azure::Core::RequestFailedException const &e)
    {
        std::cout << "Key Vault Secret Client Exception happened:" << std::endl
                  << e.Message << std::endl;
        return 1;
    }

    return 0;
}

  3. Creare una directory build per gli artefatti di build.

Compilare ed eseguire

Questa sezione illustra come configurare e compilare il progetto usando i comandi CMake e quindi eseguire il programma per assicurarsi che tutto sia configurato correttamente. I comandi in questa sezione devono essere eseguiti dalla radice del progetto in cui si trovano la build directory, CMakeLists.txte i main.cpp file .

  1. Per configurare CMake, immettere il comando seguente:

    cmake -B ./build

  2. Per compilare il progetto, immettere il comando seguente:

    cmake --build ./build

  3. Per eseguire il programma, immettere il comando seguente:

    .\build\Debug\azure_sample.exe

  4. Il programma deve avere l'output seguente:

    Secret is returned with name MySampleSecret and value My super secret value

Risoluzione dei problemi

Gruppo di risorse non trovato

Quando si usa AzureCLI per creare un'istanza di Key Vault, se viene visualizzato l'errore seguente, il gruppo di risorse a cui si sta tentando di aggiungere l'istanza di Key Vault a non esiste.

(ResourceGroupNotFound) Resource group '<your-resource-group-name>' could not be found.
Code: ResourceGroupNotFound
Message: Resource group '<your-resource-group-name>' could not be found.

Per creare il gruppo di risorse, è possibile usare il comando seguente:

az group create --name <your-resource-group-name> --location <your-resource-group-location>

Per altre informazioni, vedere la documentazione di AzureCLI sulla gestione dei gruppi di risorse di Azure.

La configurazione o la compilazione di CMake non riescono a trovare i pacchetti di Azure

Quando si eseguono i comandi di configurazione o compilazione di CMake, se viene visualizzato l'errore seguente o qualcosa di simile, il CMakeLists.txt file non esegue il vcpkg.cmake modulo prima che il progetto CMake venga stabilito o affatto.

CMake Error at CMakeLists.txt:12 (find_package):
  Could not find a package configuration file provided by
  "azure-identity-cpp" with any of the following names:

    azure-identity-cppConfig.cmake
    azure-identity-cpp-config.cmake

  Add the installation prefix of "azure-identity-cpp" to CMAKE_PREFIX_PATH or
  set "azure-identity-cpp_DIR" to a directory containing one of the above
  files.  If "azure-identity-cpp" provides a separate development package or
  SDK, be sure it has been installed.

Verificare nel file CMakeLists.txt che la set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") riga sia sopra il project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

Verificare quindi anche che /path/to/vcpkg-root/ nella riga set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") sia aggiornato al percorso in cui è stato installato vcpkg.

Errore di sintassi nel codice cmake

Quando si eseguono i comandi di configurazione o compilazione di CMake, se viene visualizzato l'errore seguente, il fileCMakeLists.txt può contenere percorsi usando \. Questo problema può essere comune quando si usano i percorsi di Window.

Syntax error in cmake code at

    C:/Users/username/Desktop/CppProject/CMakeLists.txt:6

  when parsing string

    C:\Users\username\vcpkg\scripts\buildsystems\vcpkg.cmake

  Invalid character escape '\U'.

Anche se Windows usa \ nei percorsi di file, CMake usa / solo nei percorsi di file. Il problema può essere risolto sostituendo tutti i \ con / nei percorsi usati nel file CMakeLists.txt.

Se l'errore persiste dopo aver apportato la modifica, fare riferimento alla sezione Errori CMake persistenti dopo aver apportato modifiche per informazioni su come risolverli.

Gli errori di CMake vengono mantenuti dopo aver apportato modifiche

Quando si esegue il comando di configurazione di CMake, se si continua a ricevere lo stesso errore dopo aver apportato modifiche per correggerlo, provare a cancellare la cache CMake. La cache CMake può essere cancellata eliminando il contenuto della directory di compilazione e quindi eseguendo nuovamente il comando di configurazione di CMake.

È richiesto CMake 3.30 o una versione successiva.

Quando si esegue il comando di configurazione di CMake, se viene visualizzato un errore simile al seguente, potrebbe essere necessario aggiornare la versione di CMake.

CMake Error at CMakeLists.txt:2 (cmake_minimum_required):
  CMake 3.30.0 or higher is required.  You are running version 3.25.0

Per risolvere questo errore, aggiornare l'installazione di CMake alla versione indicata nel messaggio di errore.

Il chiamante non è autorizzato a eseguire un'azione sulla risorsa

Quando si esegue il programma di esempio C++, se viene visualizzato un errore simile al seguente, non si dispone delle autorizzazioni appropriate per lavorare con i segreti nella risorsa dell'insieme di credenziali delle chiavi specificata.

Key Vault Secret Client Exception happened:
Caller is not authorized to perform action on resource.
If role assignments, deny assignments or role definitions were changed recently, please observe propagation time.
Caller: <redacted-application-information>
Action: 'Microsoft.KeyVault/vaults/secrets/setSecret/action'
Resource: <redacted-resource-information>
Assignment: (not found)
DenyAssignmentId: null
DecisionReason: null 
Vault: <your-key-vault-name>;location=<your-key-vault-location>

Le autorizzazioni appropriate possono essere concesse all'account usando il portale di Azure o l'interfaccia della riga di comando di Azure.

Per aggiornare le autorizzazioni usando il portale di Azure, passare alla pagina Controllo di accesso (IAM) della risorsa di Key Vault. Selezionare l'elenco a discesa Aggiungi e selezionare Aggiungi assegnazione di ruolo. Nella pagina Ruolo selezionare il ruolo Key Vault Secrets Officer e selezionare Avanti nella parte inferiore della pagina. Nella pagina Membri, mantieni l'opzione Assegna accesso a su Utente, gruppo o entità servizio e clicca sul link Seleziona membri. Nella finestra popup a destra, cerca e seleziona il tuo ID, quindi seleziona Seleziona nella parte inferiore della finestra popup. L'ID selezionato dovrebbe ora essere visualizzato nella tabella della sezione Membri . Selezionare il pulsante Rivedi e assegna nella parte inferiore. Selezionare quindi di nuovo il pulsante Rivedi e assegna .

Per aggiornare le autorizzazioni usando l'interfaccia della riga di comando di Azure, immettere il comando seguente, sostituendo <upn> con il nome dell'entità utente, <subscription-id> con l'ID sottoscrizione, <resource-group-name> con il nome del gruppo di risorse e <your-unique-keyvault-name> con il nome dell'istanza di Key Vault:

az role assignment create --role "Key Vault Secrets Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

VS Code include degli errori

Se vengono visualizzate righe di errore nelle istruzioni di inclusione quando si usa VS Code (illustrato nell'immagine seguente), l'editor non sa dove trovare la directory di inclusione.

{Screenshot di C++ include istruzioni di VS Code con righe ondulate di errore rosso sotto.}

vcpkg inserisce i file di intestazione in build/vcpkg_installed/<vcpkg-platform-triplet>/include in modalità manifesto. Sostituire <vcpkg-platform-triplet> con il vcpkg triplet per la tua piattaforma.

Per aggiungere la directory di inclusione alle impostazioni di VS Code, passare il puntatore del mouse sull'istruzione include con la riga di errore. Selezionare quindi il collegamento Correzione rapida nella parte inferiore del popup. Nelle opzioni Correzione rapida selezionare l'opzione Aggiungi a "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . La scheda Configurazione estensione C/C++ dovrebbe essere aperta e nella sezione "Includi percorso" dovrebbe essere visualizzato il percorso della directory di inclusione elencata.

Bootstrap-vcpkg linux non è riuscito a trovare le dipendenze

Quando si esegue lo script bootstrap-vcpkg.sh in Linux, se viene visualizzato un errore simile al seguente, non sono installati gli strumenti necessari per eseguire lo script.

Could not find zip. Please install it (and other dependencies) with:
On Debian and Ubuntu derivatives:
  sudo apt-get install curl zip unzip tar
On recent Red Hat and Fedora derivatives:
  sudo dnf install curl zip unzip tar
On older Red Hat and Fedora derivatives:
  sudo yum install curl zip unzip tar
On SUSE Linux and derivatives:
  sudo zypper install curl zip unzip tar
On Arch Linux and derivatives:
  sudo pacman -Syu base-devel git curl zip unzip tar cmake ninja
On Alpine:
  apk add build-base cmake ninja zip unzip curl git
  (and export VCPKG_FORCE_SYSTEM_BINARIES=1)

Per installare gli strumenti, usare il comando fornito nel messaggio di errore per la distribuzione linux. Ad esempio, in Ubuntu sarebbe il comando seguente:

sudo apt-get install curl zip unzip tar

Quindi eseguire di nuovo lo bootstrap-vcpkg.sh script.

Linux non è riuscito a trovare il file toolchain

Quando si esegue il comando di configurazione di CMake, se viene visualizzato un errore simile al seguente, il percorso dei moduli vcpkg.cmake non è stato impostato correttamente.

CMake Error at /usr/share/cmake-3.28/Modules/CMakeDetermineSystem.cmake:176 (message):
  Could not find toolchain file:
  /path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake
Call Stack (most recent call first):
  CMakeLists.txt:9 (project)

Nel fileCMakeLists.txt aggiornare l'istruzione set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") con il percorso corretto in cui è stato installato vcpkg.

Installazione di Linux vcpkg non riuscita

Quando si esegue il comando di configurazione di CMake, se viene visualizzato un errore simile al seguente, è necessario installare le dipendenze di sistema per i pacchetti.

CMake Error at /path/to/vcpkg/scripts/buildsystems/vcpkg.cmake:904 (message):
  vcpkg install failed.  See logs for more information:

Per trovare i pacchetti di sistema necessari, cercare nell'output dei comandi di configurazione di CMake le righe che iniziano con Could not find <system-package>, sostituendo <system-package> con il pacchetto di sistema mancante. Sotto questa riga deve essere presente un comando per installare il pacchetto di sistema mancante. Eseguire il comando. Eseguire quindi di nuovo il comando di configurazione di CMake. Potrebbe essere necessario ripetere questo processo alcune volte a seconda del numero di pacchetti di sistema mancanti.

Passo successivo

  • Last updated on