Freigeben über

Installieren und Integrieren von Bibliotheken aus dem Azure SDK für C++

Dieses Handbuch bietet Entwicklern die erforderlichen Schritte zum Installieren von Bibliotheken aus dem Azure SDK für C++ mithilfe von vcpkg und die Integration in ihre Projekte mit CMake. Indem Sie die Anweisungen befolgen, können Sie Ihre Entwicklungsumgebung einrichten und mit der Verwendung von Azure-Diensten in Ihren C++-Anwendungen beginnen. Ganz gleich, ob Sie neu bei Azure sind oder Ihren Integrationsprozess optimieren möchten, mit dieser Dokumentation können Sie schnell und effizient beginnen.

Voraussetzungen

Überprüfen der Git- und CMake-Installation

Um einen reibungslosen Integrationsprozess sicherzustellen, ist es wichtig, sicherzustellen, dass Git und CMake ordnungsgemäß auf Ihrem System installiert sind.

  1. Um zu überprüfen, ob Git ordnungsgemäß installiert ist, führen Sie den folgenden Befehl in Ihrem Terminal aus:

    git --version

  2. Sie sollten eine Ausgabe erhalten, die die aktuell installierte Version für Git angibt, wie folgt:

    git version <version>

  3. Um zu überprüfen, ob CMake ordnungsgemäß installiert ist, führen Sie den folgenden Befehl in Ihrem Terminal aus:

    cmake --version

  4. Sie sollten eine Ausgabe erhalten, die die aktuell installierte Version von CMake angibt, wie folgt:

    cmake version <version>

Installieren von vcpkg

Verwenden Sie vcpkg, um das Azure SDK für C++-Bibliotheken zu verwalten und zu installieren. vcpkg ist ein plattformübergreifender Paket-Manager, der den Prozess der Behandlung von Abhängigkeiten vereinfacht.

  1. Um vcpkg zu installieren, klonen Sie zuerst das vcpkg-Repo. Der empfohlene Ansatz besteht darin, vcpkg an einen zentralen Speicherort in Ihrer Entwicklungsumgebung und nicht in Ihrem C++-Projektverzeichnis zu klonen. In diesem Beispiel wird vcpkg in das Home-Verzeichnis geklont.

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

  2. Nachdem das vcpkg-Repository geklont wurde, durchlaufen Sie das neue Verzeichnis, und führen Sie das bootstrap-vcpkg.bat Skript aus.

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

  3. Fügen Sie vcpkg nach dem Bootstrapping zu Ihrem Pfad hinzu, damit Sie die vcpkg-Binärdatei von Ihrem Projektverzeichnis aus ausführen können. Denken Sie daran, das <path\to\vcpkg> Im Befehlsbeispiel durch den Pfad zum zuvor geklonten vcpkg-Verzeichnis zu ersetzen.

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

  4. Um zu überprüfen, ob das vcpkg-Verzeichnis ihrem Pfad hinzugefügt wurde, wechseln Sie zurück zum Projektverzeichnis, und führen Sie den folgenden Befehl aus:

    vcpkg --version

  5. Die folgende Ausgabe sollte angezeigt werden:

    vcpkg package management program version <version>

Installieren der Bibliotheken

Dieser Abschnitt führt Sie durch den Prozess der Installation der erforderlichen Bibliotheken aus dem Azure SDK für C++ mithilfe von vcpkg. In diesem Abschnitt wird gezeigt, wie Sie vcpkg im Manifestmodus verwenden, wodurch einige vcpkg-Projektdateien erstellt werden, um die Abhängigkeiten des Projekts selbst dann zu verwalten, wenn sie für andere Projektmitarbeiter freigegeben wurden.

  1. Führen Sie im Stammverzeichnis Ihres Projekts den folgenden Befehl aus, um ein neues vcpkg-Projekt im Manifestmodus zu starten:

    vcpkg new --application

  2. Es sollte nun eine vcpkg.json-Datei und eine vcpkg-configuration.json Datei in Ihrem Projektverzeichnis vorhanden sein.

  3. Jetzt können wir die Azure Key Vault- und Identitätsbibliotheken aus dem Azure SDK für C++ zu unserem Projekt hinzufügen, indem wir den folgenden Befehl ausführen:

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

  4. Die dateivcpkg.json sollte jetzt den folgenden Inhalt haben:

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

