First commit of C# notebook docs

Author: deborahc

articles/cosmos-db/cosmosdb-jupyter-notebooks.md

@@ -3,58 +3,60 @@ title: Introduction to the built-in Jupyter notebooks support in Azure Cosmos DB
 description: Learn how you can use the built-in Jupyter notebooks support in Azure Cosmos DB to interactively run queries.
 ms.service: cosmos-db
 ms.topic: overview 
-ms.date: 09/22/2019
-author: markjbrown
-ms.author: mjbrown
+ms.date: 05/19/2020
+author: deborahc
+ms.author: dech
 ---
 
 # Built-in Jupyter notebooks support in Azure Cosmos DB (preview)
 
-Jupyter notebook is an open-source web application that allows you to create and share documents containing live code, equations, visualizations, and narrative text. Azure Cosmos DB supports built-in Jupyter notebooks for all APIs such as Cassandra, MongoDB, SQL, Gremlin, and Table. The built-in notebook support for all Azure Cosmos DB APIs and data models allows you to interactively run queries. The Jupyter notebooks run within the Azure Cosmos accounts and they enable developers to perform data exploration, data cleaning, data transformations, numerical simulations, statistical modeling, data visualization, and machine learning.
+Jupyter notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations, and narrative text. 
+
+Azure Cosmos DB built-in Jupyter notebooks are directly integrated into the Azure portal and your Azure Cosmos DB accounts, making them convenient and easy to use. Developers, data scientists, engineers, and analysts can use the familiar Jupyter notebooks experience to do data exploration, data cleaning, data transformations, numerical simulations, statistical modeling, data visualization, and machine learning.
 
 ![Jupyter notebooks visualizations in Azure Cosmos DB](./media/cosmosdb-jupyter-notebooks/cosmos-notebooks-overview.png)
 
-The Jupyter notebooks supports magic functions that extend the capabilities of the kernel by supporting additional commands. Cosmos magic is a command that extends the capabilities of the Python kernel in Jupyter notebook so you can run Azure Cosmos SQL API queries in addition to Apache Spark. You can easily combine Python and SQL API queries to query and visualize data by using rich visualization libraries integrated with render commands.
-Azure portal natively integrates Jupyter notebook experience into Azure Cosmos accounts as shown in the following image:
+Azure Cosmos DB supports both C# and Python notebooks for all APIs, including Core (SQL), Cassandra, Gremlin, Table, and API for MongoDB. Inside the notebook, you can take advantage of built-in commands and features that make it easy to create Azure Cosmos DB resources, upload data, and query and visualize your data in Azure Cosmos DB. 
 
 ![Jupyter notebooks support in Azure Cosmos DB](./media/cosmosdb-jupyter-notebooks/jupyter-notebooks-portal.png)
 
 ## Benefits of Jupyter notebooks
 
-Jupyter notebooks were originally developed for data science applications written in Python, R. However, they can be used in various ways for different kinds of projects such as:
+Jupyter notebooks were originally developed for data science applications written in Python and R. However, they can be used in various ways for different kinds of projects, including:
 
-* ***Data visualizations:** Jupyter notebooks allow you to visualize data in the form of a shared notebook that renders some data set as a graphic. Jupyter notebook lets you author visualizations, share them, and allow interactive changes to the shared code and data set.
+* ***Data visualization:** Jupyter notebooks allow you to visualize data in the form of a shared notebook that renders a data set as a graphic. You can create visualizations, make interactive changes to the shared code and data set, and share the results.
 
-* **Code sharing:** Services like GitHub provide ways to share code, but they’re largely non-interactive. With a Jupyter notebook, you can view code, execute it, and display the results directly in the Azure portal.
+* **Code sharing:** Services like GitHub provide ways to share code, but they're largely non-interactive. With a Jupyter notebook, you can view code, execute it, and display the results directly in the Azure portal.
 
-* **Live interactions with code:** Jupyter notebook code is dynamic; it can be edited and re-run incrementally in real time. Notebooks can also embed user controls (e.g., sliders or text input fields) that can be used as input sources for code, demos or Proof of Concepts(POCs).
+* **Live interactions with code:** Code in a Jupyter notebook is dynamic; it can be edited and rerun incrementally in real time. You can also embed user controls (for example, sliders or text input fields) that can be used as input sources for code, demos, or Proof of Concepts (POCs).
 
