Azure SDK Core Library för C++

Azure::Core (azure-core) tillhandahåller delade primitiver, abstraktioner och hjälpfunktioner för moderna Azure SDK-klientbibliotek skrivna i C++. Dessa bibliotek följer Azure SDK:s designriktlinjer för C++.

Biblioteket gör det möjligt för klientbibliotek att exponera vanliga funktioner på ett konsekvent sätt. När du har lärt dig hur du använder dessa API:er i ett klientbibliotek vet du hur du använder dem i andra klientbibliotek.

Komma igång

Normalt behöver du inte ladda ned azure-core. Det laddas ned för dig som ett beroende av klientbiblioteken. Om du vill ladda ned den explicit (till exempel för att implementera ditt eget klientbibliotek) kan du hitta källan här eller använda vcpkg för att installera paketet azure-core-cpp.

Inkludera paketet

Det enklaste sättet att hämta C++ SDK är att utnyttja vcpkg-pakethanteraren. Se motsvarande Azure SDK för C++-readme-avsnittet.

Så här installerar du Azure Core-paketet via vcpkg:

> vcpkg install azure-core-cpp

Använd sedan i CMake-filen:

find_package(azure-core-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-core)

Viktiga begrepp

De viktigaste delade begreppen Azure::Core är:

• Hantera strömmande data och indata/utdata (I/O) via BodyStream tillsammans med dess härledda typer.
• Åtkomst till HTTP-svarsinformation för den returnerade modellen för alla SDK-klientåtgärder via Response<T>.
• Avsökning av långvariga åtgärder (LRO: er) via Operation<T>.
• Undantag för att rapportera fel från tjänstbegäranden på ett konsekvent sätt via den grundläggande undantagstypen RequestFailedException.
• Abstraktioner för Azure SDK-autentiseringsuppgifter (TokenCredential).
• Ersättningsbart HTTP-transportlager för att skicka begäranden och ta emot svar via nätverket.
• HTTP-pipeline- och HTTP-principer, till exempel återförsök och loggning, som kan konfigureras via klientspecifika alternativ för tjänsten.

Tidskrävande åtgärder

Vissa åtgärder tar lång tid att slutföra och kräver avsökning för deras status. Metoder som startar långvariga åtgärder returnerar Operation<T> typer.

Du kan ibland avsöka om åtgärden har slutförts med hjälp Poll() av metoden för den returnerade Operation<T> och spåra förloppet för åtgärden med hjälp Value()av . Du kan också använda PollUntilDone()om du bara vill vänta tills åtgärden har slutförts.

SomeServiceClient client;

auto operation = *client.StartSomeLongRunningOperation();

while (!operation.IsDone())
{
  std::unique_ptr<Http::RawResponse> response = operation.Poll();

  auto partialResult = operation.Value();

  // Your per-polling custom logic goes here, such as logging progress.

  // You can also try to abort the operation if it doesn't complete in time.

  std::this_thread::sleep_for(std::chrono::milliseconds(1000));
}

auto finalResult = operation.Value();

HTTP-transportkort

Azure SDK för C++ stöder biblioteken libcurl och WinHTTP som HTTP-staplar för kommunikation med Azure-tjänster via nätverket. SDK:t tillhandahåller också en mekanism för customer-implementedHTTP-transportkort. Du kan läsa mer om transportkortet i det här dokumentet.

Felsökning

Tre huvudsakliga sätt att felsöka fel är:

• Inspektera undantag
• Aktivera loggning (se SDK-loggmeddelanden)

SDK-loggmeddelanden

Det enklaste sättet att aktivera loggar är att ange AZURE_LOG_LEVEL miljövariabeln till ett av värdena: ||AZURE_LOG_LEVELAzure::Core::Diagnostics::Logger::Level|Loggmeddelandenivå |-|-|-| |4, eller error, eller err|Error|Loggningsnivå för fel som programmet sannolikt inte kommer att återställas från.| |3, eller warning, eller warn|Warning|Loggningsnivå när en funktion inte kan utföra sin avsedda uppgift.| |2, eller informational, eller informationeller info|Informational|Loggningsnivå när en funktion fungerar normalt.| |1, eller verbose, eller debug|Verbose|Loggningsnivå för detaljerade felsökningsscenarier.|

Sedan skrivs loggmeddelanden ut till konsolen (stderr). Observera att stderr meddelanden kan omdirigeras till en loggfil så här:

På Windows:

myprogram.exe 2> log.txt

I Linux eller macOS:

./myprogram 2> log.txt

Dessutom kan loggmeddelanden bearbetas programmatiskt genom att tillhandahålla en återanropsfunktion som kan spara dem i en fil eller visa dem på ett önskat anpassat sätt.

#include <azure/core/diagnostics/logger.hpp>

int main()
{
    using namespace Azure::Core::Diagnostics;

    // See above for the level descriptions.
    Logger::SetLevel(Logger::Level::Verbose);

    // SetListener accepts std::function<>, which can be either lambda or a function pointer.
    Logger::SetListener([&](auto lvl, auto msg){ /* handle Logger::Level lvl and std::string msg */ });
}

Observera att återanropet till lyssnaren körs i samma tråd som den åtgärd som utlöste loggmeddelandet. Vi rekommenderar implementering på grund av den minimala mängden bearbetning av loggmeddelanden i motringningstråden. När meddelandebearbetning krävs bör du överväga att implementera på ett sätt som motringningen skickar meddelandesträngen till en trådsäker kö, så att en annan tråd väljer meddelandena från kön och hanterar dem.

Nästa steg

Utforska och installera tillgängliga Azure SDK-bibliotek.

Contributing

Mer information om hur du bidrar till den här lagringsplatsen finns i bidragsguiden.

Det här projektet välkomnar bidrag och förslag. De flesta bidrag kräver att du godkänner ett licensavtal för deltagare (CLA) som förklarar att du har rätt att, och faktiskt gör det, ge oss rätten att använda ditt bidrag. Mer information finns i licensavtalet för deltagare.

När du skickar en pull-begäran avgör en CLA-robot automatiskt om du behöver tillhandahålla ett CLA och dekorera PR på rätt sätt (t.ex. etikett, kommentar). Följ bara anvisningarna från roboten. Du behöver bara göra detta en gång för alla lagringsplatser med vår CLA.

Det här projektet har antagit Microsoft Open Source Code of Conduct (Microsofts regler för uppförande för öppen källkod). Mer information finns i vanliga frågor och svar om uppförandekod eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Ytterligare användbara länkar för deltagare

Många människor över hela världen har hjälpt till att göra detta projekt bättre. Du vill checka ut:

• Vilka är några bra första problem för nya deltagare på lagringsplatsen?
• Så här skapar och testar du din ändring
• Hur du kan göra en ändring händer!
• Vanliga frågor och svar och konceptuella ämnen i den detaljerade Azure SDK för C++-wikin.

Rapportera säkerhetsproblem och säkerhetsbuggar

Säkerhetsproblem och buggar ska rapporteras privat via e-post till Microsoft Security Response Center (MSRC). secure@microsoft.com Du bör få ett svar inom 24 timmar. Om du av någon anledning inte gör det följer du upp via e-post för att säkerställa att vi har fått ditt ursprungliga meddelande. Mer information, inklusive MSRC PGP-nyckeln, finns i Security TechCenter.

Licens

Azure SDK för C++ licensieras under MIT-licensen .