簡單的 Web API 快速開始範例 (C#)

發行項
04/18/2017

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)

這個範例會示範如何對 Microsoft Dynamics 365 Server 進行驗證，然後呼叫基本的 Web API 作業 WhoAmI Function。不同於其他 Web API 範例，這個範例不倚賴其他非標準的 Helper 程式庫或額外的來源檔案。所有其原始程式碼都在單一檔案中，Program.cs 幫助您更容易了解邏輯流程和驗證程序。此範例適用於線上、內部部署和網際網路面向部署 (IFD)。

需求

此範例有下列需求：

若要開啟並建置解決方案，需要 Microsoft Visual Studio 2015 或更新版本。本產品的免費版本可供下載：Visual Studio Express 或 Visual Studio Community。
網際網路或網路連線，分別連線到線上或內部部署 Microsoft Dynamics 365 Server。
Microsoft Dynamics 365 Server (線上或內部部署) 上的使用者帳戶。
如果使用 Dynamics 365 (線上)，則範例應用程式必須是註冊的 Azure Active Directory，如逐步解說：向 Azure Active Directory 註冊 Dynamics 365 應用程式中所述。
如果使用 Dynamics 365 (內部部署) 搭配網際網路對向部署 (IFD)，則範例應用程式必須在您的 Active Directory 用戶中註冊，如逐步解說：向 Active Directory 註冊 Dynamics 365 應用程式中所述。

重要

根據設計，一開始解決方案不會成功建置。必須編輯 //TODO 註解所指示的原始程式碼行，以提供使用者帳戶和/或應用程式註冊資訊。

示範

這個簡單的範例會示範兩個使用 Web API 開發所需的基本概念：對 Microsoft Dynamics 365 Server 驗證，以及使用 HTTP 通訊協定形成基本 Web API 呼叫。

必須驗證，用戶端應用程式才能存取任何 Dynamics 365 資源。此程序不必繁瑣的原因有二個：不同的部署類型需要不同的驗證機制，以及 Web 為基礎的驗證機制通常會牽涉到多個程式設計方面的步驟。內部部署所需的 Windows 整合式驗證，相對來說簡單明瞭，只需要使用者名稱和密碼。之後程式會接著做為已驗證使用者的代理。

相反地，線上和 IFD 部署需要事先註冊用戶端應用程式，然後使用多步驟 OAuth 驗證程序。Dynamics 365 (線上) 的註冊程序在文章逐步解說：向 Azure Active Directory 註冊 Dynamics 365 應用程式中說明。Dynamics 365 (內部部署) 在網際網路對向部署 (IFD) 中的註冊程序在文章逐步解說：向 Active Directory 註冊 Dynamics 365 應用程式中說明。每個後續 Web API 要求都必須經過 OAuth 驗證。幸好 OAuth 驗證的大部分複雜性可加以簡化，透過使用 Active Directory Authentication Library (ADAL) for .NET 用戶端，這會加入範例做為 NuGet 套件 Microsoft.IdentityModel.Clients.ActiveDirectory。 OAuth 授權會在此範例中進一步封裝，透過納入 OAuthMessageHandler 類別，將必要的 OAuth 授權標頭加入至訊息要求。在未來範例中，支援驗證功能劃分至 Web API Helper 程式庫。如需詳細資訊，請參閱在 Microsoft Dynamics 365 中驗證使用者。

Dynamics 365 Web API 是 REST API，根據 OData 規格，因此它支援對實體的標準化 HTTP 要求，以及呼叫函式和動作。這個範例會示範使用 GET 要求叫用 WhoAmI Function 函式，然後使用這個函式提供的資訊在產生的 HTTP 回應中。此範例使用數個標準程式庫來協助叫用：

來自 System.Net 的 .NET Framework 類別和 System.Net.Http 命名空間用於 HTTP 通訊。
因為 C# 缺少 JSON 原生支援，因此開放原始碼 Json.NET 架構會隨附在其 NuGet 套件。
System.Threading.Tasks命名空間支援非同步程式設計。因為潛在延遲，Web 存取通常會採用非同步機制。如需詳細資訊，請參閱使用 Async 和 Await 的非同步程式設計。

執行此範例

