Kódtárak telepítése és integrálása az Azure SDK for C++ szolgáltatásból

Ez az útmutató biztosítja a fejlesztőknek a szükséges lépéseket ahhoz, hogy kódtárakat telepítsenek a C++-hoz készült Azure SDK-ból vcpkg használatával, és integrálják őket a projektjeikbe a CMake-vel. Az utasításokat követve beállíthatja a fejlesztési környezetet, és megkezdheti az Azure-szolgáltatások használatát a C++ alkalmazásokban. Akár még csak most ismerkedik az Azure-nal, akár szeretné egyszerűsíteni az integrációs folyamatot, ez a dokumentáció segít a gyors és hatékony kezdésben.

Előfeltételek

• Bármely szövegszerkesztő
• Terminál
• C++ fordító
• Git
• CMake
• Azure-előfizetés
• Azure CLI

A Git és a CMake telepítésének ellenőrzése

A zökkenőmentes integráció érdekében fontos ellenőrizni, hogy a Git és a CMake megfelelően van-e telepítve a rendszeren.

Windows – PowerShell

1. A git megfelelő telepítésének ellenőrzéséhez futtassa a következő parancsot a terminálon:

   git --version
   

2. A git jelenleg telepített verzióját az alábbi módon kell megkapnia:

   git version <version>
   

3. A CMake megfelelő telepítésének ellenőrzéséhez futtassa a következő parancsot a terminálon:

   cmake --version
   

4. A CMake jelenleg telepített verziójának jelölését a következő módon kell megkapnia:

   cmake version <version>
   

MacOS/Linux – Bash

1. A git megfelelő telepítésének ellenőrzéséhez futtassa a következő parancsot a terminálon:

   git --version
   

2. A git jelenleg telepített verzióját az alábbi módon kell megkapnia:

   git version <version>
   

3. A CMake megfelelő telepítésének ellenőrzéséhez futtassa a következő parancsot a terminálon:

   cmake --version
   

4. A CMake jelenleg telepített verziójának jelölését a következő módon kell megkapnia:

   cmake version <version>
   

A vcpkg telepítése

A C++ kódtárakhoz készült Azure SDK kezeléséhez és telepítéséhez használja a vcpkg-t. A vcpkg egy platformfüggetlen csomagkezelő, amely leegyszerűsíti a függőségek kezelését.

Windows – PowerShell

1. A vcpkg telepítéséhez először klónozza a vcpkg-adattárat. Az ajánlott módszer a vcpkg klónozása a fejlesztési környezet központi helyére, nem pedig a C++ projektkönyvtárba. Ebben a példában a vcpkg-t a felhasználói könyvtárba klónozzák.

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

2. A vcpkg-adattár klónozása után az új könyvtárba lépve futtassa a bootstrap-vcpkg.bat szkriptet.

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

3. A vcpkg rendszerindítása után adja hozzá az útvonalhoz, hogy a projektkönyvtárából végrehajthassa a vcpkg-t. Ne felejtse el lecserélni a <path\to\vcpkg> parancspéldában szereplő elemet a korábban klónozott vcpkg könyvtár elérési útjára.

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

4. Ha ellenőrizni szeretné, hogy a vcpkg könyvtár hozzá lett-e adva az elérési úthoz, lépjen vissza a projektkönyvtárba, és futtassa a következő parancsot:

   vcpkg --version
   

5. A következő kimenetet kell kapnia:

   vcpkg package management program version <version>
   

MacOS/Linux – Bash

1. A vcpkg telepítéséhez először klónozza a vcpkg-adattárat. Az ajánlott módszer a vcpkg klónozása a fejlesztési környezet központi helyére, nem pedig a C++ projektkönyvtárba. Ebben a példában a vcpkg-t a felhasználói könyvtárba klónozzák.

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

2. A vcpkg-adattár klónozása után az új könyvtárba lépve futtassa a bootstrap-vcpkg.sh szkriptet.

   cd vcpkg
   ./bootstrap-vcpkg.sh
   

3. A vcpkg rendszerindítása után adja hozzá az útvonalhoz, hogy a projektkönyvtárából végrehajthassa a vcpkg-t. Ne felejtse el lecserélni a <path\to\vcpkg> parancspéldában szereplő elemet a korábban klónozott vcpkg könyvtár elérési útjára.

   export PATH=$PATH:/path/to/vcpkg
   

4. Ha ellenőrizni szeretné, hogy a vcpkg könyvtár hozzá lett-e adva az elérési úthoz, lépjen vissza a projektkönyvtárba, és futtassa a következő parancsot:

   vcpkg --version
   

