Deze inhoud is niet beschikbaar in uw taal, maar wel in het Engels.

Developer Notes for Azure in China Applications

Updated: November 19, 2014

In This Section:

Microsoft provides a number of tools to create and deploy cloud applications to Microsoft’s global Windows Azure service (“Global Service”).

Windows Azure in China (“China Service”) is a separate instance of the Windows Azure service operated and provided by a Chinese company, 21Vianet, from data centers located in the People’s Republic of China (excluding Hong Kong, Macau, and Taiwan). Therefore, when creating and deploying applications to as opposed to Global Service, developers need to know the key differences of the two services, when setting up their programming environment, writing applications, and deploying them as services hosted in China.

The information in this document summarizes those differences and supplements the information available on the Chinese Windows Azure portal and the Windows Azure Technical Library on MSDN. Official information may also be available in many other locations such as the Windows Azure poster, TechNet wiki and in various blog posts by Microsoft employees. This content is intended for partners and developers who are deploying in China to the Datacenters hosted in China.

For the latest update on feature availability for the China service, please visit the Chinese Windows Azure portal. For a list of the current content assets on Windows Azure, please see the Appendix in this document.

Because most of the English technical content that is available from Microsoft currently assumes that applications are being developed for the Global Service rather than for China Service, it’s important for you to ensure that developers are aware of key differences for applications developed to be hosted in China.

First, there are feature differences, which mean that certain features that are in Global Service are not available in China.

Second, for features that are offered in China, there are operating differences which means that to consume publicly available English content (that are written for Global Service), you have to customize any sample code and steps.

The following Windows Azure features are included in China Service at this time.

  • Compute – Virtual Machines (For IaaS Services)

  • Compute – Cloud Service (For PaaS Services)

  • Compute – Web Site

  • Data Services – Storage (For Blobs, tables and Queues)

  • Data Services – SQL Database

  • Data Service – HDInsight

  • SQL Database – SQL Import/ExportNetworks – Virtual Network (To communicate between cloud services via Local networks)

  • Service Bus

  • Active Directory

  • Access Control Service – which has its own UI and namespace

  • Caching – only dedicated cache is supported

  • Mobile Service

  • Media Service

  • CDN

  • Traffic Manager

The following diagrams shows the available components in China Service today.

Azure Features available in China

The following Windows Azure features are not included in China Service at this time.

  • ACS namespace

  • Data Services – SQL Reporting

  • Data Services – SQL Data Sync

  • SQL Database Management Portal

A hosted service in Windows Azure consists of an application that is designed to run in the hosted service and XML configuration files that define how the hosted service should run. Hosted services use both a service definition file (.csdef) and a configuration file (.cscfg). See Overview of Creating a Hosted Service for Windows Azure for more information.

A primary difference when developing a hosted service on China Service is that there are different URIs for endpoint addresses. For example, Windows Azure and SQL Database URIs normally end with windows.net. For China Service developers must be able to recognize when URI endpoints differ, and then configure the tools that they use and the applications that they develop to use URIs for these different endpoints as appropriate.

Examples of when endpoint URIs need to be changed:

  1. Configuring Visual Studio

  2. Defining connection strings for SQL Database

  3. Defining connection strings to Windows Azure Storage

  4. Defining Port Communications in Windows Azure Compute.

  5. Using the Service Management API

  6. Redirecting URLs from a custom domain name to your hosted service

  7. Issuing certificates for HTTPS endpoints

  8. Using Windows Azure diagnostics, which uses Windows Azure Storage

  9. Using tools and services that were designed to run on Windows Azure that have configuration files or service definition files of their own

  10. Uploading an image for VM role using the CSUPLOAD tool

Use the following table to guide you when mapping public Windows Azure and SQL Database endpoints to China specific endpoints.


Service Type Global Service URI China Service URI

Windows Azure - General


*.ch *.chinacloudapi.cn

Windows Azure Compute



Windows Azure Storage







Windows Azure Service Management



SQL Database



Windows Azure Management Portal



SQL Azure Database Management API


See About the SQL Azure Database Management API