Erstellen einer Azure Key Vault-Ressource

In diesem Abschnitt wird erläutert, wie Sie die Azure CLI zum Erstellen einer Azure Key Vault-Ressource verwenden. Diese Key Vault-Ressource speichert und verwaltet vertrauliche Informationen, wie Geheimnisse und Schlüssel.

  1. Verwenden Sie die Azure CLI, um sich anzumelden, indem Sie den folgenden Befehl in Ihr Terminal eingeben:

    az login

  2. Verwenden Sie die Popupfenster, um sich bei Azure anzumelden.

  3. Nachdem Sie das Popupbrowserfenster zum Anmelden verwendet haben, wählen Sie das Azure-Abonnement aus, das Sie im Terminal verwenden möchten.

  4. Verwenden Sie dann den folgenden Befehl, um Ihre Key Vault-Ressource zu erstellen, und denken Sie daran, <your-resource-group-name> und <your-key-vault-name> durch Ihre eigenen, eindeutigen Namen zu ersetzen.

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

  5. In der Ausgabe sollten die Eigenschaften in einer Liste angezeigt werden, die die Eigenschaft vaultUri enthält. Legen Sie dies auf eine Umgebungsvariable fest, die in unserem Programm mit dem folgenden Befehl verwendet werden soll:

    $env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
  1. Stellen Sie abschließend sicher, dass Ihr Azure-Konto über die richtigen Berechtigungen verfügt, um mit Schlüssel-Tresor-Geheimnissen zu arbeiten. Sie können sich selbst die richtigen Berechtigungen erteilen, indem Sie sich selbst die Rolle "Key Vault Secrets Officer" auf der Seite "Zugriffssteuerung (IAM)" Ihrer Key Vault-Ressource im Azure-Portal zuweisen. IAM steht für Identitäts- und Zugriffsverwaltung.

Einrichten des Projekts

In diesem Abschnitt wird der Prozess zum Erstellen der erforderlichen Ordner und Dateien zum Einrichten Ihres Azure C++-Projekts beschrieben.

  1. Erstellen Sie im Stammverzeichnis Ihres Projektverzeichnisses eine CMakeLists.txt Datei. Diese Datei wird verwendet, um unser CMake-Projekt zu konfigurieren. Fügen Sie der dateiCMakeLists.txt den folgenden Code hinzu:

    # 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. Erstellen Sie im Stammverzeichnis Ihres Projektverzeichnisses eine main.cpp Datei. Fügen Sie der datei main.cpp den folgenden Code hinzu:

    #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. Erstellen Sie ein Buildverzeichnis für die Buildartefakte.

Erstellen und Ausführen

In diesem Abschnitt wird erläutert, wie Sie Ihr Projekt mithilfe von CMake-Befehlen konfigurieren und erstellen, und führen Sie dann das Programm aus, um sicherzustellen, dass alles ordnungsgemäß eingerichtet ist. Die Befehle in diesem Abschnitt sollten aus dem Stammverzeichnis Ihres Projekts ausgeführt werden, in dem sich das build Verzeichnis, CMakeLists.txt und die main.cpp Dateien befinden.

  1. Um CMake zu konfigurieren, geben Sie den folgenden Befehl ein:

    cmake -B ./build

  2. Geben Sie zum Erstellen des Projekts den folgenden Befehl ein:

    cmake --build ./build

  3. Um das Programm auszuführen, geben Sie den folgenden Befehl ein:

    .\build\Debug\azure_sample.exe

  4. Das Programm sollte die folgende Ausgabe haben:

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

Problembehandlung

Ressourcengruppe nicht gefunden

Wenn Sie die AzureCLI zum Erstellen einer Key Vault-Instanz verwenden, wenn Sie den folgenden Fehler erhalten, ist die Ressourcengruppe, der Sie die Key Vault-Instanz hinzufügen möchten, nicht vorhanden.

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

