Exercise - Create .NET app and reference SDK

Completed

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

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 library from NuGet.

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

3. Add a package reference to version 1 of the Azure.Identity library from NuGet.

   dotnet add package Azure.Identity --version 1.*
   

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

   dotnet build
   

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

     Determining projects to restore...
     All projects are up-to-date for restore.
   
   Build succeeded.
       0 Warning(s)
       0 Error(s)
   

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 and Azure.Identity namespaces including 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:

   • Azure.Identity
   • Microsoft.Azure.Cosmos
   • Microsoft.Azure.Cosmos.Fluent
   • Microsoft.Azure.Cosmos.Linq

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

4. Create a string variable of type named endpoint. Set the value of the variable to the account's document endpoint you recorded earlier in this module.

   const string endpoint = "<nosql-account-endpoint>";
   

   Tip

   Assuming the name of the Azure Cosmos DB account is mslearn-nosql-000000000, you would configure the endpoint like this example:

   const string endpoint = "https://mslearn-nosql-000000000.documents.azure.com:443/";
   

5. Create a new variable of type DefaultAzureCredential named credential.

   DefaultAzureCredential credential = new();
   

   Tip

   The DefaultAzureCredential token credential object automatically uses your currently logged in account for the Azure CLI to authenticate to the .NET SDK.

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 credential and endpoint 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(endpoint, credential)
       .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.

Run application

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.

   [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.

Review code

1. Review the *.csproj project file to ensure that the project configuration includes both referenced projects.

   <ItemGroup>
     <PackageReference Include="Azure.Identity" Version="1.*" />
     <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.*" />
   </ItemGroup>
   

   Note

   This is a subset of the project configuration XML. The rest of the content was omitted for brevity.

2. Review the Program.cs code file to make sure that your code matches this sample.

   using Azure.Identity;
   using Microsoft.Azure.Cosmos;
   using Microsoft.Azure.Cosmos.Fluent;
   using Microsoft.Azure.Cosmos.Linq;
   
   const string endpoint = "<nosql-account-endpoint>";
   
   DefaultAzureCredential credential = new();
   
   CosmosSerializationOptions serializerOptions = new()
   {
       PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
   };
   
   using CosmosClient client = new CosmosClientBuilder(endpoint, credential)
       .WithSerializerOptions(serializerOptions)
       .Build();
   
   Console.WriteLine("[Client ready]");