Bibliotheken installeren en integreren vanuit de Azure SDK voor C++

Deze handleiding biedt ontwikkelaars de benodigde stappen om bibliotheken te installeren vanuit de Azure SDK voor C++ met behulp van vcpkg en deze te integreren in hun projecten met CMake. Door de instructies te volgen, kunt u uw ontwikkelomgeving instellen en Beginnen met het gebruik van Azure-services in uw C++-toepassingen. Of u nu nieuw bent in Azure of uw integratieproces wilt stroomlijnen, deze documentatie helpt u snel en efficiënt aan de slag te gaan.

Vereiste voorwaarden

• Elke teksteditor
• Een terminal
• Een C++-compiler
• Git
• CMake
• Een Azure-abonnement
• Azure-CLI

Git- en CMake-installatie verifiëren

Om een soepel integratieproces te garanderen, is het belangrijk om te controleren of Git en CMake correct op uw systeem zijn geïnstalleerd.

vcpkg installeren

Als u de Azure SDK voor C++-bibliotheken wilt beheren en installeren, gebruikt u vcpkg. vcpkg is een platformoverschrijdende pakketbeheerder die het verwerken van afhankelijkheden vereenvoudigt.

De bibliotheken installeren

In deze sectie wordt u begeleid bij het installeren van de benodigde bibliotheken vanuit de Azure SDK voor C++ met behulp van vcpkg. In deze sectie wordt beschreven hoe u vcpkg gebruikt in de manifestmodus waarmee een aantal vcpkg-projectbestanden worden gemaakt om de afhankelijkheden van het project te beheren, zelfs wanneer ze worden gedeeld met andere medewerkers.

Een Azure Key Vault-resource maken

In deze sectie wordt beschreven hoe u de Azure CLI gebruikt om een Azure Key Vault-resource te maken. Deze Key Vault-resource slaat gevoelige informatie, zoals geheimen en sleutels, veilig op en beheert deze.

1. Controleer ten slotte of uw Azure-account over de juiste machtigingen beschikt om te werken met Key Vault-geheimen. U kunt uzelf de juiste machtigingen geven door uzelf de rol Key Vault Secrets Officer toe te wijzen op de pagina Toegangsbeheer (IAM) van uw Key Vault-resource in Azure Portal. IAM staat voor identiteits- en toegangsbeheer.

Stel uw project in

In deze sectie wordt het proces beschreven voor het maken van de benodigde mappen en bestanden voor het instellen van uw Azure C++-project.

1. Maak in de hoofdmap van je project een CMakeLists.txt-bestand. Dit bestand wordt gebruikt om ons CMake-project te configureren. Voeg de volgende code toe aan het CMakeLists.txt-bestand :

   # 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. Maak in de hoofdmap van de projectmap een main.cpp-bestand . Voeg de volgende code toe aan het bestand 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. Maak een builddirectory voor de artefacten.

Bouwen en uitvoeren

In deze sectie wordt beschreven hoe u uw project configureert en bouwt met behulp van CMake-opdrachten en vervolgens het programma uitvoert om ervoor te zorgen dat alles correct is ingesteld. De opdrachten in deze sectie moeten worden uitgevoerd vanuit de hoofdmap van uw project waar de build map CMakeLists.txten main.cpp bestanden zich bevinden.

Probleemoplossingsproces

Resourcegroep is niet gevonden

Als u AzureCLI gebruikt om een Key Vault-exemplaar te maken en u krijgt de volgende foutmelding, dan bestaat de resourcegroep waar u het Key Vault-exemplaar aan wilt toevoegen niet.

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

Als u de resourcegroep wilt maken, kunt u de volgende opdracht gebruiken:

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

Raadpleeg de AzureCLI-documenten over het beheren van Azure-resourcegroepen voor meer informatie.

Azure-pakketten kunnen niet worden gevonden met CMake configureren of bouwen

Wanneer u de CMake-configuratie- of buildopdrachten uitvoert en u de volgende fout of iets dergelijks ontvangt, wordt de CMakeLists.txtvcpkg.cmake module niet uitgevoerd vóórdat het CMake-project tot stand is gebracht, of geheel niet.

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.

Controleer in het bestandCMakeLists.txt of de set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") regel zich boven de project(azure_sample VERSION 0.1.0 LANGUAGES C CXX)regel bevindt.

Controleer vervolgens ook of de /path/to/vcpkg-root/set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") regel is bijgewerkt naar de locatie waar vcpkg is geïnstalleerd.

Syntaxisfout in cmake-code

Wanneer u de CMake-configuratie- of buildopdrachten uitvoert en u de volgende fout ontvangt, kan het CMakeLists.txt bestand paden bevatten met behulp van \. Dit probleem kan vaak voorkomen bij het gebruik van de paden van Windows.

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

Hoewel Windows \ in bestandspaden gebruikt, gebruikt CMake alleen / in bestandspaden. Het probleem kan worden opgelost door alle \ te vervangen door / in paden die in het CMakeLists.txt-bestand worden gebruikt.

Als uw fout zich blijft voordoen nadat u de wijziging hebt aangebracht, raadpleegt u de CMake-fouten na het aanbrengen van een wijzigingssectie om te leren hoe u deze kunt oplossen.

