Azure China developer guide

There are tools and documents to help developers create and deploy cloud applications to Microsoft Azure operated by 21Vianet (Azure China). Most of the currently available technical content, such as the global Azure documentation, assumes that applications are being developed for Azure global. Azure Docs for China (in Chinese) supplies technical content adapted for Azure China. For services available in Azure China, see Service availability and roadmaps of Azure China.

When referring to publicly available content for Azure global services, make sure to adapt the steps or customize any sample code that specifies settings for Azure global services. For example, customize the Azure service endpoints.

Develop for Azure users

If you’re accustomed to developing cloud services for users in other regions, make sure you consider the following user expectations in China:

  • Mobile first: Mobile devices, not PCs, are considered the source of the online world. Make sure your design strategy is mobile-centric.
  • QR codes and screen-scanning behavior: Websites, print ads, business cards, and other media commonly include QR codes. Include QR codes in your website header and footer, so visitors can quickly load the site’s mobile version on their phones.
  • Content localization: Localizing is more than just translating content. Take time to understand the digital environment of your target market and the cultural ramifications of your business decisions. Then tailor your content accordingly.

Use social sites and media services in China

Commonly used western social media sites and services may be blocked in China. When operating a web presence in China:

  • Avoid connecting to Google services on your website’s front end. Google, along with all of its services, is blocked in China. For best results, your site might need to avoid using Google services. For example, replace Google Maps with Baidu Maps, and use self-hosted fonts instead of Google fonts.
  • Don't embed videos from YouTube or Vimeo. Both services are blocked in China. Host your video locally or on Chinese video hosting sites, such as Youku, Qiyi, Tudou, or use Azure Media Services. Optimize your site for Baidu, the most frequently used search engine in China, by using a search engine optimization (SEO) audit tool.
  • Create a China-specific social network presence. Globally popular social networks, such as Facebook, Twitter, and Instagram, are blocked. Create a social marketing strategy specifically tailored for the social networks in China, such as WeChat and Sina Weibo. Azure doesn’t currently offer local social network integration (that is, a social identity provider).

Check endpoints in Azure

Azure China differs from Azure global, so any Azure service endpoints from Azure global sources, such sample code or published documentation, must be changed.

The following table shows the endpoints to change.

See also:

Service category Azure global URI Azure URI (in China)
Azure (in general) *.windows.net *.chinacloudapi.cn
Azure App Configuration *.azconfig.io *.azconfig.azure.cn
Azure compute *.cloudapp.net *.chinacloudapp.cn
Azure storage *.blob.core.windows.net *.queue.core.windows.net *.table.core.windows.net *.blob.core.chinacloudapi.cn *.queue.core.chinacloudapi.cn *.table.core.chinacloudapi.cn
Azure service management https://management.core.windows.net https://management.core.chinacloudapi.cn
Azure Resource Manager https://management.azure.com https://management.chinacloudapi.cn
Azure portal https://portal.azure.com https://portal.azure.cn
SQL Database *.database.windows.net *.database.chinacloudapi.cn
SQL Azure DB management API https://management.database.windows.net https://management.database.chinacloudapi.cn
Azure Service Bus *.servicebus.windows.net *.servicebus.chinacloudapi.cn
Azure SignalR Service *.service.signalr.net *.signalr.azure.cn
Azure Time Series Insights *.timeseries.azure.com *.insights.timeseries.azure.cn *.timeseries.azure.cn *.insights.timeseries.azure.cn
Azure Access Control Service *.accesscontrol.windows.net *.accesscontrol.chinacloudapi.cn
Azure HDInsight *.azurehdinsight.net *.azurehdinsight.cn
SQL DB import/export service endpoint  1. China East https://sh1prod-dacsvc.chinacloudapp.cn/dacwebservice.svc
2. China North https://bj1prod-dacsvc.chinacloudapp.cn/dacwebservice.svc
MySQL PaaS *.mysqldb.chinacloudapi.cn
Azure Service Fabric cluster *.cloudapp.azure.com *.chinaeast.chinacloudapp.cn
Azure Active Directory (Azure AD) *.onmicrosoft.com *.partner.onmschina.cn
Azure AD logon https://login.microsoftonline.com https://login.partner.microsoftonline.cn
Azure AD Graph API https://graph.windows.net https://graph.chinacloudapi.cn
Microsoft Graph https://graph.microsoft.com https://microsoftgraph.chinacloudapi.cn
Azure Cognitive Services https://api.projectoxford.ai/face/v1.0 https://api.cognitive.azure.cn/face/v1.0
Azure Key Vault API *.vault.azure.net *.vault.azure.cn
Sign in with PowerShell:
- Azure classic portal
- Azure Resource Manager
- Azure AD
- Add-AzureAccount
- Connect-AzureRmAccount
- Connect-msolservice
 - Add-AzureAccount -Environment AzureChinaCloud
- Connect-AzureRmAccount -Environment AzureChinaCloud
- Connect-msolservice -AzureEnvironment AzureChinaCloud

Application Insights

Note

Codeless agent/extension based monitoring for Azure App Services is currently not supported. Snapshot Debugger is also not currently available.

SDK endpoint modifications

In order to send data from Application Insights in this region, you will need to modify the default endpoint addresses that are used by the Application Insights SDKs. Each SDK requires slightly different modifications.

.NET with applicationinsights.config

