- Install .NET 6.0 SDK for your specific platform. (or a higher version within the 6.0.*** band) (https://dotnet.microsoft.com/download/dotnet-core/6.0)
- Install the latest version of git (https://git-scm.com/downloads)
- Install the Azure Cosmos DB Emulator
You can choose to use any IDE compatible with .NET development, such as:
- Visual Studio - any of the versions, including the free Community version.
- Visual Studio Code.
Azure Cosmos DB SDKs are thick constructs that contain several layers:
- Public APIs
- Retry policies
- Processing pipeline
- Transport (HTTP or Direct). More information see the connectivity modes documentation
Make sure you are familiar with:
- Azure SDK Guidelines
- Best practices for Azure Cosmos DB .NET SDK
- Designing resilient applications with Azure Cosmos DB SDKs
The following image shows the hierarchy of different entities in an Azure Cosmos account:
CosmosClient is the client:
- Working with Azure Cosmos databases. They include creating and listing through the
Databasetype. - Obtaining the Azure Cosmos account information.
A database is the unit of management for a set of Azure Cosmos containers. It maps to the Database class and supports:
- Working with Azure Cosmos containers. They include creating, modifying, deleting, and listing through the
Containertype. - Working with Azure Cosmos users. Users define access scope and permissions. They include creating, modifying, deleting, and listing through the
Usertype.
An Azure Cosmos container is the unit of scalability both for provisioned throughput and storage. A container is horizontally partitioned and then replicated across multiple regions. It maps to the Container class and supports:
- Working with items. Items are the conceptually the user's data. They include creating, modifying, deleting, and listing (including query) items.
- Working with scripts. Scripts are defined as Stored Procedures, User Defined Functions, and Triggers.
For more details visit [here][https://docs.microsoft.com/azure/cosmos-db/databases-containers-items].
The SDK currently depends on:
Microsoft.Azure.Cosmos.Direct- This package contains the Direct transport protocol and ServiceInterop DLLs.Microsoft.HybridRow- This package contains the HybridRow protocol used to transmit data for Batch requests.
Microsoft.Azure.Cosmoscontains the SDK and its tests:Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Testscontains the Unit tests project.Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.EmulatorTestscontains the Emulator/Integration tests project.Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Performance.Testscontains the micro benchmark tests project.Microsoft.Azure.Cosmos/srccontains the SDK source code and theMicrosoft.Azure.Cosmos.csprojproject.
Microsoft.Azure.Cosmos.Samplescontains samples and tools:Microsoft.Azure.Cosmos.Samples/Usagecontains sample applications for multiple scenarios. Here is where we keep our public samples for users to consume.Microsoft.Azure.Cosmos.Samples/Toolscontains tools such as the CTL runner and Benchmark runner.
Microsoft.Azure.Cosmos.EncryptionandMicrosoft.Azure.Cosmos.Encryption.Customare exclusively related to the Encryption libraries that leverage the SDK.
If you are working with Visual Studio, opening the Microsoft.Azure.Cosmos.sln file is the quickest way to build and work with the SDK.
Alternatively, you can build from the command line using the .NET tooling with dotnet build Microsoft.Azure.Cosmos.sln on the root of this repository or access the Microsoft.Azure.Cosmos/src/Microsoft.Azure.Cosmos.csproj project on the folder structure and build just the SDK source code like dotnet build .\Microsoft.Azure.Cosmos\src\Microsoft.Azure.Cosmos.csproj.
There are two major test projects:
Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Testscontains Unit tests. Any new feature or work should add unit tests covering unless explicitly allowed due to some exceptional circumstance. Unit tests should be isolated and do not depend on any endpoint or Emulator.Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.EmulatorTestscontains Emulator tests. This tests will automatically connect to a running Azure Cosmos DB Emulator (see prerequisites). Any new feature or work should have Emulator tests if the feature is interacting with the service.
All test projects can be interacted with through an IDE (some IDEs like Visual Studio have a Test Explorer to easily navigate through tests) but it can also be executed through the dotnet test command in any of the above folders.
When evaluating adding new tests, please search in the existing test files if there is already a test file for the scenario or feature you are working on.