Aracılığıyla paylaş

C++ için Azure SDK'dan kitaplıkları yükleme ve tümleştirme

Bu kılavuz, geliştiricilere vcpkg kullanarak C++ için Azure SDK'dan kitaplık yüklemek ve bunları CMake ile projeleriyle tümleştirmek için gerekli adımları sağlar. Yönergeleri izleyerek geliştirme ortamınızı ayarlayabilir ve C++ uygulamalarınızda Azure hizmetlerini kullanmaya başlayabilirsiniz. Azure'da yeniyseniz veya tümleştirme sürecinizi kolaylaştırmak istiyorsanız, bu belgeler hızlı ve verimli bir şekilde çalışmaya başlamanıza yardımcı olur.

Önkoşullar

Git ve CMake yüklemesini doğrulama

Sorunsuz bir tümleştirme işlemi sağlamak için git ve CMake'nin sisteminize doğru şekilde yüklendiğini doğrulamanız önemlidir.

  1. Git'in düzgün yüklendiğini doğrulamak için terminalinizde aşağıdaki komutu çalıştırın:

    git --version

  2. Git için şu anda yüklü olan sürümü belirten bir çıkış almanız gerekir, örneğin:

    git version <version>

  3. CMake'nin düzgün yüklendiğini doğrulamak için terminalinizde aşağıdaki komutu çalıştırın:

    cmake --version

  4. CMake'nin şu anda yüklü olan sürümünü belirten bir çıkış almanız gerekir:

    cmake version <version>

vcpkg yükleme

C++ kitaplıkları için Azure SDK'yı yönetmek ve yüklemek için vcpkg kullanın. vcpkg , bağımlılıkları işleme sürecini basitleştiren platformlar arası bir paket yöneticisidir.

  1. vcpkg yüklemek için önce vcpkg depoyu kopyalayın. Önerilen yaklaşım, vcpkg'yi C++ proje dizininizde değil geliştirme ortamınızda merkezi bir konuma kopyalamaktır. Bu örnekte, vcpkg ana dizine kopyalanmıştır.

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

  2. vcpkg deposu kopyalandıktan sonra yeni dizine geçin ve betiği çalıştırın bootstrap-vcpkg.bat .

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

  3. vcpkg'yi önyükledikten sonra, vcpkg yürütülebilir dosyasına proje dizininizden erişebilmek için bunu yolunuza ekleyin. Komut örneğindeki <path\to\vcpkg> değerini daha önce klonladığınız vcpkg dizininin yolu ile değiştirmeyi unutmayın.

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

  4. vcpkg dizininin yolunuzda eklendiğini doğrulamak için proje dizininize geri dönün ve aşağıdaki komutu çalıştırın:

    vcpkg --version

  5. Aşağıdaki çıkışı almanız gerekir:

    vcpkg package management program version <version>

Kütüphaneleri yükle.

Bu bölüm, vcpkg kullanarak C++ için Azure SDK'dan gerekli kitaplıkları yükleme işleminde size yol gösterir. Bu bölümde, diğer ortak çalışanlarla paylaşıldığında bile projenin bağımlılıklarının yönetilmesine yardımcı olmak için birkaç vcpkg proje dosyası oluşturan bildirim modunda vcpkg'nin nasıl kullanılacağı gösterilmektedir.

  1. Projenizin kök dizininden aşağıdaki komutu çalıştırarak bildirim modunda yeni bir vcpkg projesi başlatın:

    vcpkg new --application

  2. Artık proje dizininizde birvcpkg.json dosyası ve vcpkg-configuration.json dosyası olmalıdır.

  3. Şimdi aşağıdaki komutu çalıştırarak C++ için Azure SDK'sından Azure Key Vault ve Kimlik kitaplıklarını projemize ekleyebiliriz:

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

  4. vcpkg.json dosyası artık aşağıdaki içeriklere sahip olmalıdır:

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

Azure Key Vault kaynağı oluşturma

Bu bölümde, Azure Key Vault kaynağı oluşturmak için Azure CLI'nin nasıl kullanılacağı açıklanır. Bu Key Vault kaynağı gizli diziler ve anahtarlar gibi hassas bilgileri güvenli bir şekilde depolar ve yönetir.

  1. Terminalinize aşağıdaki komutu girerek oturum açmak için Azure CLI'yi kullanın:

    az login

  2. Azure'da oturum açmak için açılır pencereleri kullanın.

  3. Oturum açmak için açılır tarayıcı penceresini kullandıktan sonra terminalde kullanmak istediğiniz Azure aboneliğini seçin.

  4. Ardından aşağıdaki komutu kullanarak Key Vault kaynağınızı oluşturun ve <your-resource-group-name> ile <your-key-vault-name> yerine kendi benzersiz adlarınızı kullanmayı unutmayın.

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

  5. Çıktıda, bir vaultUri özelliği ile birlikte gelen özelliklerin listesini görmelisiniz. Bunu, aşağıdaki komutla programımızda kullanılacak bir ortam değişkeni olarak ayarlayın:

    $env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
  1. Son olarak, Azure hesabınızın Key Vault Gizli Kodlarıyla çalışmak için uygun izinlere sahip olduğundan emin olun. Azure portalındaki Key Vault kaynağınızın Erişim Denetimi (IAM) sayfasında kendinize "Key Vault Gizli Dizileri Yetkilisi" rolünü atayarak kendinize uygun izinleri verebilirsiniz. IAM, kimlik ve erişim yönetimi anlamına gelir.

