updated readme

Author: yorek

README.md

@@ -1,14 +1,22 @@
 ---
 page_type: sample
 languages:
-- csharp
+- tsql
+- sql
 products:
-- dotnet
-description: "Add 150 character max description"
-urlFragment: "update-this-to-unique-url-stub"
+- azure
+- donet
+- aspnet
+= dotnet-core
+- aspnet-core
+- azure-api-apps
+- vs-code
+- azure-sql-database
+description: "Creating a modern REST API with .NET Core and Azure SQL, using Dapper and Visual Studio Code"
+urlFragment: "azure-sql-db-python-rest-api"
 ---
 
-# Official Microsoft Sample
+# Creating a REST API with .NET Core and Azure SQL
 
 <!-- 
 Guidelines on README format: https://review.docs.microsoft.com/help/onboard/admin/samples/concepts/readme-template?branch=master
@@ -18,36 +26,122 @@ Guidance on onboarding samples to docs.microsoft.com/samples: https://review.doc
 Taxonomies for products and languages: https://review.docs.microsoft.com/new-hope/information-architecture/metadata/taxonomies?branch=master
 -->
 
-Give a short description for your sample here. What does it do and why is it important?
+Thanks to native JSON support, creating a REST API with Azure SQL and .NET Core is really a matter of a few lines of code. Take a look at `app.py` to easy it is!
 
-## Contents
+Wondering what's the magic behind? The sample uses the well known [Flask](https://flask.palletsprojects.com/en/1.1.x/) micro-framework and the [flask-restful](https://flask-restful.readthedocs.io/en/latest/) package to easily implement REST APIs. Beside that the [native JSON support that Azure SQL provides](https://docs.microsoft.com/en-us/azure/sql-database/sql-database-json-features) does all the heavy lifting so sending data back and forth to the database is as easy as sending a JSON message.
 
-Outline the file contents of the repository. It helps users navigate the codebase, build configuration and any related assets.
+## Install Sample Database
 
-| File/folder       | Description                                |
-|-------------------|--------------------------------------------|
-| `src`             | Sample source code.                        |
-| `.gitignore`      | Define what to ignore at commit time.      |
-| `CHANGELOG.md`    | List of changes to the sample.             |
-| `CONTRIBUTING.md` | Guidelines for contributing to the sample. |
-| `README.md`       | This README file.                          |
-| `LICENSE`         | The license for the sample.                |
+In order to run this sample, the WideWorldImporters database is needed. Install WideWorldImporters sample database:
 
-## Prerequisites
+[Restore WideWorldImporters Database](https://github.com/yorek/azure-sql-db-samples#restore-wideworldimporters-database)
 
-Outline the required components and tools that a user might need to have on their machine in order to run the sample. This can be anything from frameworks, SDKs, OS versions or IDE releases.
+## Add Database Objects
 
-## Setup
+Once the sample database has been installed, you need to add some stored procedure that will called from Python. The SQL code is available here:
 
-Explain how to prepare the sample once the user clones or downloads the repository. The section should outline every step necessary to install dependencies and set up any settings (for example, API keys and output folders).
+`./SQL/WideWorldImportersUpdates.sql`
 
-## Running the sample
+If you need any help in executing the SQL script, you can find a Quickstart here: [Quickstart: Use Azure Data Studio to connect and query Azure SQL database](https://docs.microsoft.com/en-us/sql/azure-data-studio/quickstart-sql-database)
 
-Outline step-by-step instructions to execute the sample and see its output. Include steps for executing the sample from the IDE, starting specific services in the Azure portal or anything related to the overall launch of the code.
+## Run sample locally
 
-## Key concepts
+Make sure you have [.NET Core 3.0](https://dotnet.microsoft.com/download) SDK installed on your machine. Clone this repo in a directory on our computer and then configure the connection string in `appsettings.json`.
 
-Provide users with more context on the tools and services used in the sample. Explain some of the code that is being used and how services interact with each other.
+If you don't want to save the connection string in the `appsettings.json` file for security reasons, you can just set it using an environment variable:
+
+Linux:
+
+```bash
+export ConnectionStrings__DefaultConnection="<your-connection-string>"
+```
+
+Windows:
+
+```powershell
+$Env:ConnectionStrings__DefaultConnection="<your-connection-string>"
+```
+
+Your connection string is something like:
+
+```
+DRIVER={ODBC Driver 17 for SQL Server};SERVER=<your-server-name>.database.windows.net;DATABASE=<your-database-name>;UID=DotNetWebApp;PWD=a987REALLY#$%TRONGpa44w0rd
+```
+
+Just replace `<your-server-name>` and `<your-database-name>` with the correct values for your environment.
+
+To run and test the REST API locally, just run
+
+```bash
+dotnet run
+```
+
+.NET will start the HTTP server and when everything is up and running you'll see something like
+
+```text
+Now listening on: https://localhost:5001
+```
+
+Using a REST Client (like [Insomnia](https://insomnia.rest/), [Postman](https://www.getpostman.com/) or curl), you can now call your API, for example:
+
+```bash
+curl -k -X GET http://localhosts:5001/customer/123
+```
+
+and you'll get info on Customer 123:
+
+```json
+[
+    {
+        "CustomerID": 123,
+        "CustomerName": "Tailspin Toys (Roe Park, NY)",
+        "PhoneNumber": "(212) 555-0100",
+        "FaxNumber": "(212) 555-0101",
+        "WebsiteURL": "http://www.tailspintoys.com/RoePark",
+        "Delivery": {
+            "AddressLine1": "Shop 219",
+            "AddressLine2": "528 Persson Road",
+            "PostalCode": "90775"
+        }
+    }
+]
+```
+
+Check out more samples to test all implemented verbs here:
+
+[cUrl Samples](./Sample-Usage.md)
+
+## Deploy to Azure
+
+Now that your REST API solution is ready, it's time to deploy it on Azure so that anyone can take advantage of it. A detailed article on how you can that that is here:
+
+- [Deploying Python web apps to Azure App Services](https://medium.com/@GeekTrainer/deploying-python-web-apps-to-azure-app-services-413cc16d4d68)
+- [Quickstart: Create a Python app in Azure App Service on Linux](https://docs.microsoft.com/en-us/azure/app-service/containers/quickstart-python?tabs=bash)
+
+The only thing you have do in addition to what explained in the above articles is to add the connection string to the Azure Web App configuration. Using AZ CLI, for example:
+
+```bash
+appName="azure-sql-db-dotnet-rest-api"
+resourceGroup="my-resource-group"
+
+az webapp config connection-string set \
+    -g $resourceGroup \
+    -n $appName \
+    --settings DefaultConnection=$ConnectionStrings__DefaultConnection \
+    --connection-string-type=SQLAzure
+```
+
+Just make sure you correctly set `$appName` and `$resourceGroup` to match your environment and also that the variable `$ConnectionStrings__DefaultConnection` as also been set, as mentioned in section "Run sample locally". An example of a full script that deploy the REST API is available here: `azure-deploy.sh`.
+
+## Learn more
+
+If you're new to .NET and want to learn more, there are a lot of tutorial available on the [Microsoft Learn](https://docs.microsoft.com/en-us/learn/browse/?products=dotnet) platform. You can start from here, for example:
+
+- https://docs.microsoft.com/en-us/learn/modules/build-web-api-net-core/?view=aspnetcore-3.1
+
+If you also want to learn more about Visual Studio Code, here's another resource:
+
+[Using .NET Core in Visual Studio Code](https://code.visualstudio.com/docs/languages/dotnet)
 
 ## Contributing