Service Bus



SQL Database Import/Export service mapping endpoints

  1. China East: https://sh1prod-dacsvc.chinacloudapp.cn/dacwebservice.svc

  1. China North: https://bj1prod-dacsvc.chinacloudapp.cn/dacwebservice.svc

Currently there are two datacenters operated by China Service. The two datacenters show up as “China North” and “China East” in the location field.

When you are ready to publish your application, open the shortcut menu for the Windows Azure project, and then choose Publish. The following illustration shows the Publish Windows Azure Application wizard

  1. From the “Publish Windows Azure Application” wizard, under “Choose your subscription”, select <Manage…> and then select “New”.

    Publish Windows Azure Application
  2. In the “New subscription” windows;

    1. Select a certificate that you want to use for Authentication. You can choose an existing certificate or create a new one.

    2. Upload this certificate to your Account using the Management portal (http://manage.windowsazure.cn) under the settings section.

    3. Copy your subscription ID from the portal

    4. Enter the service management URL.

    5. Specify a name for your subscription.

      New Subscription

  1. In the Cloud service list, perform one of the following sets of steps:

    • Choose an existing service. The data center location for this cloud service appears. You should note this location and make sure that your storage account location is in the same data center.

    • Choose Create New to create a cloud service that Windows Azure hosts. In the Create Windows Azure Services dialog box, specify a name for the service, and then specify “China North” as the Data center.

  2. In the Environment list, choose either Production or Staging. Choose the staging environment if you want to deploy your application to a test environment. You can move your application to the production environment later.

  3. In the Build configuration list, choose either Debug or Release.

  4. In the Service configuration list, choose Cloud.

  5. Select the Enable Remote Desktop for all roles check box to enable Remote Desktop. This option is primarily used for troubleshooting. When you select this check box, the Remote Desktop Configuration dialog box appears. Choose the Settings link to change the configuration.

    Select the Enable Web Deploy for all web roles check box to enable web deployment. You must enable Remote Desktop to use this feature. For more information, see Publishing a Cloud Service using the Windows Azure Tools. For more information about Web Deploy, see Publishing a Cloud Service using the Windows Azure Tools.

    Windows Azure Publish Settings
  6. Choose the Advanced Settings tab. In the Deployment label field, either accept the default name, or enter a name of your choosing. To append the date to the deployment label, leave the check box selected.

  7. In the Storage account list, choose the storage account to use for this deployment. Compare the locations of the data centers for your cloud service and your storage account. Ideally, these locations should be the same.

    Windows Azure Publish Settings 02
  8. Select the Deployment update check box if you want to deploy only updated components. This type of deployment can be faster than a full deployment. Choose the Settings link to open the Deployment update settings dialog box, shown in the following illustration.

    Windows Azure Deployment Settings
    You can choose either of two options for update deployment, incremental or simultaneous. An incremental deployment updates one deployed instance at a time, so that your application remains online and available to users. A simultaneous deployment updates all deployed instances at once. Simultaneous update is faster than incremental update, but if you choose this option, your application might not be available during the update process.

    You should select the check box if deployment can't be updated, do a full deployment if you want the full deployment to take place automatically if an update deployment fails. A full deployment resets the virtual IP (VIP) address for the cloud service. For more information, see How to: Retain a Constant Virtual IP Address for a Cloud Service.

  1. You can create a publishing profile from the settings that you have chosen. For example, you might have one profile for a test environment and another for production. To save this profile, choose the Save icon. The wizard creates the profile and saves it in the Visual Studio project.

    Windows Azure Publish Summary
    The publishing profile appears in Solution Explorer in Visual Studio, and the profile settings are written to a file with an .azurePubxml extension. Settings are saved as attributes of XML tags.

  2. Choose Publish to publish your application. You can monitor the process status in the Output pane in Visual Studio.

When modifying existing Projects, search your projects for endpoint URIs in service definition files or configuration files that point to Windows Azure, SQL Database URIs.

Endpoints that point to *.windows.net should be redirected to new URIs for China. Several examples are listed below.

You must use custom storage endpoints. The default settings point to *.core.windows.net. The * changes based on your application and storage location.

In the Windows Azure service configuration file (.cscfg) for your Windows Azure application, set up a custom data connection string to point to the blob, queue, and table storage URIs in China Service. The following code shows an example of a custom endpoint where <AccountKey> is a variable that must be replaced by your specific storage Account Key. The string mystorageaccount is an example of a storage account created under a subscription.

<Setting name="DataConnectionString" value=
"BlobEndpoint=https://mystorageaccount.blob.core.chinacloudapi.cn/;QueueEndpoint=https://mystorageaccount.queue.core.chinacloudapi.cn/;TableEndpoint=https://mystorageaccount.table.core.chinacloudapi.cn/;AccountName=mystorageaccount;AccountKey=<AccountKey> " />

Note that custom storage endpoints do not include the DefaultEndpointsProtocol setting. This setting is typically found in connection strings for storage endpoints pointing to the public version of Windows Azure.

Visual Studio also provides an option to create a custom storage endpoint in the Settings section for a given role.

  1. Open a Windows Azure solution containing one or more roles.

  2. Right-Click any role in the Solution Explorer. This brings up the configuration for that role.

  3. Click Settings.

  4. Click Add Setting.

  5. Type in a Name for your setting.

  6. Choose a Type of Connection String.

  7. Click to bring up the Storage Account Connection String dialog box.

  8. Choose Enter storage account credentials.

  9. Enter the proper storage account name and key.

  10. Choose Use custom endpoints and enter the proper https strings for the blob, table and queue endpoints.

  11. Click OK.

Visual Studio creates a custom storage endpoint in your service configuration file. You can use this storage endpoint from the code in your role.

The following code show programmatically connecting to a storage account by using custom URI specific to China Service.

CloudStorageAccount Account = new CloudStorageAccount( 
new StorageCredentialsAccountAndKey(ACCOUNTNAME, ACCOUNTKEY), 
new Uri("http:// ACCOUNTNAME.blob.core.chinacloudapi.cn/"), 
new Uri("http:// ACCOUNTNAME.queue.core.chinacloudapi.cn/"), 
new Uri("http:// ACCOUNTNAME.table.core.chinacloudapi.cn/")
CloudBlobClient BlobClient = Account.CreateCloudBlobClient();

Port bindings also use DNS names that end in *.cloudapp.net. You must change these to point to *.chinacloudapp.cn). Part of a service definition file including a port declaration is shown below.

   <Site name="MySite" physcalDirectory="..\WebSite1">
        <Binding name="My" endpointName="HttpIn" hostHeader="WebSite1.mysite.Chinacloudapp.cn" /> 
   <Site name="Web">
         <Binding name="HttpIn" endpointName="HttpIn" />

For more information, see How to Configure a Windows Azure Port.

SQL Database server names will change from *.database.windows.net to *.devdatabase.chinacloudapi.cn. Any client application or tool must use the new name for its connection string to connect to the databases. References to SQL Database servers could be DataConnectionString values in service definition files or values in other .NET configuration files for applications not running in China Service. For example;

    <add name="SQLAzure" connectionString="Server=tcp:yourserver.devdatabase.chinacloudapi.cn;
Database=Test;User ID=login@server;Password=yourPassword;

Windows Azure Active Directory (“Windows Azure AD”) provides identity and access features for on-premises and cloud applications. Developers can use features of Windows Azure AD to implement single sign-on and single sign-off for enterprise applications and software as a service (SaaS) providers, use the Graph API to query and manage cloud directory objects, and integrate with on-premises Active Directory to sync directory data to the cloud.

Windows Azure Active Directory is included in Windows Azure operated by China Service. However, by design, there are a few difference that affect the developer experience. This article describes those differences.

China Service is a customized product that shares many features with the global Service. The customization resulted in the following differences that affect developers who use Windows Azure AD.

  • Access Control namespaces are not available. To integrate applications and synchronize directories with Windows Azure identity services, use Windows Azure Active Directory. In the Windows Azure Management Portal, click Active Directory.

  • The ACS Management Portal is available only for Service Bus namespaces.

  • The preview of the OAuth 2.0 authorization code grant type for native applications and server-to-server scenarios is not yet supported.

Other than these customizations, Windows Azure AD in China Service is designed to be the same as the global service.

Access Control namespaces that were created during the preview of Windows Azure operated by China Service are not operational or accessible. However, similar features are available in the Active Directory section of the Windows Azure Management Portal.

You can redirect applications using Service Bus to specific endpoints using one of the following methods;

Option 1: Use environment variables to redirect individual or all applications.

Option 2: Use a ServiceBus.config file to redirect individual applications.

Option 3: Use a ServiceBus.config file to redirect all applications.

If you are running an EXE file or worker role, any of the options will work. If you are using a web role, only option 3 is possible.

Regardless of the method, the endpoint names will change as shown in the table below.


Service Bus endpoint Equivalent Windows Azure in China Service Bus Endpoint


servicebus. chinacloudapi.cn


accesscontrol. chinacloudapi.cn

  1. Consider what level to set the variables. Setting the environment variables for the entire computer, a user or an environment running a single application has different implications.

  2. Set the following environment variables at the appropriate level:

This option will not work when adding environment variables through the <environment> tag in the csdef file for a web role. The web role runs in the context of w3wp.exe. Environment variables are not propagated to the w3wp.exe environment. See option 3 for web roles.

  1. Create a ServiceBus.config file with the following content with the appropriate host information.

    <?xml version="1.0" encoding="utf-8"?>
        <relayHostName>servicebus. chinacloudapi.cn</relayHostName>
        <stsHostName>accesscontrol. chinacloudapi.cn</stsHostName>    
  2. Place the ServiceBus.config file in the same directory as the .exe file of the Service Bus/ACS application.

    This option will not work for web roles because they run in the context of w3wp.exe. As a result, the system looks for the servicebus.config file in the %Windir%\System32\inetsrv\ where is does not exist.

  1. Look .NET Framework configuration directory for an existing ServiceBus.config file. The .NET Framework configuration directory depends on the operating system version being 32-bit or 64-bit and the framework version that you have installed, below are the typical locations.


    Microsoft .NET Framework version Operating System version Directory

    2.0 to 3.5



    2.0 to 3.5









  2. If there is an existing ServiceBus.config file in the directory, you must edit it to add the XML configuration outlined in Option 2 (individual redirect using ServiceBus.config). If adding that configuration would conflict with information already in the existing ServiceBus.config file, then you cannot use this option. You must use option 1 or 2.

It is not possible to target a specific framework directory unless you know the framework the role is using. However, the script below generalizes the copying process with web roles. It will copy a servicebus.config file into each .NET directory if it exists.

@echo off
pushd .
cd %windir%\Microsoft.Net\Framework64\
REM set copylocal=true on servicebus.config so its present in bin dir
for /f %%i in ('dir /s /b config') do copy /y %~dp0servicebus.config %%~fi

The Service Management API allows developers to manage the deployment of hosted services running in Windows Azure. In fact, the Management Portals for both Global Service and China Service use the Service Management API.

For more information, see Addressing Service Management Resources and About the Service Management API.

If you are using a custom domain name forwarded to a hosted service running in Global Service and you move that hosted service to China Service, you must update the forwarded domains to point to the new China specific endpoint.

For example, if www.contoso.com is being re-directed to a web role running at contoso.cloudapp.net, it will now have to be re-directed to contoso.chinacloudapp.cn. For more information see How to Configure a Custom Domain for a Windows Azure Hosted Service.

When using the VM role, change the csupload endpoint to use the China-specific URI. For example:

csupload Set-Connection"SubscriptionId=<subscriptionId>;CertificateThumbprint=<certThumbprint>;ServiceManagementEndpoint=https://management.core.chinacloudapi.cn"

The following is a partial list of tools and samples and the changes required to run them on China Service.

Developers should identify internal tools or applications that refer to Global Service compute (*.cloudapp.net) or storage endpoints (*.core.windows.net) and update them to use China-specific endpoints. Use the table in Endpoint Mapping as a guide to replace the various strings you may find in the configuration files or code of these tools.

Some examples include storage explorer tools and storage upload and download tools. Some tools are listed in this section, but the list is not comprehensive.

You can use the Server Explorer in Visual Studio to browse Compute, Service Bus, Storage, and Virtual Machines resources for all China subscriptions. Visual Studio obtains China storage endpoints when a user imports a publish settings file.

The procedure available at Getting Started with the Windows Azure Tools for Visual Studio walks through the entire process of creating a Windows Azure Hello World application, compiling it, debugging it, uploading it and viewing it with the Server Explorer. These instructions work on China installations once you have imported a China subscription into Visual Studio.

You can also view compute, service bus, storage, or virtual machine resources that are already on Windows Azure in China, and that have not been deployed with Visual Studio. Use the instructions at Viewing the State of an Azure Application with the Windows Azure Compute Explorer to view the state of one or more hosted services already running on China Service. Use the instructions at Browsing Storage Resources with the Windows Azure Storage Explorer to view the objects in an existing storage account running on China Service.

The csmanage sample (recently renamed the "Windows Azure ServiceManagement Sample") uses the Service Management API. This sample contains code that points to Global Service. You must find and update references to http://*.windows.net to *.chinacloudapi.cn.

Several updates are required to the URLs in the PlainHttp sample when running it in China. Use the following steps to update the sample.

  1. Open the root folder for this sample: WindowsAzureAppFabricSDKSamples_V1.0-CS\ServiceBus\ExploringFeatures\MessageBuffer\PlainHttp

  2. Navigate to the MessageBufferClient sub folder and edit MainPage.xaml.cs

  3. Change all instances of windows.net to *.chinacloudapi.cn. See lines 31, 77 and 98.

Windows Azure Diagnostics uses either local storage on your development computer or an China Service storage account to store diagnostic information. For more information, see Collecting Logging Data by Using Windows Azure Diagnostics.

For example, your code may contain the following line:


And the following configuration information in your servicedefinition.cscfg file.

  <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="<YourStorageString>" />

The value <YourStorageString> is a custom endpoint and incorporates the URI for China Service.

No certificate changes are required when using custom domain names.

If any existing applications use HTTPS endpoints and the certificates are bound to https://*.cloudapp.net (where * is the name of your service), these certificates will have to be re-issued for *.chinacloudapp.cn. You must use these new certificates when deploying the service in China.

To use Windows PowerShell against China Service, open the PublishSettings.xml file under <Users>\AppData\Roaming\Windows Azure Powershell\ and set the correct endpoint there.

To use the SDK with China Service, supply connection strings either from the management portal, or via the CLI.

Storage, Service Bus and Notification Hubs

All of these accept a respective connection string, you can get the value either from the management portal or using the CLI.

var tableService = azure.createTableService(storageConn);
var blobService= azure.createBlobService(storageConn);
var queueService = azure.createQueueService(storageConn);
var serviceBusService = azure.createServiceBusService(sbConn);
var notificationHubService = azure.createNotificationHubService(nhConn);


For managing SQL Database servers, you use this configuration:

var sqlManagementService = azure.createSqlManagementService(subscriptionId, authentication, hostOptions);

The following lists all the content assets available for Windows Azure today, and indicate whether the asset is specifically talking about China Service.


Asset Content is specifically created for China Description



Global portal for Windows Azure.



Portal built specifically for Windows Azure operated in China

Windows Azure case studies globally


Windows Azure case studies in China



P&P series of books


These books are translated from P&P books published globally, and are targeting Global Service.

Books by MVP


MSDN Library

yes and no


Windows Azure team blogs

yes and no


MSDN Windows Azure portal



MSDN magazine


Virtual Lab




Videos on Channel 9 are for discussing Global Service, same for the Chinese videos on Youku here http://www.youku.com/playlist_show/id_19321941.html

Windows Azure training kit


Localized training kit in Github is for Global Service

MSDN code gallery





we only host English content for windowsazure.com there, there is no localized content