<ApplicationInsights>
  ...
  <TelemetryModules>
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryModule, Microsoft.AI.PerfCounterCollector">
      <QuickPulseServiceEndpoint>https://quickpulse.applicationinsights.azure.cn/QuickPulseService.svc</QuickPulseServiceEndpoint>
    </Add>
  </TelemetryModules>
    ...
  <TelemetryChannel>
     <EndpointAddress>https://dc.applicationinsights.azure.cn/v2/track</EndpointAddress>
  </TelemetryChannel>
  ...
  <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
    <ProfileQueryEndpoint>https://dc.applicationinsights.azure.cn/api/profiles/{0}/appId</ProfileQueryEndpoint>
  </ApplicationIdProvider>
  ...
</ApplicationInsights>

.NET Core

Modify the appsettings.json file in your project as follows to adjust the main endpoint:

"ApplicationInsights": {
    "InstrumentationKey": "instrumentationkey",
    "TelemetryChannel": {
      "EndpointAddress": "https://dc.applicationinsights.azure.cn/v2/track"
    }
  }

The values for Live Metrics and the Profile Query Endpoint can only be set via code. To override the default values for all endpoint values via code, make the following changes in the ConfigureServices method of the Startup.cs file:

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse; //place at top of Startup.cs file

   services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) => module.QuickPulseServiceEndpoint="https://quickpulse.applicationinsights.azure.cn/QuickPulseService.svc");

   services.AddSingleton(new ApplicationInsightsApplicationIdProvider() { ProfileQueryEndpoint = "https://dc.applicationinsights.azure.cn/api/profiles/{0}/appId" }); 

   services.AddSingleton<ITelemetryChannel>(new ServerTelemetryChannel() { EndpointAddress = "https://dc.applicationinsights.azure.cn/v2/track" });

    //place in ConfigureServices method. If present, place this prior to   services.AddApplicationInsightsTelemetry("instrumentation key");

Java

Modify the applicationinsights.xml file to change the default endpoint address.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
  <InstrumentationKey>ffffeeee-dddd-cccc-bbbb-aaaa99998888</InstrumentationKey>
  <TelemetryModules>
    <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebRequestTrackingTelemetryModule"/>
    <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebSessionTrackingTelemetryModule"/>
    <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebUserTrackingTelemetryModule"/>
  </TelemetryModules>
  <TelemetryInitializers>
    <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationIdTelemetryInitializer"/>
    <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationNameTelemetryInitializer"/>
    <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebSessionTelemetryInitializer"/>
    <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserTelemetryInitializer"/>
    <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserAgentTelemetryInitializer"/>
  </TelemetryInitializers>
  <!--Add the following Channel value to modify the Endpoint address-->
  <Channel type="com.microsoft.applicationinsights.channel.concrete.inprocess.InProcessTelemetryChannel">
  <EndpointAddress>https://dc.applicationinsights.azure.cn/v2/track</EndpointAddress>
  </Channel>
</ApplicationInsights>

Spring Boot

Modify the application.properties file and add:

azure.application-insights.channel.in-process.endpoint-address= https://dc.applicationinsights.azure.cn/v2/track

Node.js

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY');
appInsights.defaultClient.config.endpointUrl = "https://dc.applicationinsights.azure.cn/v2/track"; // ingestion
appInsights.defaultClient.config.profileQueryEndpoint = "https://dc.applicationinsights.azure.cn/api/profiles/{0}/appId"; // appid/profile lookup
appInsights.defaultClient.config.quickPulseHost = "https://quickpulse.applicationinsights.azure.cn/QuickPulseService.svc"; //live metrics
appInsights.Configuration.start();

The endpoints can also be configured through environment variables:

Instrumentation Key: “APPINSIGHTS_INSTRUMENTATIONKEY”
Profile Endpoint: “https://dc.applicationinsights.azure.cn/api/profiles/{0}/appId”
Live Metrics Endpoint: "https://quickpulse.applicationinsights.azure.cn/QuickPulseService.svc"

JavaScript

<script type="text/javascript">
var sdkInstance="appInsightsSDK";window[sdkInstance]="appInsights";var aiName=window[sdkInstance],aisdk=window[aiName]||function(e){function n(e){i[e]=function(){var n=arguments;i.queue.push(function(){i[e].apply(i,n)})}}var i={config:e};i.initialize=!0;var a=document,t=window;setTimeout(function(){var n=a.createElement("script");n.src=e.url||"https://az416426.vo.msecnd.net/next/ai.2.min.js",a.getElementsByTagName("script")[0].parentNode.appendChild(n)});try{i.cookie=a.cookie}catch(e){}i.queue=[],i.version=2;for(var r=["Event","PageView","Exception","Trace","DependencyData","Metric","PageViewPerformance"];r.length;)n("track"+r.pop());n("startTrackPage"),n("stopTrackPage");var o="Track"+r[0];if(n("start"+o),n("stop"+o),!(!0===e.disableExceptionTracking||e.extensionConfig&&e.extensionConfig.ApplicationInsightsAnalytics&&!0===e.extensionConfig.ApplicationInsightsAnalytics.disableExceptionTracking)){n("_"+(r="onerror"));var s=t[r];t[r]=function(e,n,a,t,o){var c=s&&s(e,n,a,t,o);return!0!==c&&i["_"+r]({message:e,url:n,lineNumber:a,columnNumber:t,error:o}),c},e.autoExceptionInstrumented=!0}return i}
(
	{
	instrumentationKey:"INSTRUMENTATION_KEY",
	endpointUrl: "https://dc.applicationinsights.azure.cn/v2/track"
  }
);
window[aiName]=aisdk,aisdk.queue&&0===aisdk.queue.length&&aisdk.trackPageView({});
</script>

Next steps