github/azure-sdk-for-cpp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Add LRO concept section to core, along with a sample snippet to help get started. (#1729)

Browse Source 
* Add LRO concept section to core, along with a sample snippet to help get started.

* address feedback
This commit is contained in:
Ahson Khan 2021-02-24 09:14:17 -08:00 committed by GitHub
parent f48a850284
commit d1e43af75e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 42 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -50,7 +50,7 @@ Once the library is installed, follow the instructions from the console output t
```CMake
find_package(azure-storage-blobs-cpp CONFIG REQUIRED)
target_link_libraries(myProject PRIVATE Azure::azure-storage-blobs)
target_link_libraries(<your project name> PRIVATE Azure::azure-storage-blobs)
```
> NOTE: All the Azure client libraries take a dependency on `azure-core-cpp` which provides functionality commonly needed by all Azure clients. When you install any client library via vcpkg, it will bring in all the necessary dependencies as well. You don't need to install those individually to get started.
@ -101,6 +101,8 @@ int main()
}
```
Understanding the key concepts from the `azure-core-cpp` library, which is leveraged by all client libraries will also be helpful in getting started, regardless of which Azure service you want to use. You can find more information about them, with sample code snippets, here: https://github.com/Azure/azure-sdk-for-cpp/tree/master/sdk/core/azure-core#key-concepts
#### Visual Studio - CMakeSettings.json
When building your application via Visual Studio, you can create and update a `CMakeSettings.json` file and include the following properties to let Visual Studio know where the packages are installed and which triplet needs to be used:

48
sdk/core/azure-core/README.md
View File

@ -2,21 +2,51 @@
Azure::Core (`azure-core`) provides shared primitives, abstractions, and helpers for modern Azure SDK client libraries written in the C++. These libraries follow the [Azure SDK Design Guidelines for C++][azure_sdk_cpp_development_guidelines].
The library allows client libraries to expose common functionality in a consistent fashion. Once you learn how to use these APIs in one client library, you will know how to use them in other client libraries.
The library allows client libraries to expose common functionality in a consistent fashion. Once you learn how to use these APIs in one client library, you will know how to use them in other client libraries.
## Getting started
Typically, you will not need to download `azure-core`; it will be downloaded for you as a dependency of the client libraries. In case you want to download it explicitly (to implement your own client library, for example), you can find the source
in here.
Typically, you will not need to download `azure-core`; it will be downloaded for you as a dependency of the client libraries. In case you want to download it explicitly (to implement your own client library, for example), you can find the source in here, or use vcpkg to install the package `azure-core-cpp`.
## Key concepts
The main shared concepts of Azure::Core include:
- Configuring service cliesnt, e.g. configuring retries, logging, etc.. (`ClientOptions`)
- Accessing HTTP response details (`Response`, `Response<T>`)
- Polling long-running operations
- Exceptions for reporting errors from service requests in a consistent fashion (`RequestFailedException`)
- Abstractions for Azure SDK Credentials (`TokenCredential`)
The main shared concepts of `Azure::Core` include:
- HTTP pipeline and HTTP policies such as retry and logging, which are configurable via service client specific options.
- Handling streaming data and input/output (I/O) via `BodyStream` along with its derived types.
- Accessing HTTP response details for the returned model of any SDK client operation, via `Response<T>`.
- Polling long-running operations (LROs), via `Operation<T>`.
- Exceptions for reporting errors from service requests in a consistent fashion via the base exception type `RequestFailedException`.
- Abstractions for Azure SDK credentials (`TokenCredential`).
- Replaceable HTTP transport layer to send requests and receive responses over the network.
### Long Running Operations
Some operations take a long time to complete and require polling for their status. Methods starting long-running operations return `Operation<T>` types.
You can intermittently poll whether the operation has finished by using the `Poll()` method on the returned `Operation<T>` and track progress of the operation using `Value()`. Alternatively, if you just want to wait until the operation completes, you can use `PollUntilDone()`.
```C++
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 Transport adapter