Installera och integrera bibliotek från Azure SDK för C++

2025-05-08

Den här guiden ger utvecklare de steg som krävs för att installera bibliotek från Azure SDK för C++ med vcpkg och integrera dem i sina projekt med CMake. Genom att följa anvisningarna kan du konfigurera utvecklingsmiljön och börja använda Azure-tjänster i dina C++-program. Oavsett om du är nybörjare på Azure eller vill effektivisera integreringsprocessen hjälper den här dokumentationen dig att komma igång snabbt och effektivt.

Förutsättningar

Valfri textredigerare
En terminal
En C++-kompilator
Git
CMake
En Azure-prenumeration
Azure CLI

Verifiera git- och CMake-installation

För att säkerställa en smidig integreringsprocess är det viktigt att kontrollera att git och CMake är korrekt installerade i systemet.

Windows – PowerShell
MacOS/Linux – Bash

Kontrollera att git är korrekt installerat genom att köra följande kommando i terminalen:
```
git --version
```
Du bör få utdata som anger den för närvarande installerade versionen för git, så här:
```
git version <version>
```
Kontrollera att CMake är korrekt installerat genom att köra följande kommando i terminalen:
```
cmake --version
```
Du bör få utdata som anger den installerade versionen av CMake, så här:
```
cmake version <version>
```

Kontrollera att git är korrekt installerat genom att köra följande kommando i terminalen:
```
git --version
```
Du bör få utdata som anger den för närvarande installerade versionen för git, så här:
```
git version <version>
```
Kontrollera att CMake är korrekt installerat genom att köra följande kommando i terminalen:
```
cmake --version
```
Du bör få utdata som anger den installerade versionen av CMake, så här:
```
cmake version <version>
```

Installera vcpkg

Om du vill hantera och installera Azure SDK för C++-bibliotek använder du vcpkg. vcpkg är en plattformsoberoende pakethanterare som förenklar hanteringen av beroenden.

Windows – PowerShell
MacOS/Linux – Bash

Om du vill installera vcpkg klonar du först vcpkg-lagringsplatsen. Den rekommenderade metoden är att klona vcpkg till en central plats i utvecklingsmiljön och inte i C++-projektkatalogen. I det här exemplet klonas vcpkg till hemdir.
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
När vcpkg-lagringsplatsen har klonats går du till den nya katalogen och kör skriptet bootstrap-vcpkg.bat .
```
cd .\vcpkg\
.\bootstrap-vcpkg.bat
```
När du har initierat vcpkg lägger du till det i din miljöväg så att du kan komma åt vcpkg-exekverbaren från projektkatalogen. Kom ihåg att ersätta <path\to\vcpkg> i kommandoexemplet med sökvägen till den vcpkg-katalog som du klonade tidigare.
```
$env:Path = "$env:Path;<path\to\vcpkg>"
```
Kontrollera att katalogen vcpkg har lagts till i sökvägen genom att gå tillbaka till projektkatalogen och köra följande kommando:
```
vcpkg --version
```

Du bör få följande utdata:

vcpkg package management program version <version>

Om du vill installera vcpkg klonar du först vcpkg-lagringsplatsen. Den rekommenderade metoden är att klona vcpkg till en central plats i utvecklingsmiljön och inte i C++-projektkatalogen. I det här exemplet klonas vcpkg till hemdir.
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
När vcpkg-lagringsplatsen har klonats går du till den nya katalogen och kör skriptet bootstrap-vcpkg.sh .
```
cd vcpkg
./bootstrap-vcpkg.sh
```
När du har initierat vcpkg lägger du till det i din miljöväg så att du kan komma åt vcpkg-exekverbaren från projektkatalogen. Kom ihåg att ersätta <path\to\vcpkg> i kommandoexemplet med sökvägen till den vcpkg-katalog som du klonade tidigare.
```
export PATH=$PATH:/path/to/vcpkg
```
Kontrollera att katalogen vcpkg har lagts till i sökvägen genom att gå tillbaka till projektkatalogen och köra följande kommando:
```
vcpkg --version
```

Du bör få följande utdata:

vcpkg package management program version <version>

Installera biblioteken

Det här avsnittet vägleder dig genom processen att installera nödvändiga bibliotek från Azure SDK för C++ med vcpkg. Det här avsnittet visar hur du använder vcpkg i manifestläge, vilket skapar ett par vcpkg-projektfiler för att hantera projektets beroenden även när de delas med andra medarbetare.

Windows – PowerShell
MacOS/Linux – Bash

Från rotkatalogen i projektet kör du följande kommando för att starta ett nytt vcpkg-projekt i manifestläge:
```
vcpkg new --application
```
Det bör nu finnas en vcpkg.json fil och en vcpkg-configuration.json fil i projektkatalogen.
Nu kan vi lägga till Azure Key Vault- och Identity-biblioteken från Azure SDK för C++ i vårt projekt genom att köra följande kommando:
```
vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp
```

Den vcpkg.json filen bör nu ha följande innehåll:

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