Projenizi ayarlayın

Bu bölümde, Azure C++ projenizi ayarlamak için gerekli klasörleri ve dosyaları oluşturma işlemi açıklanmaktadır.

  1. Proje dizininizin kökünde birCMakeLists.txt dosyası oluşturun. Bu dosya CMake projemizi yapılandırmak için kullanılır. CMakeLists.txt dosyasına aşağıdaki kodu ekleyin:

    # 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. Proje dizininizin kökünde bir main.cpp dosyası oluşturun. main.cpp dosyasına aşağıdaki kodu ekleyin:

    #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. Derleme yapıtları için bir derleme dizini oluşturun.

Derle ve çalıştır

Bu bölümde, CMake komutlarını kullanarak projenizi yapılandırma ve derleme ve ardından her şeyin doğru ayarlandığından emin olmak için programı çalıştırma işlemi açıklanır. Bu bölümdeki komutlar, dizininin, buildve CMakeLists.txt dosyalarının bulunduğu main.cpp projenizin kökünden çalıştırılmalıdır.

  1. CMake'yi yapılandırmak için aşağıdaki komutu girin:

    cmake -B ./build

  2. Projeyi oluşturmak için aşağıdaki komutu girin:

    cmake --build ./build

  3. Programı çalıştırmak için aşağıdaki komutu girin:

    .\build\Debug\azure_sample.exe

  4. Program aşağıdaki çıkışa sahip olmalıdır:

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

Sorun giderme

Kaynak grubu bulunamadı

Key Vault örneği oluşturmak için AzureCLI kullanırken aşağıdaki hatayı alırsanız Key Vault örneğini eklemeye çalıştığınız kaynak grubu mevcut değildir.

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

Kaynak grubunu oluşturmak için aşağıdaki komutu kullanabilirsiniz:

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

Daha fazla bilgi için Azure Kaynak Gruplarını Yönetme hakkındaki AzureCLI belgelerine göz atın.

CMake yapılandırma veya derleme sırasında Azure paketlerini bulamıyor

CMake yapılandırma veya derleme komutlarını çalıştırdığınızda aşağıdaki hatayı veya benzer bir hatayı alırsanız, CMakeLists.txt dosyası, CMake projesi kurulmadan önce ya da hiç vcpkg.cmake modülünü çalıştırmıyor.

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.

CMakeLists.txt dosyasında, set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") satırının project(azure_sample VERSION 0.1.0 LANGUAGES C CXX) üzerinde olduğunu doğrulayın.

Ardından, /path/to/vcpkg-root/ satırındaki set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") öğesinin vcpkg'nin yüklendiği konuma güncellenmiş olduğundan emin olun.

Cmake kodunda söz dizimi hatası

CMake yapılandırması veya derleme komutlarını çalıştırırken, aşağıdaki hatayı alırsanız CMakeLists.txt dosyası \ kullanılarak yollar içerebilir. Windows dosya yollarını kullanırken bu sorun yaygın olabilir.

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

Windows dosya yollarında \ kullanırken, CMake dosya yollarında yalnızca / kullanır. Sorun, \ dosyasında kullanılan yollardaki tüm / öğelerini ile değiştirerek çözülebilir.

Değişikliği yaptıktan sonra hatanız devam ederse, bunların nasıl çözüleceğini öğrenmek için CMake hataları değişiklik yaptıktan sonra da devam ediyor bölümüne bakın.

Değişiklik yaptıktan sonra CMake hataları devam ediyor

CMake configure komutunu çalıştırırken, düzeltmek için değişiklik yaptıktan sonra aynı hatayı almaya devam ederseniz CMake önbelleğini temizlemeyi deneyin. CMake önbelleği , derleme dizininin içeriği silindikten sonra CMake yapılandırma komutu yeniden çalıştırılarak temizlenebilir.

CMake 3.30 veya üzeri gereklidir

CMake configure komutunu çalıştırırken aşağıdaki gibi bir hata alırsanız CMake sürümünüzü güncelleştirmeniz gerekebilir.

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