-* **Documentation of code samples and outcomes of data exploration:** If you have a piece of code and you want to explain line-by-line how it works in Azure Cosmos DB, with real-time output all along the way, you could embed it in a Jupyter Notebook. The code will remain fully functional. You can add interactivity along with the documentation at the same time.
+* **Documentation of code samples and outcomes of data exploration:** If you have a piece of code and you want to explain line-by-line how it works, you can embed it in a Jupyter Notebook. You can add interactivity along with the documentation at the same time.
 
-* **Cosmos magic commands:** In Jupyter notebooks, you can use custom magic commands for Azure Cosmos DB to make interactive computing easier. For example, the %%sql magic that allows one to query a Cosmos container using SQL API directly in a notebook.
+* **Built-in commands for Azure Cosmos DB:** Azure Cosmos DB's built-in magic commands make it easy to interact with your account. You can use commands like %%upload and %%sql to upload data into a container and query it using [SQL API syntax](sql-query-getting-started.md), no custom code required.
 
 * **All in one place environment:** Jupyter notebooks combine code, rich text, images, videos, animations, mathematical equations, plots, maps, interactive figures, widgets, and graphical user interfaces into a single document.
 
 ## Components of a Jupyter notebook
 
-Jupyter notebooks can include several types of components, each organized into discrete blocks:
+Jupyter notebooks can include several types of components, each organized into discrete blocks or cells:
 
 * **Text and HTML:** Plain text, or text annotated in the markdown syntax to generate HTML, can be inserted into the document at any point. CSS styling can also be included inline or added to the template used to generate the notebook.
 
-* **Code and output:** Jupyter notebooks support Python code. The results of the executed code appear immediately after the code blocks, and the code blocks can be executed multiple times in any order you like.
+* **Code and output:** Jupyter notebooks support Python and C# code. The results of the executed code appear immediately after the code blocks, and the code blocks can be executed multiple times in any order you like.
 
-* **Visualizations:** Graphics and charts can be generated from the code, using modules like Matplotlib, Plotly, or Bokeh. Similar to the output, these visualizations appear inline next to the code that generates them.
+* **Visualizations:** Graphics and charts can be generated from the code, using modules like Matplotlib, Plotly, Bokeh, and others. Similar to the output, these visualizations appear inline next to the code that generates them.
 
 * **Multimedia:** Because Jupyter notebook is built on the web technology, it can display all the types of multimedia supported in a web page. You can include them in a notebook as HTML elements, or you can generate them programmatically by using the `IPython.display` module.
 
-* **Data:** Data from Azure Cosmos containers and results of the queries can be imported into a Jupyter notebook programmatically. For example, by including code in the notebook to query the data using any of the Cosmos DB APIs or natively built-in Apache Spark.
+* **Data:** Data from Azure Cosmos containers and results of queries can be imported into a Jupyter notebook programmatically. For example, you can use built-in commands to upload or query data in Azure Cosmos DB. 
 
 ## Next steps
 
-To get started with built-in Jupyter notebooks in Azure Cosmos DB see the following articles:
+To get started with built-in Jupyter notebooks in Azure Cosmos DB, see the following articles:
 
 * [Enable notebooks in an Azure Cosmos account](enable-notebooks.md)