Från rotkatalogen i projektet kör du följande kommando för att starta ett nytt vcpkg-projekt i manifestläge:
```
vcpkg new --application
```
Det bör nu finnas en vcpkg.json fil och en vcpkg-configuration.json fil i projektkatalogen.
Nu kan vi lägga till Azure Key Vault- och Identity-biblioteken från Azure SDK för C++ i vårt projekt genom att köra följande kommando:
```
vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp
```

Den vcpkg.json filen bör nu ha följande innehåll:

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

Skapa en Azure Key Vault-resurs

I det här avsnittet beskrivs hur du använder Azure CLI för att skapa en Azure Key Vault-resurs. Den här Key Vault-resursen lagrar och hanterar känslig information på ett säkert sätt, till exempel hemligheter och nycklar.

Windows – PowerShell
MacOS/Linux – Bash

Använd Azure CLI för att logga in genom att ange följande kommando i terminalen:
```
az login
```
Använd popup-fönstren för att logga in på Azure.
När du har använt popup-webbläsarfönstret för att logga in väljer du den Azure-prenumeration som du vill använda i terminalen.
Använd sedan följande kommando för att skapa din Key Vault-resurs och kom ihåg att ersätta <your-resource-group-name> och <your-key-vault-name> med dina egna unika namn:
```
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
I utdata bör du se en lista över egenskaper med en vaultUri egenskap. Ange den till en miljövariabel som ska användas i vårt program med följande kommando:
```
$env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
```

Använd Azure CLI för att logga in genom att ange följande kommando i terminalen:
```
az login
```
Använd popup-fönstren för att logga in på Azure.
När du har använt popup-webbläsarfönstret för att logga in väljer du den Azure-prenumeration som du vill använda i terminalen.
Använd sedan följande kommando för att skapa din Key Vault-resurs och kom ihåg att ersätta <your-resource-group-name> och <your-key-vault-name> med dina egna unika namn:
```
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
I utdata bör du se en lista över egenskaper med en vaultUri egenskap. Ange den till en miljövariabel som ska användas i vårt program med följande kommando:
```
export AZURE_KEYVAULT_URL="https://<your-key-vault-name>.vault.azure.net/"
```

Kontrollera slutligen att ditt Azure-konto har rätt behörighet att arbeta med Key Vault-hemligheter. Du kan ge dig själv rätt behörigheter genom att tilldela dig själv rollen "Key Vault Secrets Officer" på sidan Åtkomstkontroll (IAM) för din Key Vault-resurs i Azure-portalen. IAM står för identitets- och åtkomsthantering.

Konfigurera projektet

I det här avsnittet beskrivs processen med att skapa de mappar och filer som krävs för att konfigurera ditt Azure C++-projekt.

Skapa en CMakeLists.txt fil i roten i projektkatalogen. Den här filen används för att konfigurera vårt CMake-projekt. Lägg till följande kod i CMakeLists.txt-filen :

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

Skapa en main.cpp fil i roten i projektkatalogen. Lägg till följande kod i filen 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;
}

Skapa en byggkatalog för byggartefakterna.

Bygg och kör

I det här avsnittet beskrivs hur du konfigurerar och skapar projektet med hjälp av CMake-kommandon och kör sedan programmet för att säkerställa att allt är korrekt konfigurerat. Kommandona i det här avsnittet ska köras från roten i ditt projekt där build katalogen, CMakeLists.txtoch main.cpp filerna finns.

Windows – PowerShell
MacOS/Linux – Bash

Ange följande kommando för att konfigurera CMake:
```
cmake -B ./build
```
Om du vill skapa projektet anger du följande kommando:
```
cmake --build ./build
```
Om du vill köra programmet anger du följande kommando:
```
.\build\Debug\azure_sample.exe
```

Programmet bör ha följande utdata:

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

Ange följande kommando för att konfigurera CMake:
```
cmake -B ./build
```
Om du vill skapa projektet anger du följande kommando:
```
cmake --build ./build
```
Om du vill köra programmet anger du följande kommando:
```
./build/azure_sample
```

Programmet bör ha följande utdata:

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

Felsökning

Det går inte att hitta resursgruppen

Om du använder AzureCLI för att skapa en Key Vault-instans finns inte den resursgrupp som du försöker lägga till Key Vault-instansen i om du får följande fel.

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

Om du vill skapa resursgruppen kan du använda följande kommando:

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

Mer information finns i AzureCLI-dokumenten om hantering av Azure-resursgrupper.

CMake-konfiguration eller kompilering kan inte hitta Azure-paket

När du kör CMake-konfigurations- eller byggkommandona, om du får följande fel eller något liknande, kör inte filen CMakeLists.txt modulen vcpkg.cmake innan CMake-projektet upprättas eller inte alls.

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.

Kontrollera i filenCMakeLists.txt att set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") raden ligger ovanför project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

Kontrollera sedan också att /path/to/vcpkg-root/ raden på set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") raden har uppdaterats till den plats där vcpkg installerades.

Syntaxfel i cmake-kod