Zum Erstellen der Ressourcengruppe können Sie den folgenden Befehl verwenden:

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

Weitere Informationen finden Sie in den AzureCLI-Dokumenten zum Verwalten von Azure-Ressourcengruppen.

Die CMake-Konfiguration oder -Erstellung kann keine Azure-Pakete finden.

Wenn Sie die CMake-Konfigurations- oder Buildbefehle ausführen und dabei den folgenden Fehler oder einen ähnlichen erhalten, wird die Datei CMakeLists.txt entweder nicht ausgeführt oder das Modul vcpkg.cmake wird nicht vor dem Einrichten des CMake-Projekts oder überhaupt nicht gestartet.

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.

Vergewissern Sie sich in der dateiCMakeLists.txt , dass sich die set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") Zeile oberhalb der project(azure_sample VERSION 0.1.0 LANGUAGES C CXX)Zeile befindet.

Überprüfen Sie dann auch, ob die /path/to/vcpkg-root/-Zeile in der set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake")-Zeile auf den Speicherort aktualisiert wird, an dem vcpkg installiert wurde.

Syntaxfehler im Cmake-Code

Wenn Sie bei der Ausführung der CMake-Konfiguration oder der Build-Befehle den folgenden Fehler erhalten, kann die CMakeLists.txt-Datei Pfade enthalten, die \ verwenden. Dieses Problem kann häufig auftreten, wenn Sie die Pfade von Window verwenden.

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

Obwohl Windows \ in Dateipfaden verwendet, nutzt CMake nur / in Dateipfaden. Das Problem kann behoben werden, indem alle \ durch / in den in der DateiCMakeLists.txt verwendeten Pfaden ersetzt werden.

Wenn der Fehler nach der Änderung weiterhin auftritt, lesen Sie im Abschnitt CMake-Fehler bleiben nach der Änderung bestehen, um zu erfahren, wie Sie diesen beheben können.

CMake-Fehler bleiben nach Änderung erhalten

Wenn Sie den Befehl "CMake configure" ausführen und nach Änderungen, um es zu beheben, weiterhin derselbe Fehler angezeigt wird, versuchen Sie, den CMake-Cache zu löschen. Der CMake-Cache kann gelöscht werden, indem der Inhalt des Buildverzeichnisses gelöscht und anschließend der Befehl "CMake konfigurieren" erneut ausgeführt wird.

CMake 3.30 oder höher erforderlich

Wenn Sie den Befehl "CMake konfigurieren" ausführen, müssen Sie möglicherweise Ihre Version von CMake aktualisieren, wenn sie eine Fehlermeldung wie die folgende erhalten.

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

Um diesen Fehler zu beheben, aktualisieren Sie Ihre Installation von CMake auf die in der Fehlermeldung angegebene Version.

Der Aufrufer ist nicht berechtigt, eine Aktion an der Ressource auszuführen.

Wenn Sie beim Ausführen des C++-Beispielprogramms eine Fehlermeldung wie die folgende erhalten, verfügen Sie nicht über die erforderlichen Berechtigungen, um mit geheimen Schlüsseln in der angegebenen Key Vault-Ressource zu arbeiten.

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>

Die richtigen Berechtigungen können Ihrem Konto entweder über das Azure-Portal oder die Azure CLI erteilt werden.

Um Ihre Berechtigungen über das Azure-Portal zu aktualisieren, navigieren Sie zur Seite Access Control (IAM) Ihrer Key Vault-Ressource. Wählen Sie das Dropdown " Hinzufügen" und dann " Rollenzuweisung hinzufügen" aus. Wählen Sie auf der Seite "Rolle " die Rolle " Key Vault Secrets Officer " aus, und wählen Sie unten auf der Seite "Weiter" aus. Lassen Sie auf der Seite " Mitglieder " die Option "Zugriff zuweisen " für "Benutzer", "Gruppe" oder "Dienstprinzipal " aus, und wählen Sie auf dem Link " Mitglieder auswählen " aus. Suchen Sie im Popup rechts nach Ihrer ID, und wählen Sie sie aus, und wählen Sie dann unten im Popup "Auswählen " aus. Die ausgewählte ID sollte nun in der Tabelle des Abschnitts " Mitglieder " angezeigt werden. Wählen Sie unten die Schaltfläche " Überprüfen+ Zuweisen" aus. Wählen Sie dann erneut die Schaltfläche "Überprüfen+ Zuweisen" aus .

