Partager via

Installer et intégrer des bibliothèques à partir du Kit de développement logiciel (SDK) Azure pour C++

Ce guide fournit aux développeurs les étapes nécessaires pour installer des bibliothèques à partir du Kit de développement logiciel (SDK) Azure pour C++ à l’aide de vcpkg et les intégrer à leurs projets avec CMake. En suivant les instructions, vous pouvez configurer votre environnement de développement et commencer à utiliser des services Azure dans vos applications C++. Que vous soyez nouveau dans Azure ou que vous cherchiez à simplifier votre processus d’intégration, cette documentation vous aide à commencer rapidement et efficacement.

Conditions préalables

Vérifier l’installation git et CMake

Pour garantir un processus d’intégration fluide, il est important de vérifier que git et CMake sont correctement installés sur votre système.

  1. Pour vérifier que git est correctement installé, exécutez la commande suivante dans votre terminal :

    git --version

  2. Vous devez obtenir une sortie indiquant la version actuellement installée pour Git, comme suit :

    git version <version>

  3. Pour vérifier que CMake est installé correctement, exécutez la commande suivante dans votre terminal :

    cmake --version

  4. Vous devez obtenir une sortie indiquant la version actuellement installée de CMake, comme suit :

    cmake version <version>

Installer vcpkg

Pour gérer et installer le Kit de développement logiciel (SDK) Azure pour les bibliothèques C++, utilisez vcpkg. vcpkg est un gestionnaire de package multiplateforme qui simplifie le processus de gestion des dépendances.

  1. Pour installer vcpkg, clonez d’abord le référentiel vcpkg. L’approche recommandée consiste à cloner vcpkg à un emplacement central sur votre environnement de développement et non dans votre répertoire de projet C++. Dans cet exemple, vcpkg est cloné dans le dir d’accueil.

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

  2. Une fois le référentiel vcpkg cloné, parcourez le nouveau répertoire et exécutez le bootstrap-vcpkg.bat script.

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

  3. Après avoir démarré vcpkg, ajoutez-le à votre chemin d’accès pour accéder à l’exécutable vcpkg à partir de votre répertoire de projet. N’oubliez pas de remplacer l’exemple <path\to\vcpkg> de commande par le chemin d’accès au répertoire vcpkg que vous avez cloné précédemment.

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

  4. Pour vérifier que le répertoire vcpkg a été ajouté à votre chemin d’accès, revenez au répertoire de votre projet et exécutez la commande suivante :

    vcpkg --version

  5. Vous devez obtenir la sortie suivante :

    vcpkg package management program version <version>

Installer les bibliothèques

Cette section vous guide tout au long du processus d’installation des bibliothèques nécessaires à partir du Kit de développement logiciel (SDK) Azure pour C++ à l’aide de vcpkg. Cette section montre comment utiliser vcpkg en mode manifeste, ce qui crée quelques fichiers projet vcpkg pour aider à gérer les dépendances du projet même lorsqu’il est partagé avec d’autres collaborateurs.

  1. À partir du répertoire racine de votre projet, exécutez la commande suivante pour démarrer un nouveau projet vcpkg en mode manifeste :

    vcpkg new --application

  2. Il doit maintenant y avoir un fichier vcpkg.json et un fichier vcpkg-configuration.json dans le répertoire de votre projet.

  3. Nous pouvons maintenant ajouter les bibliothèques Azure Key Vault et Identity à partir du Kit de développement logiciel (SDK) Azure pour C++ à notre projet en exécutant la commande suivante :

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

  4. Le fichier vcpkg.json doit maintenant avoir le contenu suivant :

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

Créer une ressource Azure Key Vault

Cette section explique comment utiliser Azure CLI pour créer une ressource Azure Key Vault. Cette ressource Key Vault stocke et gère en toute sécurité les informations sensibles, telles que les secrets et les clés.

  1. Utilisez Azure CLI pour vous connecter en entrant la commande suivante dans votre terminal :

    az login

  2. Utilisez les fenêtres contextuelles pour vous connecter à Azure.

  3. Après avoir utilisé la fenêtre contextuelle du navigateur pour vous connecter, sélectionnez l’abonnement Azure que vous souhaitez utiliser dans le terminal.

  4. Utilisez ensuite la commande suivante pour créer votre ressource Key Vault et n’oubliez pas de remplacer <your-resource-group-name> et <your-key-vault-name> par vos noms uniques propres.

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

  5. Dans la sortie, vous devez voir une liste de propriétés avec une vaultUri propriété. Définissez cette valeur sur une variable d’environnement à utiliser dans notre programme avec la commande suivante :

    $env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
  1. Enfin, vérifiez que votre compte Azure dispose des autorisations appropriées pour utiliser les secrets Key Vault. Vous pouvez vous accorder les autorisations appropriées en vous affectant le rôle « Agent des secrets Key Vault » sur la page Contrôle d’accès (IAM) de votre ressource Key Vault dans le portail Azure. IAM correspond à la gestion des identités et des accès.