Om du får följande fel när du kör CMake-konfigurations- eller byggkommandona kan filenCMakeLists.txt innehålla sökvägar med hjälp av \. Det här problemet kan vara vanligt när du använder Windows-sökvägar.

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

Trots att Windows använder \ i filsökvägar, använder CMake endast / i filsökvägar. Problemet kan lösas genom att ersätta alla \ med / i sökvägar som används i CMakeLists.txt-filen .

Om felet kvarstår när du har gjort ändringen kan du läsa avsnittet CMake-fel som kvarstår när du har gjort ändringar för att lära dig hur du löser dem.

CMake-fel kvarstår efter ändring

När du kör kommandot CMake configure kan du prova att rensa CMake-cachen om du fortsätter att få samma fel när du har gjort ändringar för att åtgärda det. CMake-cachen kan rensas genom att ta bort innehållet i byggkatalogen och sedan köra kommandot CMake configure igen.

CMake 3.30 eller senare krävs

När du kör kommandot CMake configure kan du behöva uppdatera din version av CMake om du får ett felmeddelande som liknar följande.

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

Lös det här felet genom att uppdatera installationen av CMake till den version som anges i felmeddelandet.

Anroparen har inte behörighet att utföra åtgärder på resursen

Om du får ett felmeddelande som följande när du kör C++-exempelprogrammet har du inte rätt behörighet att arbeta med hemligheter på den angivna Key Vault-resursen.

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>

Rätt behörigheter kan ges till ditt konto antingen med hjälp av Azure-portalen eller Azure CLI.

Om du vill uppdatera dina behörigheter med hjälp av Azure-portalen går du till sidan Åtkomstkontroll (IAM) för din Key Vault-resurs. Välj listrutan Lägg till och välj Lägg till rolltilldelning. På sidan Roll väljer du rollen Key Vault Secrets Officer och väljer Nästa längst ned på sidan. På sidan Medlemmar lämnar du alternativet Tilldela åtkomst till på Användaren, gruppen eller tjänstens huvudnamn och väljer på länken Välj medlemmar . I popup-fönstret till höger söker du efter och väljer ditt ID och väljer sedan Välj längst ned i popup-fönstret. Det ID som du valde bör nu visas i tabellen i avsnittet Medlemmar . Tryck på Granska + tilldela-knappen längst ned. Tryck på knappen Granska + tilldela igen.

Om du vill uppdatera dina behörigheter med hjälp av Azure CLI anger du följande kommando, ersätter <upn> med användarens huvudnamn, <subscription-id> med ditt prenumerations-ID, <resource-group-name> med resursgruppens namn och <your-unique-keyvault-name> med ditt Key Vault-instansnamn:

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 innehåller fel

Om du ser felrader under dina inkluderingsinstruktioner när du använder VS Code (visas i följande bild) vet inte redigeraren var du hittar inkluderingskatalogen.

{Skärmbild av C++ innehåller instruktioner från VS Code som har röda fel med vågiga rader under.}

vcpkg placerar include-huvudena i build/vcpkg_installed/<vcpkg-platform-triplet>/include när i manifestläge. Ersätt <vcpkg-platform-triplet> med vcpkg-triple för din plattform.

Om du vill lägga till inkluderingskatalogen i VS Code-inställningarna hovrar du över include-instruktionen med felraden. Välj sedan länken Snabbkorrigering... längst ned i popup-fönstret. I snabbkorrigeringsalternativen väljer du alternativet Lägg till i "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . Fliken Konfiguration av C/C++-tillägg bör öppnas och under avsnittet "Inkludera sökväg" bör du se sökvägen till inkluderingskatalogen i listan.

Linux bootstrap-vcpkg kunde inte hitta beroenden

När du kör bootstrap-vcpkg.sh skriptet på Linux, om du får ett fel som följande, har du inte de verktyg som krävs för att köra skriptet.

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)

Om du vill installera verktygen använder du det angivna kommandot i felmeddelandet för linux-distributionen. På Ubuntu skulle det till exempel vara följande kommando:

sudo apt-get install curl zip unzip tar

Kör sedan skriptet igen bootstrap-vcpkg.sh .

Det gick inte att hitta verktygskedjans fil i Linux

Om du får ett felmeddelande som följande när du kör kommandot CMake configure har sökvägen till modulerna vcpkg.cmake inte angetts korrekt.

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)

I CMakeLists.txt-filen uppdaterar du instruktionen set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") med rätt sökväg till platsen där vcpkg installerades.

Installationen av Linux vcpkg misslyckades

När du kör kommandot CMake configure måste systemberoenden för paketen installeras om du får ett felmeddelande som följande.

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

Om du vill hitta de systempaket som behövs söker du i utdata från CMake-konfigurationskommandona efter rader som börjar med Could not find <system-package>och ersätter <system-package> med det systempaket som saknas. Under den här raden bör det finnas ett kommando för att installera det systempaket som saknas. Kör kommandot. Kör sedan CMake-konfigurationskommandot igen. Du kan behöva upprepa den här processen några gånger beroende på antalet systempaket som saknas.

Nästa steg

Feedback

Var den här sidan till hjälp?