Um Ihre Berechtigungen mithilfe der Azure CLI zu aktualisieren, geben Sie den folgenden Befehl ein, ersetzen <upn> Sie durch Ihren Benutzerprinzipalnamen, <subscription-id> ihre Abonnement-ID, <resource-group-name> ihren Ressourcengruppennamen und <your-unique-keyvault-name> ihren Key Vault-Instanznamen:

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 enthält Fehler

Wenn Fehlerzeilen unter Ihren Include-Anweisungen bei Verwendung von VS Code (siehe folgende Abbildung) angezeigt werden, weiß der Editor nicht, wo das Includeverzeichnis zu finden ist.

{Screenshot von C++ Include-Anweisungen aus VS Code mit roten Fehlerkringeln unterhalb.}

vcpkg platziert die Include-Header im build/vcpkg_installed/<vcpkg-platform-triplet>/include-Manifestmodus. Ersetzen Sie <vcpkg-platform-triplet> durch das vcpkg-Triplet für Ihre Plattform.

Um das Include-Verzeichnis zu Ihren VS Code-Einstellungen hinzuzufügen, fahren Sie mit der Maus über die Include-Anweisung mit der Fehlerzeile. Wählen Sie dann den Link "Schnellkorrektur" am unteren Rand des Popups aus. Wählen Sie in den Schnellkorrekturoptionen die Option "Hinzufügen zu "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include" aus. Die Registerkarte "C/C++-Erweiterungskonfiguration" sollte geöffnet werden, und unter dem Abschnitt "Pfad einschließen" sollte der Pfad zum eingeschlossenen Verzeichnis angezeigt werden.

Linux bootstrap-vcpkg konnte keine Abhängigkeiten finden

Wenn Sie das bootstrap-vcpkg.sh-Skript unter Linux ausführen, wenn sie einen Fehler wie die folgende erhalten, sind die erforderlichen Tools zum Ausführen des Skripts nicht installiert.

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)

Um die Tools zu installieren, verwenden Sie den bereitgestellten Befehl in der Fehlermeldung für Ihre Linux-Verteilung. Beispielsweise wäre es auf Ubuntu der folgende Befehl:

sudo apt-get install curl zip unzip tar

Führen Sie dann das bootstrap-vcpkg.sh Skript erneut aus.

Linux konnte die Toolkette-Datei nicht finden

Wenn Beim Ausführen des Befehls "CMake configure" ein Fehler wie folgt angezeigt wird, wurde der Pfad zu den vcpkg.cmake-Modulen nicht ordnungsgemäß festgelegt.

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)

Aktualisieren Sie in der CMakeLists.txt Datei die set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") Anweisung mit dem richtigen Pfad, zu dem vcpkg installiert wurde.

Fehler bei der Installation von Linux vcpkg

Wenn beim Ausführen des Befehls "CMake configure" ein Fehler wie folgender angezeigt wird, müssen Systemabhängigkeiten für die Pakete installiert werden.

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

Um die benötigten Systempakete zu finden, suchen Sie in der Ausgabe der CMake-Konfigurationsbefehle nach Zeilen, die mit Could not find <system-package> beginnen, und ersetzen Sie <system-package> durch das fehlende Systempaket. Unter dieser Zeile sollte ein Befehl zum Installieren dieses fehlenden Systempakets stehen. Führen Sie diesen Befehl aus. Führen Sie dann den Konfigurationsbefehl "CMake" erneut aus. Je nach Anzahl fehlender Systempakete müssen Sie diesen Vorgang möglicherweise ein paar Mal wiederholen.

Nächster Schritt