5. A következő kimenetet kell kapnia:

   vcpkg package management program version <version>
   

A könyvtárak telepítése

Ez a szakasz végigvezeti a szükséges kódtáraknak a C++-hoz készült Azure SDK-ból a vcpkg használatával történő telepítésének folyamatán. Ez a szakasz bemutatja, hogyan használhatja a vcpkg-t jegyzék módban, amely létrehoz egy pár vcpkg-projektfájlt, hogy segítsen a projekt függőségeinek kezelésében, még akkor is, ha más közreműködőkkel megosztják.

Windows – PowerShell

1. A projekt gyökérkönyvtárából futtassa a következő parancsot egy új vcpkg-projekt jegyzék módban való elindításához:

   vcpkg new --application
   

2. Most egy vcpkg.json fájlnak és egy vcpkg-configuration.json fájlnak kell lennie a projektkönyvtárban.

3. Most az alábbi parancs futtatásával hozzáadhatjuk az Azure Key Vault- és identitástárakat az Azure SDK for C++ szolgáltatásból a projekthez:

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

4. A vcpkg.json fájlnak a következő tartalommal kell rendelkeznie:

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

MacOS/Linux – Bash

1. A projekt gyökérkönyvtárából futtassa a következő parancsot egy új vcpkg-projekt jegyzék módban való elindításához:

   vcpkg new --application
   

2. Most egy vcpkg.json fájlnak és egy vcpkg-configuration.json fájlnak kell lennie a projektkönyvtárban.

3. Most az alábbi parancs futtatásával hozzáadhatjuk az Azure Key Vault- és identitástárakat az Azure SDK for C++ szolgáltatásból a projekthez:

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

4. A vcpkg.json fájlnak a következő tartalommal kell rendelkeznie:

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

Azure Key Vault-erőforrás létrehozása

Ez a szakasz azt ismerteti, hogyan hozhat létre Azure Key Vault-erőforrást az Azure CLI használatával. Ez a Key Vault-erőforrás biztonságosan tárolja és kezeli a bizalmas információkat, például titkos kulcsokat és kulcsokat.

Windows – PowerShell

1. Az Azure CLI használatával jelentkezzen be a terminálon a következő paranccsal:

   az login
   

2. Az előugró ablakokkal jelentkezzen be az Azure-ba.

3. Miután az előugró böngészőablakot használta a bejelentkezéshez, válassza ki a terminálon használni kívánt Azure-előfizetést.

4. Ezután a következő paranccsal hozza létre a Key Vault-erőforrást, és ne felejtse el lecserélni a <your-resource-group-name> és <your-key-vault-name> elemeket a saját, egyedi neveire.

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

5. A kimenetben meg kell jelennie egy tulajdonságok listájának, amely tartalmazza a vaultUri tulajdonságot. Állítsa be ezt egy környezeti változóra, amelyet a program a következő paranccsal használ:

   $env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
   

MacOS/Linux – Bash

1. Az Azure CLI használatával jelentkezzen be a terminálon a következő paranccsal:

   az login
   

2. Az előugró ablakokkal jelentkezzen be az Azure-ba.

3. Miután az előugró böngészőablakot használta a bejelentkezéshez, válassza ki a terminálon használni kívánt Azure-előfizetést.

4. Ezután a következő paranccsal hozza létre a Key Vault-erőforrást, és ne felejtse el lecserélni a <your-resource-group-name> és <your-key-vault-name> elemeket a saját, egyedi neveire.

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

5. A kimenetben meg kell jelennie egy tulajdonságok listájának, amely tartalmazza a vaultUri tulajdonságot. Állítsa be ezt egy környezeti változóra, amelyet a program a következő paranccsal használ:

   export AZURE_KEYVAULT_URL="https://<your-key-vault-name>.vault.azure.net/"
   

1. Végül győződjön meg arról, hogy az Azure-fiókja rendelkezik a Key Vault titkos kulcsaival való munkához szükséges megfelelő engedélyekkel. A megfelelő engedélyeket úgy adhatja meg magának, hogy a Key Vault-erőforrás Hozzáférés-vezérlése (IAM) oldalán az Azure portálon hozzárendeli magát a "Key Vault Titokkezelő tisztviselő" szerepkörhöz. Az IAM az identitás- és hozzáférés-kezelést jelenti.

Állítsa be a projektjét

Ez a szakasz az Azure C++ projekt beállításához szükséges mappák és fájlok létrehozásának folyamatát ismerteti.