Configuration de votre projet

Cette section décrit le processus de création des dossiers et fichiers nécessaires pour configurer votre projet Azure C++.

  1. À la racine de votre répertoire de projet, créez un fichier CMakeLists.txt . Ce fichier est utilisé pour configurer notre projet CMake. Ajoutez le code suivant au fichier 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. À la racine de votre répertoire de projet, créez un fichier main.cpp . Ajoutez le code suivant au fichier 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. Créez un répertoire build pour les artéfacts de build.

Compiler et exécuter

Cette section explique comment configurer et générer votre projet à l’aide de commandes CMake, puis exécuter le programme pour vous assurer que tout est configuré correctement. Les commandes de cette section doivent être exécutées à partir de la racine de votre projet où se trouvent le build répertoire, CMakeLists.txtet main.cpp les fichiers.

  1. Pour configurer CMake, entrez la commande suivante :

    cmake -B ./build

  2. Pour générer le projet, entrez la commande suivante :

    cmake --build ./build

  3. Pour exécuter le programme, entrez la commande suivante :

    .\build\Debug\azure_sample.exe

  4. Le programme doit avoir la sortie suivante :

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

Résolution des problèmes

Groupe de ressources introuvable

Lorsque vous utilisez AzureCLI pour créer une instance Key Vault, si vous recevez l’erreur suivante, le groupe de ressources auquel vous essayez d’ajouter l’instance Key Vault n’existe pas.

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

Pour créer le groupe de ressources, vous pouvez utiliser la commande suivante :

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

Pour plus d’informations, consultez la documentation AzureCLI sur la gestion des groupes de ressources Azure.

CMake configure ou build ne peut pas trouver de packages Azure

Lorsque vous exécutez les commandes de configuration ou de build CMake, si vous recevez l’erreur suivante ou quelque chose de similaire, le CMakeLists.txt fichier n’exécute pas le vcpkg.cmake module avant que le projet CMake soit établi ou du tout.

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.

Vérifiez dans le fichier CMakeLists.txt que la ligne set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") est au-dessus de la project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

Ensuite, vérifiez que la ligne /path/to/vcpkg-root/ dans set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") est mise à jour à l’emplacement où vcpkg a été installé.

Erreur de syntaxe dans le code cmake

Lors de l’exécution des commandes de configuration ou de build CMake, si vous recevez l’erreur suivante, le fichier CMakeLists.txt peut contenir des chemins d’accès utilisant \. Ce problème peut être courant lors de l’utilisation des chemins d’accès de 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'.

Même si Windows utilise \ dans les chemins d’accès aux fichiers, CMake utilise / uniquement dans les chemins d’accès aux fichiers. Le problème peut être résolu en remplaçant tous les \ par / dans les chemins d’accès utilisés dans le fichier CMakeLists.txt.

Si votre erreur persiste après avoir apporté la modification, reportez-vous à la section Erreurs CMake persistent après avoir effectué des modifications pour apprendre à les résoudre.

Les erreurs CMake persistent après avoir apporté une modification

Lorsque vous exécutez la commande de configuration CMake, si vous continuez à recevoir la même erreur après avoir apporté des modifications, essayez d’effacer le cache CMake. Le cache CMake peut être effacé en supprimant le contenu du répertoire de build , puis réexécutez la commande de configuration CMake.

CMake 3.30 ou version ultérieure requise

Lorsque vous exécutez la commande de configuration CMake, si vous recevez une erreur comme celle-ci, vous devrez peut-être mettre à jour votre version de 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

Pour résoudre cette erreur, mettez à jour votre installation de CMake vers la version indiquée dans le message d’erreur.

