- 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.
- Create a branch for your contribution (if you are an external contributor, on your own fork).
- Make sure your work is adding tests as required (either unit and/or emulator tests depending on the scope of the work).
- Send a Pull Request to the master branch once your work is ready to be reviewed.
- The CI pipeline will start any required tests. If you are an external contributor, a team member will start the verification once we confirm the nature of the contribution through a
/azp runcomment in your Pull Request. - Look for review comments and attempt to answer/address them to the best of your ability.
- Check for test failures and address them if they are not transient.
- Review the Checks section to confirm there are no pending steps that might be blocking your work from merging.
If the Pull Request is experiencing test failures, these will appear as failed checks:
Clicking on Details will take you to the Checks section. Each failed check will contain a link to View more details on Azure Pipelines:
Which takes you to the pipeline run. Clicking on the run number will take you to the run Overview:
And you can see which Tests failed during that check and click on the individual test to see the error message:
In some cases, the failures are unrelated to your changes and might result from a transient issue on the test environment. On the Checks section, you can decide to Re-run the tests individually:
Or all through Re-run failed checks on the top right corner:
-
- The same version of the emulator used in the CI pipelines can be downloaded here
- More information about how ro use the emulator for development is documented here
- You can start the emulator with same parameters as the emulator unit tests in the CI pipeline via
.\CosmosDB.Emulator.exe /DisableRateLimiting /PartitionCount=100 /Consistency=Strong /enableRio /EnablePreview /EnableAadAuthentication /EnableSqlComputeEndpoint