1. A projektkönyvtár gyökerében hozzon létre egy CMakeLists.txt fájlt. Ez a fájl a CMake-projekt konfigurálására szolgál. Adja hozzá a következő kódot a CMakeLists.txt fájlhoz:

   # 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. A projektkönyvtár gyökerében hozzon létre egy main.cpp fájlt. Adja hozzá a következő kódot a main.cpp fájlhoz:

   #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. Hozzon létre egy buildkönyvtárat a buildösszetevők számára.

Fordítás és futtatás

Ez a szakasz bemutatja, hogyan konfigurálhatja és hozhatja létre a projektet CMake-parancsokkal, majd futtathatja a programot, hogy minden megfelelően legyen beállítva. Az ebben a szakaszban található parancsokat a projekt gyökeréből kell futtatni, ahol a build könyvtár, CMakeLists.txt, és main.cpp fájlok találhatók.

Windows – PowerShell

1. A CMake konfigurálásához írja be a következő parancsot:

   cmake -B ./build
   

2. A projekt létrehozásához írja be a következő parancsot:

   cmake --build ./build
   

3. A program futtatásához írja be a következő parancsot:

   .\build\Debug\azure_sample.exe
   

4. A programnak a következő kimenettel kell rendelkeznie:

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

MacOS/Linux – Bash

1. A CMake konfigurálásához írja be a következő parancsot:

   cmake -B ./build
   

2. A projekt létrehozásához írja be a következő parancsot:

   cmake --build ./build
   

3. A program futtatásához írja be a következő parancsot:

   ./build/azure_sample
   

4. A programnak a következő kimenettel kell rendelkeznie:

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

Hibaelhárítás

Az erőforráscsoport nem található

Amikor az AzureCLI használatával hoz létre egy Key Vault-példányt, ha a következő hibaüzenet jelenik meg, a Key Vault-példányt hozzáadni kívánt erőforráscsoport nem létezik.

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

Az erőforráscsoport létrehozásához használja a következő parancsot:

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

További információkért tekintse meg az AzureCLI-dokumentációt az Azure-erőforráscsoportok kezeléséről.

A CMake konfigurálása vagy összeállítása nem találja az Azure-csomagokat

A CMake konfigurálási vagy buildelési parancsainak futtatásakor, ha a következő vagy hasonló hibaüzenetet kapja, a CMakeLists.txt fájl nem futtatja a vcpkg.cmake modult a CMake-projekt létrehozása előtt, vagy egyáltalán.

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.

Ellenőrizze a CMakeLists.txt fájlban, hogy a set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") sor a project(azure_sample VERSION 0.1.0 LANGUAGES C CXX) felett van.

Ezután győződjön meg arról is, hogy a /path/to/vcpkg-root/ sorban lévő set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") fájl a vcpkg telepítésének helyére frissült.

Szintaxishiba a cmake-kódban

Amikor a CMake-konfiguráció vagy a buildparancsok futtatása közben a következő hibaüzenet jelenik meg, a CMakeLists.txt fájl olyan elérési utakat tartalmazhat, amelyek \-t használnak. Ez a probléma gyakori lehet az ablak elérési útjainak használatakor.

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

Annak ellenére, hogy a Windows a fájlelérési utakban \-t használ, a CMake csak /-t használ fájlelérési utakban. A probléma úgy oldható meg, hogy minden \-t /-re lecserélünk azCMakeLists.txtfájlban használt elérési utakon.

Ha a hiba a módosítás után is fennáll, tekintse meg a módosítás után is fennálló CMake-hibákat , és ismerje meg, hogyan háríthatja el őket.

A CMake-hibák a módosítás után is megmaradnak

A CMake-konfigurálási parancs futtatásakor, ha a javítás módosítása után is ugyanazt a hibaüzenetet kapja, próbálja meg törölni a CMake-gyorsítótárat. A CMake-cache a build könyvtár tartalmának törlésével, majd a CMake konfigurálási parancs újrafuttatásával törölhető.

CMake 3.30 vagy újabb szükséges

A CMake configure parancs futtatásakor, ha az alábbihoz hasonló hibaüzenet jelenik meg, előfordulhat, hogy frissítenie kell a CMake verzióját.

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

A hiba megoldásához frissítse a CMake telepítését a hibaüzenetben megadott verzióra.

A hívó nem jogosult műveletet végrehajtani az erőforráson

