SiddiqSoft.CosmosClient
0.6.1-pullrequest0007-0005
This is a prerelease version of SiddiqSoft.CosmosClient.
There is a newer version of this package available.
See the version list below for details.
See the version list below for details.
dotnet add package SiddiqSoft.CosmosClient --version 0.6.1-pullrequest0007-0005
NuGet\Install-Package SiddiqSoft.CosmosClient -Version 0.6.1-pullrequest0007-0005
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SiddiqSoft.CosmosClient" Version="0.6.1-pullrequest0007-0005" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SiddiqSoft.CosmosClient --version 0.6.1-pullrequest0007-0005
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: SiddiqSoft.CosmosClient, 0.6.1-pullrequest0007-0005"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install SiddiqSoft.CosmosClient as a Cake Addin #addin nuget:?package=SiddiqSoft.CosmosClient&version=0.6.1-pullrequest0007-0005&prerelease // Install SiddiqSoft.CosmosClient as a Cake Tool #tool nuget:?package=SiddiqSoft.CosmosClient&version=0.6.1-pullrequest0007-0005&prerelease
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
CosmosClient : Azure Cosmos REST-API Client for Modern C++
Motivation
There is a need for a light-weight Azure Cosmos client that is crafted for C++ instead of "C" wrapper.
Features
- C++20 Azure Cosmos REST API client.
- Be instructive and functional.
- Low-overhead--just not optimized.
- C++20 sugarcoating
- JSON everywhere; configuration, I/O, results.
- Simple interface -- this means we limit the options you can fiddle
- Implement the Cosmos SQL REST API
- All of the responses are JSON documents as returned from Azure Cosmos. We do not abstract/encapsulate unless there is value.
- Implement Azure REST API best practices.
- Single header
- Use Microsoft Win32 API for IO, encryption
- Dependency on nlohmann.json
- The best interface
- Dependency on azure-cpp-utils our own library.
- We do not implement any encryption functions. We only add a thin modern C++ coating on the underlying Win32 SDK.
- Dependency on restcl our own library.
- Again, we wrap a modern C++ sugar coat on the Win32 WinHTTP library. Nothing overly heavy or force you to use std::wstring or invent yet-another-string!
- Dependency on nlohmann.json
- Simplicity and ease of use--focus on your problem set and let the libraries evolve.
Development Style
- Continuous improvement
- During early stages, development is going to be private until a first release candidate source.
- We break ABI often.
- Focus on end-use and ease-of-use over performance
- Build what is needed and add features subject to the above criteria
Requirements
- While the code is pretty much C++20 the IO uses WinHTTP underneath.
- The build and tests are for Visual Studio 2019 under x64 using googletest.
- We switched to googletest from VSTest for the insane reason that enabiling ASAN was not compatible with VSTest.
- As of Visual Studio v16.11.2 the tag
/c++20
no longer includesformat
and our code is stuck at/c++latest
.
API / Usage
You can start saving your documents in Cosmos with just 3 lines of code!
- Declare the instance
- Configure with json via
configure
- Make call to
create
The detailed API is over at Github pages.
Sample
#include "nlohmann/json.hpp"
#include "siddiqsoft/azure-cosmos-restcl.hpp"
// See the example1 test for full source code
// Code here has been trimmed for brevity.
void example1(const std::string& p, const std::string& s)
{
// You should maintain one instance for each Cosmos service
// It is advised to maintain a single instance per runtime (exe/dll/service)
siddiqsoft::CosmosClient cc;
// If you provide valid information, this will configure by probing Azure for
// region information and sets up the read and write locations.
// We use JSON object as the primary configuration interface.
// The items you provide are muxed with the defaults so you can provide as much
// or as little as the following elements.
cc.configure({{"partitionKeyNames", {"__pk"}},
{"connectionStrings", {p, s}}} );
// This is all we need to worry about when creating a document!
// Cosmos requires the "id" field be in the document so we perform
// no checks for id nor the primaryKey field.
// The goal is to get you the response from Cosmos with little more
// than convenience overhead.
// No useless abstractions.
// Just use the JSON object!
if (auto [rc, doc] = cc.create(dbName, collectionName,
{{"id", docId}, // We send the JSON document
{"ttl", 360}, // inline for this example
{"__pk", pkId}, // PKID is required
{"func", __func__},
{"source", "basic_tests.exe"}});
201 == rc)
{
// ...do something
// ...useful with doc..
// Remove the just created document..
auto [rcd, _] = cc.remove(dbName, collectionName, doc.value("id", docId), pkId);
}
}
Roadmap
- Documentation
- Async operations with auto-retry (follow the read/write locations and toggle primary/secondary)
- Support C++20 modules
- Co-routines
- OpenSSL for non-Windows platforms (current implementation is Windows only)
<p align="right"> © 2021 Siddiq Software LLC. All rights reserved. </p>
Product | Versions Compatible and additional computed target framework versions. |
---|---|
native | native is compatible. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
- nlohmann.json (>= 3.10.0)
- SiddiqSoft.asynchrony-lib (>= 0.9.0)
- SiddiqSoft.AzureCppUtils (>= 1.2.0)
- SiddiqSoft.format-helpers (>= 1.0.3)
- SiddiqSoft.restcl (>= 0.9.0)
- SiddiqSoft.TimeThis (>= 1.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.7.14 | 1,306 | 12/23/2021 |
0.7.13 | 1,221 | 12/21/2021 |
0.7.12 | 1,344 | 12/20/2021 |
0.7.11 | 1,359 | 12/20/2021 |
0.7.10 | 1,433 | 12/18/2021 |
0.7.9 | 1,321 | 12/15/2021 |
0.7.8 | 1,644 | 11/20/2021 |
0.7.7 | 1,492 | 10/11/2021 |
0.7.6 | 1,172 | 10/8/2021 |
0.7.5 | 1,401 | 10/7/2021 |
0.7.4 | 1,458 | 10/5/2021 |
0.7.3 | 1,412 | 10/5/2021 |
0.7.2 | 1,462 | 9/28/2021 |
0.7.2-pullrequest0008-0005 | 1,318 | 9/28/2021 |
0.7.1 | 1,479 | 9/26/2021 |
0.6.1-pullrequest0007-0006 | 1,340 | 9/23/2021 |
0.6.1-pullrequest0007-0005 | 1,313 | 9/23/2021 |
0.6.0 | 1,518 | 9/11/2021 |
0.6.0-pullrequest0006-0088 | 1,247 | 9/11/2021 |
0.6.0-alpha0087 | 1,413 | 9/11/2021 |
0.5.7 | 1,381 | 9/11/2021 |
0.5.6 | 1,484 | 9/6/2021 |
0.5.3 | 1,394 | 9/3/2021 |
0.5.2 | 1,436 | 9/3/2021 |
0.5.1 | 1,516 | 9/3/2021 |
0.5.0 | 1,414 | 9/2/2021 |
0.4.2 | 1,638 | 9/1/2021 |
Documentation is over at https://siddiqsoft.github.io/CosmosClient/