{"id":13706410,"url":"https://github.com/Azure-Samples/azure-sql-db-sync-api-change-tracking","last_synced_at":"2025-05-05T20:31:10.471Z","repository":{"id":144908024,"uuid":"242029424","full_name":"Azure-Samples/azure-sql-db-sync-api-change-tracking","owner":"Azure-Samples","description":"Using Azure SQL Change Tracking API to Sync mobile Apps data with the Cloud","archived":false,"fork":false,"pushed_at":"2024-08-06T19:50:48.000Z","size":41,"stargazers_count":63,"open_issues_count":1,"forks_count":22,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-08-06T23:14:02.352Z","etag":null,"topics":["aspnet","azure","azure-sql-database","azuresqldb","change-tracking","disconnected","dotnet","dotnet-core","offline","rest-api","sql","sync"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Azure-Samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-21T01:34:07.000Z","updated_at":"2024-08-06T19:50:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"f12d0468-4621-404a-a449-eb78c8736a80","html_url":"https://github.com/Azure-Samples/azure-sql-db-sync-api-change-tracking","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Fazure-sql-db-sync-api-change-tracking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Fazure-sql-db-sync-api-change-tracking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Fazure-sql-db-sync-api-change-tracking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Fazure-sql-db-sync-api-change-tracking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Azure-Samples","download_url":"https://codeload.github.com/Azure-Samples/azure-sql-db-sync-api-change-tracking/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224465823,"owners_count":17315883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aspnet","azure","azure-sql-database","azuresqldb","change-tracking","disconnected","dotnet","dotnet-core","offline","rest-api","sql","sync"],"created_at":"2024-08-02T22:00:55.435Z","updated_at":"2024-11-13T14:31:00.156Z","avatar_url":"https://github.com/Azure-Samples.png","language":"C#","funding_links":[],"categories":["C# #"],"sub_categories":[],"readme":"---\npage_type: sample\nlanguages:\n- aspx-csharp\n- tsql\n- sql\n- json\nproducts:\n- azure\n- dotnet\n- aspnet\n- aspnet-core\n- azure-app-service\n- vs-code\n- azure-sql-database\ndescription: \"Using Change Tracking API to sync data between Apps and the Cloud\"\nurlFragment: \"azure-sql-db-dotnet-rest-api\"\n---\n\n# Using Change Tracking API to sync data between Apps and the Cloud\n\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n\n\u003c!-- \nGuidelines on README format: https://review.docs.microsoft.com/help/onboard/admin/samples/concepts/readme-template?branch=master\n\nGuidance on onboarding samples to docs.microsoft.com/samples: https://review.docs.microsoft.com/help/onboard/admin/samples/process/onboarding?branch=master\n\nTaxonomies for products and languages: https://review.docs.microsoft.com/new-hope/information-architecture/metadata/taxonomies?branch=master\n--\u003e\n\nIf you are developing an application that must be able to work disconnected from the cloud, you'll surely need, at some point, to implement the ability to download the latest data from the cloud to refresh the data local to the app. Doing this efficiently could be tricky, as you would need to understand what are the changes that happened on the cloud since the last time the application synched with it, so that you can only send the differences.\n\nWith Azure SQL you can take advantage of [Change Tracking](https://docs.microsoft.com/en-us/sql/relational-databases/track-changes/about-change-tracking-sql-server) to detect which rows have been changed from the last time the application synced and generate a payload that only contains those changes. Something like that:\n\n```json\n{\n  \"Metadata\": {\n    \"Sync\": {\n      \"Version\": 6,\n      \"Type\": \"Diff\"\n    }\n  },\n  \"Data\": [\n    {\n      \"$operation\": \"U\",\n      \"Id\": 10,\n      \"RecordedOn\": \"2019-10-27T17:54:48-08:00\",\n      \"Type\": \"Run\",\n      \"Steps\": 3450,\n      \"Distance\": 4981\n    },\n    {\n      \"$operation\": \"I\",\n      \"Id\": 11,\n      \"RecordedOn\": \"2019-10-26T18:24:32-08:00\",\n      \"Type\": \"Run\",\n      \"Steps\": 4866,\n      \"Distance\": 4562\n    }\n  ]\n}\n```\n\nWell, more precisely, not only you can detect the changes, but you can also generate the JSON directly from Azure SQL, so that you can take advantage of the amazing integration that Azure SQL provides across all its features and create a beautifully simple code.\n\nMore technical details are available here: [Sync Mobile Apps with Azure using Change Tracking API ](https://techcommunity.microsoft.com/t5/azure-sql-database/sync-mobile-apps-with-azure-using-change-tracking-api/ba-p/1213993)\n\nI've also prepared a video to show in 10 minutes how much simpler can be your life using Change Tracking API.\n\n![Azure SQL Change Tracking API in Action](https://img.youtube.com/vi/c1BmNruu6wc/0.jpg)](https://www.youtube.com/watch?v=c1BmNruu6wc)\n\n## Create an empty database\n\nMake sure you have an Azure SQL DB database to use. If you don't have an Azure account you, you can create one for free that will also include a free Azure SQL DB tier:\n\nhttps://azure.microsoft.com/en-us/free/free-account-faq/\n\nTo create a new database, follow the instructions here:\n\n[Create Azure SQL Database](https://docs.microsoft.com/en-us/azure/sql-database/sql-database-single-database-get-started?tabs=azure-portal)\n\nor, if you're already comfortable with [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/get-started-with-azure-cli), you can just execute (using Bash, via [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), a Linux environment or [Azure Cloud Shell](https://docs.microsoft.com/en-us/azure/cloud-shell/overview))\n\n```bash\naz group create -n \u003cmy-resource-group\u003e -l WestUS2\naz sql server create -g \u003cmy-resource-group\u003e -n \u003cmy-server-name\u003e -u \u003cmy-user\u003e -p \u003cmy-password\u003e\naz sql db create -g \u003cmy-resource-group\u003e --server \u003cmy-server-name\u003e -n CTSample --service-objective HS_Gen5_2\n```\n\nOnce the database is created, you can connect to it using [Azure Data Studio](https://docs.microsoft.com/en-us/sql/azure-data-studio). If you need help in setting up your first connection to Azure SQL with Azure Data Studio, this quick video will help you:\n\n[How to connect to Azure SQL Database from Azure Data Studio](https://www.youtube.com/watch?v=Td_pYlRraQE)\n\n## Add Database Objects\n\nOnce the database has been created, you need to enable change tracking and add a stored procedure that will called from .NET. The SQL code is available here:\n\n- `./SQL/01-change-tracking-setup.sql`\n- `./SQL/02-stored-procedure.sql`\n\nPlease execute the script on the created database in sequence.\n\nIf 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)\n\n## Run sample locally\n\nMake 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`.\n\nIf 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:\n\nLinux:\n\n```bash\nexport ConnectionStrings__DefaultConnection=\"\u003cyour-connection-string\u003e\"\n```\n\nWindows:\n\n```powershell\n$Env:ConnectionStrings__DefaultConnection=\"\u003cyour-connection-string\u003e\"\n```\n\nYour connection string is something like:\n\n```text\nSERVER=\u003cyour-server-name\u003e.database.windows.net;DATABASE=\u003cyour-database-name\u003e;UID=DotNetWebApp;PWD=a987REALLY#$%TRONGpa44w0rd!\n```\n\nJust replace `\u003cyour-server-name\u003e` and `\u003cyour-database-name\u003e` with the correct values for your environment.\n\nTo run and test the REST API locally, just run\n\n```bash\ndotnet run\n```\n\n.NET will start the HTTP server and when everything is up and running you'll see something like\n\n```text\nNow listening on: https://localhost:5001\n```\n\nUsing a REST Client (such as [Visual Studio](https://learn.microsoft.com/aspnet/core/test/http-files), [Insomnia](https://insomnia.rest/), [Curl](https://curl.se/docs/httpscripting.html) or PowerShell's [Invoke-RestMethod](https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-restmethod))), you can now call your API, for example:\n\n```bash\ncurl -s -k -H \"fromVersion: 0\" --url https://localhost:5001/trainingsession/sync\n```\n\nand you'll get something like the following:\n\n```json\n{\n  \"Metadata\": {\n    \"Sync\": {\n      \"Version\": 6,\n      \"Type\": \"Full\",\n      \"ReasonCode\": 0\n    }\n  },\n  \"Data\": [\n    {\n      \"Id\": 9,\n      \"RecordedOn\": \"2019-10-28T17:27:23-08:00\",\n      \"Type\": \"Run\",\n      \"Steps\": 3784,\n      \"Distance\": 5123\n    },\n    {\n      \"Id\": 10,\n      \"RecordedOn\": \"2019-10-27T17:54:48-08:00\",\n      \"Type\": \"Run\",\n      \"Steps\": 0,\n      \"Distance\": 4981\n    }\n  ]\n}\n```\n\n## Debug from Visual Studio Code\n\nDebugging from Visual Studio Code is fully supported. If you have an `.env`, it will be used to get the connection string: this means, that at minimum the `.env` file needs to be like the following:\n\n```\nConnectionStrings__DefaultConnection=\"\u003cthe-connection-string\u003e\"\n```\n\nThe `.env` file is also used to read values needed to deploy the solution to Azure, as described in the next section.\n\n## Deploy to Azure\n\nNow 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:\n\n- [Create an ASP.NET Core app in App Service on Linux](https://docs.microsoft.com/en-us/azure/app-service/containers/quickstart-dotnetcore)\n\nThe 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:\n\n```bash\nAppName=\"azure-sql-db-dotnet-rest-api\"\nResourceGroup=\"my-resource-group\"\n\naz webapp config connection-string set \\\n    -g $ResourceGroup \\\n    -n $AppName \\\n    --settings DefaultConnection=$ConnectionStrings__DefaultConnection \\\n    --connection-string-type=SQLAzure\n```\n\nJust 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\". \n\nAn example of a full script that deploy the REST API is available here: `azure-deploy.sh`. The script need and `.env` file to run. If there is none it will create an empty one for you. Make sure you to fill it with the correct values for your environment, and you'll be good to go. \n\nThe `.env` file looks like the following:\n\n```\nResourceGroup=\"\u003cresource-group-name\u003e\"\nAppName=\"\u003capp-name\u003e\"\nLocation=\"WestUS2\" \nConnectionStrings__DefaultConnection=\"\u003cthe-connection-string\u003e\"\n```\n\n## Learn more\n\nIf 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:\n\n- https://docs.microsoft.com/en-us/learn/modules/build-web-api-net-core/?view=aspnetcore-3.1\n\nIf you also want to learn more about Visual Studio Code, here's another resource:\n\n[Using .NET Core in Visual Studio Code](https://code.visualstudio.com/docs/languages/dotnet)\n\n## Contributing\n\nThis project welcomes contributions and suggestions.  Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.\n\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAzure-Samples%2Fazure-sql-db-sync-api-change-tracking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAzure-Samples%2Fazure-sql-db-sync-api-change-tracking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAzure-Samples%2Fazure-sql-db-sync-api-change-tracking/lists"}