Exercise - Create .NET app and reference SDK

  • 7 minutes

As the first step to creating your project's application, you need to create a .NET project. Recall that the .NET project should use the Microsoft.Azure.Cosmos SDK to connect to the account you already created. There are three key requirements at this time:

  • Create a .NET project
  • Add a package reference to the SDK
  • Connect using the client classes

Illustration of icons of an Azure Cosmos DB account and .NET application.

After you complete this exercise, you'll have a simple .NET application that successfully connects to your API for NoSQL account, but doesn't perform any operations yet.

Create a .NET console project

The .NET CLI creates and manages .NET projects within a specified directory. Here, you use the CLI to create a new console application and add a package reference to the SDK.

  1. Create a new console application in the current directory.

    dotnet new console

    Tip

    Since you did not specify a project name or a directory, the command will create the new project in the current directory and name the project to match the directory's name (inventory).

  2. Add a package reference to version 3 of the Microsoft.Azure.Cosmos SDK from NuGet.

    dotnet add package Microsoft.Azure.Cosmos --version 3.*

  3. Build the .NET project to ensure you correctly configured your project.

    dotnet build

    The output of the command should be similar to this example:

    MSBuild version 17.5.0+6f08c67f3 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  dotnet-env-azure-cosmos-db -> /workspaces/dotnet-env-azure-cosmos-db/bin/Debug/net7.0/dotnet-env-azure-cosmos-db.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:05.96

Connect to the account

Now, the .NET project should be built and ready for you to add your own custom code. You have access to the Microsoft.Azure.Cosmos namespace and all of the classes necessary to connect to the API for NoSQL. Here, you open the Program.cs file and implement code to connect to the account using the client classes of the SDK.

  1. Open the Program.cs file within the code editor.

  2. Delete all existing code from the file.

  3. Add using directives for the following namespaces:

    using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Fluent;
using Microsoft.Azure.Cosmos.Linq;

  4. Create a constant string variable named connectionString. Set the value of the variable to the connection string you recorded earlier in this module.

    const string connectionString = "<your-azure-cosmos-db-connection-string>";

    Tip

    Assuming the name of the Azure Cosmos DB account is nybncrsna76fo-cosmos-nosql and the key is Aj2OSQqWhXfFzkITIi4MIbocWAAoBCUWnSPzHlQbDYA3TiyZCJlk8A6R1l6WqD45BxAG5vrsyQ4SCXEkPS1pLh==, you would configure the connection string like this example:

    const string connectionString = "AccountEndpoint=https://nybncrsna76fo-cosmos-nosql.documents.azure.com:443/;AccountKey=Aj2OSQqWhXfFzkITIi4MIbocWAAoBCUWnSPzHlQbDYA3TiyZCJlk8A6R1l6WqD45BxAG5vrsyQ4SCXEkPS1pLh==;";

  5. Print the connection string to the console.

    Console.WriteLine($"[Connection string]:\t{connectionString}");

  6. Create a new instance of the CosmosSerializationOptions class named serializerOptions. Set the PropertyNamingPolicy property to the value CamelCase from the CamelCase enumeration.

    CosmosSerializationOptions serializerOptions = new()
{
    PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
};

  7. Create a new instance of the CosmosClientBuilder class by passing in the connection string to the constructor. Next, chain the WithSerializerOptions(CosmosSerializationOptions) fluent method and set this method's parameter to serializerOptions. Chain the Build() method to create an instance of type CosmosClient named client. Finally, wrap the creation of the client variable with a using statement.

    using CosmosClient client = new CosmosClientBuilder(connectionString)
    .WithSerializerOptions(serializerOptions)
    .Build();

  8. Print a message indicating that your client is ready.

    Console.WriteLine("[Client ready]");

  9. Save the Program.cs file.

Check your work

The application is now ready to run and connect to Azure Cosmos DB for NoSQL. Here, you compare your application code to our sample. Then, you check that your application works as expected by running the code.

  1. Run the .NET application in the terminal

    dotnet run

  2. Observe the output of running the application. The output should match the example here.

    [Connection string]:    <your-azure-cosmos-db-connection-string>
[Client ready]

Note

If building or running the .NET application results in an error, go to the Review code tab to validate that your code matches the example.