Bu hatayı çözmek için CMake yüklemenizi hata iletisinde belirtilen sürüme güncelleştirin.

Çağıranın kaynak üzerinde eylem gerçekleştirme yetkisi yok

C++ örnek programını çalıştırırken aşağıdaki gibi bir hata alırsanız, belirtilen Key Vault kaynağında gizli dizilerle çalışmak için uygun izinlere sahip değilsiniz.

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>

Azure portalı veya Azure CLI kullanılarak hesabınıza uygun izinler verilebilir.

Azure portalını kullanarak izinlerinizi güncelleştirmek için Key Vault kaynağınızın Erişim Denetimi (IAM) sayfasına gidin. Ekle açılır listesini ve ardından Rol ataması ekle seçeneğini seçin. Rol sayfasında Key Vault Gizli DiziLeri Yetkilisi rolünü seçin ve sayfanın alt kısmındaki İleri'yi seçin. Üyeler sayfasında, Erişimi ata seçeneğini Kullanıcı, grup veya hizmet sorumlusu olarak bırakın ve Üye seç bağlantısını seçin. Sağ taraftaki açılır pencerede kimliğinizi arayın ve seçin, ardından açılır pencerenin alt kısmındaki Seç'i seçin. Seçtiğiniz kimlik artık Üyeler bölümünün tablosunda gösterilmelidir. Alttaki Gözden Geçir ve ata düğmesini seçin. Ardından Gözden Geçir ve ata düğmesini yeniden seçin.

Azure CLI kullanarak izinlerinizi güncelleştirmek için aşağıdaki komutu girin ve yerine <upn> kullanıcı asıl adınızı, abonelik kimliğinizi, <subscription-id><resource-group-name> kaynak grubu adınızı ve <your-unique-keyvault-name> Key Vault örneğinizin adını yazın:

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 içerme hataları

VS Code kullanırken ekleme deyimlerinizin altında hata satırları görürseniz (aşağıdaki görüntüde gösterilmiştir), düzenleyici ekleme dizinini nerede bulacağını bilmez.

{Altında kırmızı hata dalgalı çizgileri olan VS Code'dan C++ include ifadelerinin ekran görüntüsü.}

vcpkg, üst bilgi başlıklarını bildirim modunda olduğunda build/vcpkg_installed/<vcpkg-platform-triplet>/include içine yerleştirir. <vcpkg-platform-triplet> öğesini platformunuzun vcpkg üçlüsüyle değiştirin.

EKLEME dizinini VS Code ayarlarınıza eklemek için, hata satırıyla birlikte include deyiminin üzerine gelin. Ardından açılan pencerenin alt kısmındaki Hızlı Düzeltme... bağlantısını seçin. Hızlı Düzeltme seçeneklerinde Ekle "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include seçeneğini belirleyin. C/C++ Uzantı Yapılandırması sekmesi açılmalı ve "Yolu ekle" bölümünün altında ekleme dizininin yolunun listelendiğini görmeniz gerekir.

Linux bootstrap-vcpkg bağımlılıkları bulamadı

Linux'ta bootstrap-vcpkg.sh betiğini çalıştırırken aşağıdaki gibi bir hata alırsanız, betiği çalıştırmak için gerekli araçlar yüklü değildir.

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)

Araçları yüklemek için linux dağıtımınız için hata iletisinde sağlanan komutu kullanın. Örneğin, Ubuntu'da aşağıdaki komut olacaktır:

sudo apt-get install curl zip unzip tar

Yeniden bootstrap-vcpkg.sh betiğini çalıştırın.

Linux araç zinciri dosyasını bulamadı

CMake configure komutunu çalıştırırken aşağıdaki gibi bir hata alırsanız vcpkg.cmake modüllerinin yolu düzgün ayarlanmadı.

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)

CMakeLists.txt dosyasında set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") komutunu vcpkg'nin yüklendiği konuma doğru dosya yoluyla güncelleyin.

Linux vcpkg yüklemesi başarısız oldu

CMake configure komutunu çalıştırırken aşağıdaki gibi bir hata alırsanız paketler için sistem bağımlılıklarının yüklenmesi gerekir.

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

Gerekli sistem paketlerini bulmak için, CMake yapılandırma komutlarının çıktısını kontrol ederek Could not find <system-package> ile başlayan satırları arayın ve eksik sistem paketini <system-package> yerine ekleyin. Bu satırın altında eksik sistem paketini yüklemek için bir komut olmalıdır. Bu komutu çalıştırın. Ardından CMake yapılandırma komutunu yeniden çalıştırın. Eksik sistem paketlerinin sayısına bağlı olarak bu işlemi birkaç kez yinelemeniz gerekebilir.

Sonraki adım

  • Last updated on