A C++ mintaprogram futtatásakor, ha az alábbihoz hasonló hibaüzenet jelenik meg, nem rendelkezik a megfelelő engedélyekkel a titkos kulcsok használatához a megadott Key Vault-erőforráson.

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>

A megfelelő engedélyeket az Azure Portal vagy az Azure CLI használatával adhatja meg a fiókjának.

Az engedélyek Azure Portalon való frissítéséhez lépjen a Key Vault-erőforrás hozzáférés-vezérlési (IAM) oldalára. Válassza a Hozzáadás legördülő menüt, és válassza a Szerepkör-hozzárendelés hozzáadása lehetőséget. A Szerepkör lapon válassza ki a Key Vault titkos kulcsfelügyelői szerepkörét, majd kattintson a Lap alján található Tovább gombra. A Tagok lapon hagyja a hozzáférés hozzárendelése lehetőséget a Felhasználó, csoport vagy szolgáltatási objektum beállításon, és kattintson a Tagok kiválasztása hivatkozásra. A jobb oldali előugró ablakban keresse meg és válassza ki az azonosítóját, majd válassza a Kiválasztás lehetőséget az előugró ablak alján. A kijelölt azonosítónak most meg kell jelennie a Tagok szakasz táblájában. Kattintson az alul található Véleményezés + hozzárendelés gombra. Ezután kattintson ismét a Véleményezés + hozzárendelés gombra.

Ha az Azure CLI használatával szeretné frissíteni az engedélyeket, írja be a következő parancsot, lecserélve <upn> a felhasználónevet, <subscription-id> az előfizetés azonosítóját, <resource-group-name> az erőforráscsoport nevét és <your-unique-keyvault-name> a Key Vault-példány nevét:

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

A VS Code hibákat tartalmaz

Ha a VS Code használatakor hibasorok jelennek meg a belefoglalási utasítások alatt (az alábbi képen látható), a szerkesztő nem tudja, hol található a belefoglalási könyvtár.

A vcpkg a include fejléceket a build/vcpkg_installed/<vcpkg-platform-triplet>/include könyvtárba helyezi, amikor jegyzék módban van. Cserélje le <vcpkg-platform-triplet> a platformhoz tartozó vcpkg tripletre.

Ha hozzá szeretné adni a befoglalási könyvtárat a VS Code beállításaihoz, vigye az egérmutatót a hibavonallal ellátott include utasítás fölé. Ezután válassza a Gyorsjavítás... hivatkozást az előugró ablak alján. A Gyorsjavítás beállításai között válassza a Hozzáadás a beállításhoz "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include lehetőséget. A C/C++ Bővítménykonfiguráció lapnak meg kell nyílnia, és a "Tartalmazási útvonal" szakaszban látnia kell a tartalmazási könyvtár útvonalát.

A Linux bootstrap-vcpkg nem talált függőségeket

Ha Linuxon futtatja a bootstrap-vcpkg.sh szkriptet, az alábbihoz hasonló hibaüzenet jelenik meg, nincs telepítve a szkript futtatásához szükséges eszközök.

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)

Az eszközök telepítéséhez használja a linuxos disztribúcióhoz tartozó hibaüzenetben megadott parancsot. Az Ubuntu esetében például a következő parancs lenne:

sudo apt-get install curl zip unzip tar

Ezután futtassa újra a bootstrap-vcpkg.sh szkriptet.

A Linux nem találja az eszközláncfájlt

A CMake configure parancs futtatásakor, ha az alábbihoz hasonló hibaüzenet jelenik meg, a vcpkg.cmake modulok elérési útja nem lett megfelelően beállítva.

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)

A CMakeLists.txt fájlban frissítse az set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") utasítást a vcpkg telepítési helyének megfelelő elérési útvonalával.

A Linux vcpkg telepítése sikertelen

A CMake configure parancs futtatásakor, ha a következőhöz hasonló hibaüzenet jelenik meg, telepíteni kell a csomagok rendszerfüggőségeit.

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

A szükséges rendszercsomagok megkereséséhez keresse meg a CMake konfigurációs parancsok kimenetében azokat a sorokat, amelyek `Could not find <system-package>`-vel kezdődnek, és cserélje ki `<system-package>`-et a hiányzó rendszercsomaggal. A sor alatt egy parancsnak kell lennie a hiányzó rendszercsomag telepítéséhez. Futtassa a parancsot. Ezután futtassa újra a CMake konfigurációs parancsot. Előfordulhat, hogy a hiányzó rendszercsomagok számától függően néhányszor meg kell ismételnie ezt a folyamatot.

Következő lépés