首先前往單的 Web API 快速開始範例 (C#)，下載範例封存檔 Simple Web API quick-start sample (CS.zip)，然後將其內容解壓縮至本機資料夾。此資料夾中應包含下列檔案：

檔案	用途/描述
Program.cs	包含此範例的原始程式碼。
SimpleWebApi.sln SimpleWebApi.csproj packages.config AssemblyInfo.cs App.config	此範例的標準 Microsoft Visual Studio 2015 解決方案、專案、NuGet 套件設定、組件資訊及應用程式設定檔。

接著，使用下列程序執行此範例。

尋找解決方案檔案 SimpleWebApi.sln 並按兩下，將解決方案載入 Visual Studio 中。
在 [方案總管] 中，按兩下 [Program.cs] 檔案，在編輯器中開啟它。
尋找 Main 方法內的 //TODO 註解，新增必要的連接字串值，然後取消註解相關行。
建置 SimpleWebApi 解決方案。這樣應該會自動下載和安裝所有遺漏或需要更新的必要 NuGet 套件。
執行 SimpleWebApi 專案，從 Visual Studio 中。根據預設，所有範例解決方案都設定為以偵錯模式執行。
行為取決於部署類型。
- 若是線上和 IFD 部署，主控台應用程式會開啟新的視窗，輸入您的使用者認證和密碼。
- 若是內部部署，主控台應用程式會提示您輸入所提供 Dynamics 365 帳戶的密碼。
提供此資訊並按下 Enter。

程式碼清單

此檔案的最新來源可在範例下載套件中找到。

Program.cs

namespace Microsoft.Crm.Sdk.Samples
{
    /// <summary>
    /// A basic Web API client application for Dynamics 365 (CRM). This sample authenticates 
    /// the user and then calls the WhoAmI Web API function. 
    /// </summary>
    /// <remarks> 
    /// Prerequisites: 
    ///   -  To run this application, you must have a CRM Online or on-premise account. 
    ///   -  For CRM Online or Internet-facing deployments (IFD), the application must be registered  
    ///      with Azure Active Directory as described in this article: 
    ///      https://msdn.microsoft.com/en-us/library/dn531010.aspx
    ///   
    /// The WhoAmI Web API function is documented here: 
    ///    https://msdn.microsoft.com/en-us/library/mt607925.aspx
    /// </remarks>
    static class SimpleWebApi
    {
        //TODO: Uncomment then substitute your correct Dynamics 365 organization service 
        // address for either CRM Online or on-premise (end with a forward-slash).
        //private static string serviceUrl = "https://mydomain.crm.dynamics.com/myorg/";   // CRM Online
        //private static string serviceUrl = "https://<organization name>.<domain name>/";   // CRM IFD
        //private statics string serviceUrl = "http://myserver/myorg/";        // CRM on-premises

        //TODO: For an on-premises deployment, set your organization credentials here. (If
        // online or IFD, you can you can disregard or set to null.)
        private static string userAccount = "<user-account>";  //CRM user account
        private static string domain = "<server-domain>";  //CRM server domain

        //TODO: For CRM Online or IFD deployments, substitute your app registration values  
        // here. (If on-premise, you can disregard or set to null.)
        private static string clientId = "<app-reg-guid>";     //e.g. "e5cf0024-a66a-4f16-85ce-99ba97a24bb2"
        private static string redirectUrl = "<redirect-URL>";  //e.g. "https://localhost/SdkSample"

        static public void Main(string[] args)
        {
            //One message handler for OAuth authentication, and the other for Windows integrated 
            // authentication.  (Assumes that HTTPS protocol only used for CRM Online.)
            HttpMessageHandler messageHandler;
            if (serviceUrl.StartsWith("https://"))
            {
                messageHandler = new OAuthMessageHandler(serviceUrl, clientId, redirectUrl,
                         new HttpClientHandler());
            }
            else
            {
                //Prompt for user account password required for on-premise credentials.  (Better
                // approach is to use the SecureString class here.)
                Console.Write("Please enter the password for account {0}: ", userAccount);
                string password = Console.ReadLine().Trim();
                NetworkCredential credentials = new NetworkCredential(userAccount, password, domain);
                messageHandler = new HttpClientHandler() { Credentials = credentials };
            }
            try
            {
                //Create an HTTP client to send a request message to the CRM Web service.
                using (HttpClient httpClient = new HttpClient(messageHandler))
                {
                    //Specify the Web API address of the service and the period of time each request 
                    // has to execute.
                    httpClient.BaseAddress = new Uri(serviceUrl);
                    httpClient.Timeout = new TimeSpan(0, 2, 0);  //2 minutes

                    //Send the WhoAmI request to the Web API using a GET request. 
                    var response = httpClient.GetAsync("api/data/v8.1/WhoAmI",
                            HttpCompletionOption.ResponseHeadersRead).Result;
                    if (response.IsSuccessStatusCode)
                    {
                        //Get the response content and parse it.
                        JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                        Guid userId = (Guid)body["UserId"];
                        Console.WriteLine("Your system user ID is: {0}", userId);
                    }
                    else
                    {
                        Console.WriteLine("The request failed with a status of '{0}'",
                               response.ReasonPhrase);
                    }
                }
            }
            catch (Exception ex)
            {
                DisplayException(ex);
                throw;
            }
            finally
            {
                Console.WriteLine("Press <Enter> to exit the program.");
                Console.ReadLine();
            }
        }

        /// <summary> Displays exception information to the console. </summary>
        /// <param name="ex">The exception to output</param>
        private static void DisplayException(Exception ex)
        {
            Console.WriteLine("The application terminated with an error.");
            Console.WriteLine(ex.Message);
            while (ex.InnerException != null)
            {
                Console.WriteLine("\t* {0}", ex.InnerException.Message);
                ex = ex.InnerException;
            }
        }
    }

    /// <summary>
    ///Custom HTTP message handler that uses OAuth authentication thru ADAL.
    /// </summary>
    class OAuthMessageHandler : DelegatingHandler
    {
        private AuthenticationHeaderValue authHeader;

        public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl,
                HttpMessageHandler innerHandler)
            : base(innerHandler)
        {
            // Obtain the Azure Active Directory Authentication Library (ADAL) authentication context.
            AuthenticationParameters ap = AuthenticationParameters.CreateFromResourceUrlAsync(
                    new Uri(serviceUrl + "api/data/")).Result;
            AuthenticationContext authContext = new AuthenticationContext(ap.Authority, false);
            //Note that an Azure AD access token has finite lifetime, default expiration is 60 minutes.
            AuthenticationResult authResult = authContext.AcquireToken(serviceUrl, clientId, new Uri(redirectUrl));
            authHeader = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);
        }

        protected override Task<HttpResponseMessage> SendAsync(
                 HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
        {
            request.Headers.Authorization = authHeader;
            return base.SendAsync(request, cancellationToken);
        }
    }
}

另請參閱

Web API Reference
Web API 範例
 使用 Microsoft Dynamics 365 Web API Helper 程式庫 (C#)
在 Microsoft Dynamics 365 中驗證使用者

Microsoft Dynamics 365

共用方式為

簡單的 Web API 快速開始範例 (C#)

需求

示範

執行此範例

程式碼清單

另請參閱

其他資源