-* [Use notebook features and commands](use-notebook-features-and-commands.md)
+* [Use Python notebook features and commands](use-python-notebook-features-and-commands.md)
+* [Use C# notebook features and commands](use-csharp-notebook-features-and-commands.md)
 
 
 

articles/cosmos-db/media/use-notebook-features-and-commands/csharp-built-in-dictionary-viewer.png

@@ -0,0 +1,160 @@
+---
+title: Use built-in notebook commands and features in Azure Cosmos DB C# notebooks (preview)
+description: Learn how to use built-in commands and features to do common operations using Azure Cosmos DB's built-in C# notebooks.
+author: deborahc
+ms.service: cosmos-db
+ms.topic: conceptual
+ms.date: 05/19/2020
+ms.author: dech
+
+---
+
+# Use built-in notebook commands and features in Azure Cosmos DB C# notebooks (preview)
+
+Built-in Jupyter notebooks in Azure Cosmos DB enable you to analyze and visualize your data from the Azure portal. This article describes how to use built-in notebook commands and features to do common operations in C# notebooks.
+
+## Install a new NuGet package
+After you enable notebook support for your Azure Cosmos accounts, you can open a new notebook and install a package.
+
+In a new code cell, insert and run the following code, replacing ``PackageToBeInstalled`` with the desired NuGet package, and ``optionalVersion`` with a specific version of the package if desired. 
+
+```csharp
+#r "nuget: PackageToBeInstalled, optionalVersion"
+```
+You can install multiple NuGet packages in the same cell. Packages will be available to use from any notebook in the Azure Cosmos account workspace. 
+
+Currently, the C# notebooks workspace does not support recursive resolution of NuGet packages. If a NuGet package has dependencies on other NuGet packages not currently installed, you may have to explicitly reference them along with the parent package.
+
+> [!TIP]
+> If your notebook requires a custom package, we recommend that you add a cell to your notebook to install the package and make it the first cell. This reduces the chance of conflicts with any packages Azure Cosmos DB loads by default. It also makes it easy to re-install them if you [reset the workspace](#reset-notebooks-workspace), which removes all packages. 
+## Use the built-in Azure Cosmos DB .NET SDK
+Version 3 of the [Azure Cosmos DB .NET SDK for SQL API](https://github.com/Azure/azure-cosmos-dotnet-v3) is installed and included in the notebook environment for the Azure Cosmos account.
+
+Create an instance of ``CosmosClient`` to run any SDK operation. 
+
+For example:
+
+```csharp
+// Include usings
+using System;
+using Microsoft.Azure.Cosmos; //namespace for Azure Cosmos DB .NET V3 SDK
+using System.Collections;
+
+// Initialize a new instance of CosmosClient using the built-in account endpoint and key parameters
+CosmosClient cosmosClient = new CosmosClient(Cosmos.Endpoint, Cosmos.Key);
+
+// Create a new database and container with 400 RU/s
+Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync("DatabaseName");
+Container container = await database.CreateContainerIfNotExistsAsync("ContainerName", "/partitionKey", 400);
+```
+See [.NET SDK samples](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage). 
+
+> [!IMPORTANT]
+> The built-in Azure Cosmos DB .NET SDK is only supported for SQL (Core) API accounts. For other APIs, you will need to [install the relevant .NET driver](#install-a-new-nuget-package) that corresponds to the API. 
+
+## Set custom options using ```CosmosClientOptions```
+For more flexibility, you can set custom [``CosmosClientOptions``](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions). You can use this to:
+
+- Set an application name in the user-agent suffix to include in every request 
+- Set the preferred region to be used to operations against the service
+- Set a custom retry policy on rate-limited requests
+
+See the [documentation](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions) for all ``CosmosClientOptions`` settings.
+
+```csharp
+using Microsoft.Azure.Cosmos;
+
+// Configure CosmosClientOptions
+var cosmosClientOptions = new CosmosClientOptions
+{
+    ApplicationName = "ContosoNotebookAppName",
+    ApplicationRegion = Regions.RegionName, // By default, this is the region you first created your account in
+    MaxRetryAttemptsOnRateLimitedRequests = 9, // By default, this value is 9
+};
+
+var client = new CosmosClient(Cosmos.Endpoint, Cosmos.Key, cosmosClientOptions);
+```
+
+## Access the account endpoint and primary key variables
+You can access the built-in endpoint and key of the account your notebook is in.
+
+```csharp
+var key = Cosmos.Key;
+var endpoint = Cosmos.Endpoint;
+```
+
+> [!IMPORTANT]
+> The ``Cosmos.Key`` and ``Cosmos.Endpoint`` variables are only applicable for SQL API. For other APIs, find the endpoint and key in the **Connection Strings** or **Keys** blade in your Azure Cosmos account.  
+
+## Print console output in C# code
+In your C# code, you can use the Display.AsMarkdown() syntax with [string interpolation](/dotnet/csharp/language-reference/tokens/interpolated) to print console output that will appear when you run the cell. 
+
+For example: 
+
+```csharp
+// Print text in the output
+Display.AsMarkdown($"Hello world!");
+
+// Print a variable in the output
+for (int i = 0; i < 5; i++) {
+    Display.AsMarkdown($"Printing out variable: {i}");
+}
+```
+> [!IMPORTANT]
+> Console.WriteLine() syntax is not currently supported in C# notebooks. Use Display.AsMarkdown to print console output from your program. 
+
+## Use built-in nteract data explorer
+You can use the built-in [nteract data explorer](https://blog.nteract.io/designing-the-nteract-data-explorer-f4476d53f897) to filter and visualize a collection of items. In a cell, put the variable you want to visualize in the last line, which will automatically be displayed in nteract when the cell is run.
+
+For example, in the GetingStarted_Csharp.ipynb example, we can print out the variable with our result, the ``telemetryEvents``. See the [GettingStarted_Csharp.ipynb notebook](https://github.com/Azure-Samples/cosmos-notebooks/blob/master/CSharp_quickstarts/GettingStarted_CSharp.ipynb) for the entire sample. 
+
+![Csharp query cell](media/use-notebook-features-and-commands/csharp-query-cell.png)
+
+![nteract data explorer](media/use-notebook-features-and-commands/csharp-nteract-built-in-chart.png)
+
+## Use built-in dictionary viewer
+You can use the built-in dictionary viewer to view a variable. In a cell, put the variable you want to visualize in the last line, which will be automatically displayed when the cell is run.
+
+![Built-in dictionary viewer](media/use-notebook-features-and-commands/csharp-built-in-dictionary-viewer.png)
+
+## Upload JSON items to a container
+You can use the ``%%upload`` magic command to upload data from a JSON file to a specified Azure Cosmos container. Use the following command to upload the items:
+
+```bash
+%%upload --databaseName {database_id} --containerName {container_id} --url {url_location_of_file}
+```
+
+- Replace ``{database_id}`` and ``{container_id}`` with the name of the database and container in your Azure Cosmos account. If the ``--database`` and ``--container`` arguments are not provided, the query will be executed on the [default database and container](#set-default-database-for-queries).
+- Replace ``{url_location_of_file}`` with the location of your JSON file. The file must be an array of valid JSON objects and it should be accessible over the public Internet.
+
+For example:
+
+```bash
+%%upload --database databaseName --container containerName --url 
+https://contoso.com/path/to/data.json
+```
+```bash
+Documents successfully uploaded to ContainerName
+Total number of documents imported : 2654
+Total time taken : 00:00:38.1228087 hours
+Total RUs consumed : 25022.58
+```
+With the output statistics, you can calculate the effective RU/s used to upload the items. For example, if 25,000 RUs were consumed over 38 seconds, the effective RU/s is 25,000 RUs / 38 seconds = 658 RU/s.
+
+## Run another notebook in current notebook 
+You can use the ``%%run`` magic command to run another notebook in your workspace from your current notebook. Use the syntax:
+
+```bash
+%%run ./path/to/{notebookName}.ipynb
+```
+Replace ``{notebookName}`` with the name of the notebook you want to run. The notebook must be in your current 'My Notebooks' workspace. 
+
+## Reset notebooks workspace
+To reset the notebooks workspace to the default settings, select **Reset Workspace** on the command bar. This will remove any custom installed packages and restart the Jupyter server. Your notebooks, files, and Azure Cosmos resources will not be affected.  
+
+![Reset notebooks workspace](media/use-notebook-features-and-commands/reset-workspace.png)
+
+## Next steps
+
+- Learn about the benefits of [Azure Cosmos DB Jupyter notebooks](cosmosdb-jupyter-notebooks.md)
+- Learn about the [Azure Cosmos DB .NET SDK for SQL API](https://github.com/Azure/azure-cosmos-dotnet-v3)