L’appelant n’est pas autorisé à effectuer une action sur la ressource

Lorsque vous exécutez l’exemple de programme C++, si vous recevez une erreur semblable à ce qui suit, vous n’avez pas les autorisations appropriées pour travailler avec des secrets sur la ressource Key Vault spécifiée.

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>

Les autorisations appropriées peuvent être accordées à votre compte à l’aide du portail Azure ou d’Azure CLI.

Pour mettre à jour vos autorisations à l’aide du portail Azure, accédez à la page Contrôle d’accès (IAM) de votre ressource Key Vault. Sélectionnez la liste déroulante Ajouter , puis sélectionnez Ajouter une attribution de rôle. Dans la page Rôle , sélectionnez le rôle Agent de secrets Key Vault , puis sélectionnez Suivant en bas de la page. Dans la page Membres, laissez l’option Affecter l’accès à sur Utilisateur, groupe ou principal du service et sélectionnez le lien Sélectionner des membres. Dans la fenêtre contextuelle à droite, recherchez et sélectionnez votre ID, puis sélectionnez Sélectionner en bas de la fenêtre contextuelle. L’ID que vous avez sélectionné doit maintenant s’afficher dans la table de la section Membres . Sélectionnez le bouton Vérifier + affecter en bas. Sélectionnez ensuite à nouveau le bouton Vérifier + affecter .

Pour mettre à jour vos autorisations à l’aide d’Azure CLI, entrez la commande suivante, en remplaçant <upn> par votre nom d’utilisateur principal, <subscription-id> par votre ID d’abonnement, <resource-group-name> par le nom de votre groupe de ressources et <your-unique-keyvault-name> par le nom de votre instance 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 inclut des erreurs

Si vous voyez des lignes d’erreur sous vos instructions Include lors de l’utilisation de VS Code (illustré dans l’image suivante), l’éditeur ne sait pas où trouver le répertoire include.

{Capture d’écran de C++ inclure des instructions de VS Code qui ont des lignes d’erreur rouge en dessous.}

vcpkg place les en-têtes include dans le build/vcpkg_installed/<vcpkg-platform-triplet>/include mode manifeste. Remplacez <vcpkg-platform-triplet> par le triplet vcpkg pour votre plateforme.

Pour ajouter le répertoire include à vos paramètres VS Code, pointez sur l’instruction Include avec la ligne d’erreur. Sélectionnez ensuite le lien Correctif rapide... en bas de la fenêtre contextuelle. Dans les options Correctif rapide, sélectionnez l’option Ajouter à "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . L’onglet Configuration de l’extension C/C++ doit s’ouvrir et, sous la section « Inclure le chemin d’accès », vous devez voir le chemin d’accès au répertoire include répertorié.

Linux bootstrap-vcpkg n’a pas pu trouver de dépendances

Lorsque vous exécutez le script bootstrap-vcpkg.sh sur Linux, si vous recevez une erreur comme celle-ci, vous n’avez pas les outils nécessaires pour exécuter le 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)

Pour installer les outils, utilisez la commande fournie dans le message d’erreur de votre distribution Linux. Par exemple, sur Ubuntu, il s’agit de la commande suivante :

sudo apt-get install curl zip unzip tar

Réexécutez ensuite le bootstrap-vcpkg.sh script.

Linux n’a pas pu trouver le fichier de chaîne d’outils

Lors de l’exécution de la commande de configuration CMake, si vous recevez une erreur comme celle-ci, le chemin d’accès aux modules vcpkg.cmake n’a pas été correctement défini.

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)

Dans le fichier CMakeLists.txt mettez à jour l’instruction set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") avec le chemin d’accès approprié à l’emplacement où vcpkg a été installé.

Échec de l’installation de vcpkg Linux

Lorsque vous exécutez la commande de configuration CMake, si vous recevez une erreur comme celle-ci, les dépendances système pour les packages doivent être installées.

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

Pour trouver les packages système nécessaires, analysez la sortie des commandes de configuration CMake à la recherche de lignes commençant par Could not find <system-package>, et remplacez <system-package> par le package système manquant. Sous cette ligne, il doit s’agir d’une commande pour installer ce package système manquant. Exécutez cette commande. Réexécutez ensuite la commande de configuration CMake. Vous devrez peut-être répéter ce processus plusieurs fois en fonction du nombre de packages système manquants.

Étape suivante