CMake-fouten blijven behouden na het aanbrengen van wijzigingen

Als u tijdens het uitvoeren van de CMake-configuratieopdracht dezelfde fout blijft tegenkomen nadat u wijzigingen hebt aangebracht om deze op te lossen, probeer dan de CMake-cache te wissen. De CMake-cache kan worden gewist door de inhoud van de buildmap te verwijderen en vervolgens de CMake-configuratieopdracht opnieuw uit te voeren.

CMake 3.30 of hoger vereist

Wanneer u de CMake-opdracht configureert, moet u mogelijk uw versie van CMake bijwerken als u een foutmelding krijgt zoals hieronder.

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

Als u deze fout wilt oplossen, werkt u de installatie van CMake bij naar de versie die in het foutbericht wordt vermeld.

Aanroeper is niet gemachtigd om actie uit te voeren op de resource

Wanneer u het C++-voorbeeldprogramma uitvoert, hebt u niet de juiste machtigingen om te werken met geheimen voor de opgegeven Key Vault-resource als u een foutmelding krijgt zoals hieronder.

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>

De juiste machtigingen kunnen worden verleend aan uw account met behulp van Azure Portal of de Azure CLI.

Als u uw machtigingen wilt bijwerken met behulp van Azure Portal, gaat u naar de pagina Toegangsbeheer (IAM) van uw Key Vault-resource. Selecteer de vervolgkeuzelijst Toevoegen en selecteer Roltoewijzing toevoegen. Selecteer op de pagina Rol de rol Key Vault Secrets Officer en selecteer Volgende onder aan de pagina. Laat op de pagina Leden de optie Toegang toewijzen op gebruiker, groep of service-principal staan en selecteer op de koppeling Leden selecteren . Zoek in het pop-upvenster aan de rechterkant naar uw ID en selecteer Selecteren onder aan het pop-upvenster. De id die u hebt geselecteerd, moet nu worden weergegeven in de tabel van de sectie Leden . Selecteer onderaan de knop Beoordelen en toewijzen . Selecteer vervolgens opnieuw de knop Beoordelen en toewijzen .

Als u uw machtigingen wilt bijwerken met behulp van de Azure CLI, voert u de volgende opdracht in, waarbij u <upn> de principal-naam van de gebruiker vervangt door <subscription-id> uw abonnements-id, <resource-group-name> de naam van uw resourcegroep en <your-unique-keyvault-name> de naam van uw Key Vault-exemplaar:

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

Als u foutmeldingen onder uw inclusieverklaringen ziet wanneer u VS Code gebruikt (weergegeven in de volgende afbeelding), weet de editor niet waar hij de inclusiemap moet vinden.

vcpkg plaatst de inclusiekoppen in de build/vcpkg_installed/<vcpkg-platform-triplet>/include wanneer dit in de manifestmodus is. Vervang <vcpkg-platform-triplet> door de vcpkg triplet voor uw platform.

Als u de inclusiemap wilt toevoegen aan uw VS Code-instellingen, beweegt u de muisaanwijzer over de insluitingsinstructie met de foutmelding. Selecteer vervolgens de koppeling Snelle oplossing... onderaan het pop-upvenster. Selecteer in de opties voor snelle oplossing de optie Toevoegen aan "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . Het tabblad Configuratie van de extensie C/C++ moet worden geopend en onder de sectie Inclusief pad ziet u het pad naar de insluitingsmap vermeld.

Linux bootstrap-vcpkg kan afhankelijkheden niet vinden

Als u bij het uitvoeren van het bootstrap-vcpkg.sh-script op Linux een foutmelding ontvangt zoals de volgende, dan hebt u niet de benodigde hulpprogramma's geïnstalleerd om het script uit te voeren.

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)

Als u de hulpprogramma's wilt installeren, gebruikt u de opgegeven opdracht in het foutbericht voor uw Linux-distributie. Op Ubuntu is dit bijvoorbeeld de volgende opdracht:

sudo apt-get install curl zip unzip tar

Voer het bootstrap-vcpkg.sh script vervolgens opnieuw uit.

Kan het hulpprogrammahangerbestand niet vinden in Linux

Wanneer u de configure-opdracht van CMake uitvoert, en u ontvangt een foutmelding zoals hieronder, is het pad naar de vcpkg.cmake-modules niet juist ingesteld.

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)

Werk in het bestandCMakeLists.txt het set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") statement bij met het juiste pad naar de locatie waar vcpkg is geïnstalleerd.

Installatie van Linux vcpkg is mislukt

Wanneer u de CMake-configuratieopdracht uitvoert, moet u systeemafhankelijkheden voor de pakketten installeren als u een foutmelding krijgt zoals hieronder.

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

Als u de benodigde systeempakketten wilt vinden, zoekt u in de uitvoer van de CMake-configuratieopdrachten naar regels die beginnen met Could not find <system-package>regels, waarbij u het ontbrekende systeempakket vervangt <system-package> . Onder deze regel moet een opdracht zijn om dat ontbrekende systeempakket te installeren. Voer die opdracht uit. Voer vervolgens de CMake-configuratieopdracht opnieuw uit. Mogelijk moet u dit proces een paar keer herhalen, afhankelijk van het aantal ontbrekende systeempakketten.

Volgende stap