如何使用適用於 Azure Mobile Apps 的 ASP.NET Framework SDK

發行項
12/19/2022

注意

此產品已淘汰。如需使用 .NET 8 或更新版本的專案取代專案，請參閱 Community Toolkit Datasync 連結庫。

本主題說明如何在主要 Azure App Service Mobile Apps 案例中使用 .NET 後端伺服器 SDK。 Azure Mobile Apps SDK 可協助您從 ASP.NET 應用程式使用行動用戶端。

警告

本文涵蓋 v4.2.0 連結庫版本的資訊，此版本已由 v5.0.0 連結庫取代。如需最新的資訊，請參閱最新版本文章

建立 Azure Mobile Apps ASP.NET Framework 後端

您可以使用 Visual Studio 2019 建立 ASP.NET Framework 應用程式。

選擇 ASP.NET Web 應用程式（.NET Framework） 範本。如果您在尋找此範本時遇到問題，請選取 [C#]、[所有平臺]，然後 [Web]。
選取應用程式的名稱和位置之後，請選取 Web API 項目範本。將會安裝應用程式的正確基底服務集合。

下載並初始化 SDK

SDK 可在 NuGet.org上使用，並提供開始使用 Azure Mobile Apps 所需的基本功能。若要安裝套件：

以滑鼠右鍵按下項目，然後選取 [管理 NuGet 套件...。
在 [流覽] 索引標籤中，於搜尋方塊中輸入 Microsoft.Azure.Mobile.Server，然後按 Enter 鍵。
選取 Microsoft.Azure.Mobile.Server.Quickstart 套件。
按兩下 [安裝]。
請遵循提示來完成安裝。

重複此程式以安裝 Microsoft.Owin.Host.SystemWeb。

注意

請勿更新作為相依性的套件，例如 Newtonsoft.JSON 或 System.IdentityModel.Jwt。在許多情況下，這些套件的 API 已變更，且現在與適用於 ASP.NET Framework 的 Azure Mobile Apps 不相容。

初始化伺服器專案

Azure Mobile Apps 伺服器專案會初始化，類似於其他 ASP.NET 架構專案;包含 OWIN 啟動類別。若要新增 OWIN 啟動類別：

以滑鼠右鍵按兩下項目，然後選取 [[新增>新增專案]
選取 [Web[一般]，然後選取範本 OWIN 啟動類別。
輸入名稱 Startup.cs 作為啟動名稱。

Startup.cs 檔案的內容應該類似下列程式代碼：

using Microsoft.Azure.Mobile.Server.Config;
using Microsoft.Owin;
using Owin;
using System.Web.Http;

[assembly: OwinStartup(typeof(WebApplication1.Startup))]
namespace WebApplication1
{
    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            HttpConfiguration config = new HttpConfiguration();
            new MobileAppConfiguration()
                // no added features
                .ApplyTo(config);
            app.UseWebApi(config);
        }
    }
}

OwinStartup、命名空間和類別名稱會根據您的專案而有所不同。具體來說，您應該取代 Configuration() 方法的內容，並據以調整 using 指示詞。

若要啟用個別功能，您必須先在 MobileAppConfiguration 物件上呼叫擴充方法，才能呼叫 applyTo。例如，下列程式代碼會將預設路由新增至初始化期間具有屬性 [MobileAppController] 的所有 API 控制器：

new MobileAppConfiguration()
    .MapApiControllers()
    .ApplyTo(config);

下列設定被視為「一般」使用方式，可讓數據表和 API 控制器使用 Entity Framework 來存取 SQL 服務。

new MobileAppConfiguration()
    .AddMobileAppHomeController()
    .MapApiControllers()
    .AddTables(
        new MobileAppTableConfiguration()
            .MapTableControllers()
            .AddEntityFramework()
    )
    .MapLegacyCrossDomainController()
    .ApplyTo(config);

使用的擴充方法如下：

AddMobileAppHomeController() 提供預設的 Azure Mobile Apps 首頁。
MapApiControllers() 為以 [MobileAppController] 屬性裝飾的 WebAPI 控制器提供自定義 API 功能。
AddTables() 提供 /tables 端點與數據表控制器的對應。
AddTablesWithEntityFramework() 是使用 Entity Framework 型控制器對應 /tables 端點的簡短方法。
MapLegacyCrossDomainController() 提供標準 CORS 標頭以進行本機開發。

SDK 延伸模組

下列以 NuGet 為基礎的擴充功能套件提供應用程式可以使用的各種行動功能。您可以使用 MobileAppConfiguration 物件，在初始化期間啟用擴充功能。

Microsoft.Azure.Mobile.Server.Quickstart 支援基本的 Mobile Apps 設定。在初始化期間呼叫 UseDefaultConfiguration 擴充方法，以新增至組態。此延伸模組包含下列延伸模組：通知、驗證、實體、數據表、跨網域和首頁套件。
Microsoft.Azure.Mobile.Server.Home 實作此行動應用程式的預設 網站根目錄已啟動並執行頁面。呼叫 addMobileAppHomeController 擴充方法，以新增至組態。
Microsoft.Azure.Mobile.Server.Tables 包含處理數據和設定數據管線的類別。呼叫 AddTables 擴充方法，以新增至組態。
Microsoft.Azure.Mobile.Server.Entity 讓 Entity Framework 能夠存取 SQL Database 中的數據。呼叫 AddTablesWithEntityFramework 擴充方法，以新增至組態。
Microsoft.Azure.Mobile.Server.Authentication 啟用驗證和設定用來驗證令牌的 OWIN 中間件。呼叫 AddAppServiceAuthentication 並 IAppBuilder來新增至組態。UseAppServiceAuthentication 擴充方法。
Microsoft.Azure.Mobile.Server.Notifications 啟用推播通知並定義推播註冊端點。呼叫 addPushNotifications 擴充方法新增至組態。
Microsoft.Azure.Mobile.Server.CrossDomain 建立控制器，以從行動應用程式將數據傳送至舊版網頁瀏覽器。呼叫 MapLegacyCrossDomainController 擴充方法，以新增至組態。
Microsoft.Azure.Mobile.Server.Login 提供 AppServiceLoginHandler.CreateToken() 方法，這是自定義驗證案例期間使用的靜態方法。

發佈伺服器專案

本節說明如何從 Visual Studio 發佈 .NET 後端專案。還有其他方法可讓您發佈應用程式。如需詳細資訊，請參閱 Azure App Service 檔。

在Visual Studio中，重建專案以還原NuGet套件。
在 [方案總管] 中，以滑鼠右鍵按兩下專案，按兩下 [[發佈]。
如果您之前尚未發佈此專案，您將設定發佈。
- 選取目標 Azure。
- 針對特定目標選取 [Azure App Service [Windows]。
- 選取您想要部署的 App Service 實例。如果您沒有帳戶，請使用 + 來建立一個。
- 點選 [完成] 。
如果您之前尚未連結 SQL 資料庫，請按下 SQL Database 旁的 [設定]
。
- 選取 [azure SQL Database]
- 選取您的資料庫。如果您沒有一個或想要使用不同的資料庫，請按兩下 + 來建立新的資料庫和伺服器。
- 輸入 MS_TableConnectionString 作為資料庫連接字串名稱。在提供的方塊中填入使用者名稱和密碼。
- 按兩下 [完成
按兩下 [發佈

發佈至 Azure 需要一些時間。如需詳細資訊，請參閱 Visual Studio 檔案。

定義數據表控制器

定義數據表控制器，以向行動用戶端公開 SQL 資料表。設定資料表控制器需要三個步驟：

建立資料傳輸物件（DTO）類別。
在Mobile DbContext 類別中設定資料表參考。
建立數據表控制器。

數據傳輸物件（DTO）是繼承自 EntityData的一般 C# 物件。例如：

public class TodoItem : EntityData
{
    public string Text { get; set; }
    public bool Complete {get; set;}
}

DTO 可用來定義 SQL 資料庫中的數據表。若要建立資料庫專案，請將 DbSet<> 屬性新增至您使用的 DbContext：

public class MobileServiceContext : DbContext
{
    private const string connectionStringName = "Name=MS_TableConnectionString";

    public MobileServiceContext() : base(connectionStringName)
    {

    }

    public DbSet<TodoItem> TodoItems { get; set; }

    protected override void OnModelCreating(DbModelBuilder modelBuilder)
    {
        modelBuilder.Conventions.Add(
            new AttributeToColumnAnnotationConvention<TableColumnAttribute, string>(
                "ServiceColumnTable", (property, attributes) => attributes.Single().ColumnType.ToString()));
    }
}

最後，建立新的控制器：

以滑鼠右鍵按兩下 Controllers 資料夾。
選取 [Web API>Web API 2 控制器 - 空白
輸入控制器的名稱。

以下欄程序代碼取代新控制器的內容：

public class TodoItemController : TableController<TodoItem>
{
    protected override void Initialize(HttpControllerContext controllerContext)
    {
        base.Initialize(controllerContext);
        ZUMOAPPNAMEContext context = new ZUMOAPPNAMEContext();
        DomainManager = new EntityDomainManager<TodoItem>(context, Request);
    }

    // GET tables/TodoItem
    public IQueryable<TodoItem> GetAllTodoItems()
    {
        return Query();
    }

    // GET tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
    public SingleResult<TodoItem> GetTodoItem(string id)
    {
        return Lookup(id);
    }

    // PATCH tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
    public Task<TodoItem> PatchTodoItem(string id, Delta<TodoItem> patch)
    {
        return UpdateAsync(id, patch);
    }

    // POST tables/TodoItem
    public async Task<IHttpActionResult> PostTodoItem(TodoItem item)
    {
        TodoItem current = await InsertAsync(item);
        return CreatedAtRoute("Tables", new { id = current.Id }, current);
    }

    // DELETE tables/TodoItem/48D68C86-6EA6-4C25-AA33-223FC9A27959
    public Task DeleteTodoItem(string id)
    {
        return DeleteAsync(id);
    }
}

調整數據表分頁大小

根據預設，Azure Mobile Apps 會針對每個要求傳回 50 筆記錄。分頁可確保用戶端不會將其UI線程和伺服器系結太久，以確保良好的用戶體驗。若要變更資料表分頁大小，請增加伺服器端的「允許查詢大小」和用戶端頁面大小。伺服器端「允許的查詢大小」會使用 EnableQuery 屬性來調整：

[EnableQuery(PageSize = 500)]

確定 PageSize 與用戶端所要求的大小相同或更大。如需變更用戶端頁面大小的詳細數據，請參閱特定的用戶端 HOWTO 檔。

定義自定義 API 控制器

自定義 API 控制器會藉由公開端點，為您的行動應用程式後端提供最基本的功能。您可以使用 [MobileAppController] 屬性來註冊行動特定 API 控制器。 MobileAppController 屬性會註冊路由、設定Mobile Apps JSON串行化程式，並開啟用戶端版本檢查。

自訂 API 控制器的內容如下：

[MobileAppController]
public class CustomAPIController : ApiController
{
    // Content here
}

使用 MobileAppController 屬性進行設定之後，您就可以以與任何其他 Web API 相同的方式定義自定義 API。

使用驗證

Azure Mobile Apps 會使用 App Service 驗證/授權來保護您的行動後端。本節說明如何在 .NET 後端伺服器項目中執行下列驗證相關工作：

將驗證新增至伺服器專案
使用應用程式的自訂驗證
擷取已驗證的使用者資訊
限制授權用戶的數據存取

將驗證新增至伺服器專案

您可以藉由擴充 MobileAppConfiguration 物件和設定 OWIN 中間件，將驗證新增至伺服器專案。

在 Visual Studio 中，安裝 Microsoft.Azure.Mobile.Server.Authentication 套件。
在 Startup.cs 項目檔中，於 Configuration 方法開頭新增下列程式代碼行：
```
app.UseAppServiceAuthentication(config);
```
此 OWIN 中間件元件會驗證相關聯 App Service 閘道所簽發的令牌。
將 [Authorize] 屬性新增至任何需要驗證的控制器或方法。

針對您的應用程式使用自定義驗證

重要

若要啟用自定義驗證，您必須先啟用App Service驗證，而不需在 Azure 入口網站中選取 App Service 的提供者。這會在裝載時啟用 WEBSITE_AUTH_SIGNING_KEY 環境變數。

如果您不想使用其中一個 App Service 驗證/授權提供者，您可以實作自己的登入系統。安裝 Microsoft.Azure.Mobile.Server.Login 套件，以協助產生驗證令牌。提供您自己的程式代碼來驗證使用者認證。例如，您可能會檢查資料庫中的鹽化和哈希密碼。在下列範例中，isValidAssertion() 方法（定義於別處）負責這些檢查。

自訂驗證會藉由建立 ApiController 並公開 register 和 login 動作來公開。客戶端應該使用自定義UI從使用者收集資訊。然後，系統會使用標準 HTTP POST 呼叫，將資訊提交至 API。一旦伺服器驗證判斷提示，就會使用 AppServiceLoginHandler.CreateToken() 方法發出令牌。 ApiController 不應該 使用 [MobileAppController] 屬性。

範例 login 動作：

public IHttpActionResult Post([FromBody] JObject assertion)
{
    if (isValidAssertion(assertion)) // user-defined function, checks against a database
    {
        JwtSecurityToken token = AppServiceLoginHandler.CreateToken(new Claim[] { new Claim(JwtRegisteredClaimNames.Sub, assertion["username"]) },
            mySigningKey,
            myAppURL,
            myAppURL,
            TimeSpan.FromHours(24) );
        return Ok(new LoginResult()
        {
            AuthenticationToken = token.RawData,
            User = new LoginResultUser() { UserId = userName.ToString() }
        });
    }
    else // user assertion was not valid
    {
        return this.Request.CreateUnauthorizedResponse();
    }
}

在上述範例中，LoginResult 和 LoginResultUser 是公開必要屬性的可串行化物件。用戶端預期會以 JSON 物件的形式傳回登入回應：

{
    "authenticationToken": "<token>",
    "user": {
        "userId": "<userId>"
    }
}

AppServiceLoginHandler.CreateToken() 方法包含物件和 簽發者 參數。這兩個參數都會使用 HTTPS 配置，設定為應用程式根目錄的 URL。同樣地，您應該將 secretKey 設定為應用程式簽署密鑰的值。請勿在用戶端中散發簽署密鑰，因為它可以用來挖掘密鑰並模擬使用者。您可以藉由參考 WEBSITE_AUTH_SIGNING_KEY 環境變數，在 App Service 中裝載時取得簽署密鑰。如果在本機偵錯內容中需要，請依照使用驗證區段本機偵錯中的指示擷取密鑰，並將其儲存為應用程式設定。

發行的令牌也可能包含其他宣告和到期日。至少，簽發的令牌必須包含主體（子）宣告。

您可以藉由多載驗證路由來支援標準用戶端 loginAsync() 方法。如果用戶端呼叫 client.loginAsync('custom'); 來登入，您的路由必須 /.auth/login/custom。您可以使用 MapHttpRoute()來設定自訂驗證控制器的路由：

config.Routes.MapHttpRoute("custom", ".auth/login/custom", new { controller = "CustomAuth" });

提示

使用 loginAsync() 方法可確保驗證令牌會附加至服務的每個後續呼叫。

擷取已驗證的用戶資訊

當 App Service 驗證使用者時，您可以在 .NET 後端程式代碼中存取指派的使用者識別碼和其他資訊。使用者資訊可用於在後端進行授權決策。下列程式代碼會取得與要求相關聯的使用者識別碼：

// Get the SID of the current user.
var claimsPrincipal = this.User as ClaimsPrincipal;
string sid = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier).Value;

SID 衍生自提供者特定的使用者標識碼，而且是指定使用者和登入提供者的靜態。無效驗證令牌的 SID 為 Null。

App Service 也可讓您向登入提供者要求特定宣告。每個識別提供者都可以使用識別提供者 SDK 來提供更多資訊。例如，您可以使用Facebook圖形 API 來取得朋友資訊。您可以指定 Azure 入口網站中提供者刀鋒視窗中要求的宣告。某些宣告需要使用識別提供者進行更多設定。

下列程式代碼會呼叫 GetAppServiceIdentityAsync 擴充方法來取得登入認證，其中包括對 Facebook Graph API 提出要求所需的存取令牌：

// Get the credentials for the logged-in user.
var credentials = await this.User.GetAppServiceIdentityAsync<FacebookCredentials>(this.Request);

if (credentials.Provider == "Facebook")
{
    // Create a query string with the Facebook access token.
    var fbRequestUrl = "https://graph.facebook.com/me/feed?access_token="
        + credentials.AccessToken;

    // Create an HttpClient request.
    var client = new System.Net.Http.HttpClient();

    // Request the current user info from Facebook.
    var resp = await client.GetAsync(fbRequestUrl);
    resp.EnsureSuccessStatusCode();

    // Do something here with the Facebook user information.
    var fbInfo = await resp.Content.ReadAsStringAsync();
}

為 System.Security.Principal 新增 using 語句，以提供 GetAppServiceIdentityAsync 擴充方法。

限制授權用戶的數據存取

在上一節中，我們示範如何擷取已驗證使用者的用戶標識碼。您可以根據此值限制對資料和其他資源的存取。例如，將userId數據行新增至數據表，並依使用者標識碼篩選查詢結果，是將傳回的數據限制為僅限授權用戶的簡單方式。只有在 SID 符合 TodoItem 數據表之 UserId 數據行中的值時，下列程式代碼才會傳回數據列：

// Get the SID of the current user.
var claimsPrincipal = this.User as ClaimsPrincipal;
string sid = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier).Value;

// Only return data rows that belong to the current user.
return Query().Where(t => t.UserId == sid);

Query() 方法會傳回可由 LINQ 操作以處理篩選的 IQueryable。

對 .NET Server SDK 進行偵錯和疑難解答

Azure App Service 為 ASP.NET 應用程式提供數種偵錯和疑難解答技術：

監視 Azure App Service
在 Azure App Service 中啟用診斷記錄
在 Visual Studio 中針對 Azure App Service 進行疑難解答

伐木

您可以使用標準 ASP.NET 追蹤寫入，寫入至 App Service 診斷記錄。您必須先在 Azure Mobile Apps 後端啟用診斷，才能寫入記錄。

若要啟用診斷並寫入記錄：

請遵循啟用應用程式記錄（Windows）中的步驟。
在您的程式代碼檔案中新增下列 using 語句：
```
using System.Web.Http.Tracing;
```

建立追蹤寫入器，以從 .NET 後端寫入診斷記錄，如下所示：

ITraceWriter traceWriter = this.Configuration.Services.GetTraceWriter();
traceWriter.Info("Hello, World");

重新發佈您的伺服器專案，並存取 Azure Mobile Apps 後端，以使用記錄來執行程式碼路徑。
下載並評估記錄檔，如 Access 記錄檔中所述，。

使用驗證進行本機偵錯

您可以將變更發佈至雲端之前，先在本機執行應用程式以測試變更。針對大部分的 Azure Mobile Apps 後端，請在 Visual Studio 中按下 F5。不過，使用驗證時有一些額外的考慮。

您必須已設定 App Service 驗證/授權的雲端式行動應用程式，且您的用戶端必須指定為替代登入主機的雲端端點。如需所需的特定步驟，請參閱用戶端平台的檔。

請確定您的行動後端已安裝 Microsoft.Azure.Mobile.Server.Authentication。然後，在應用程式的 OWIN 啟動類別中，在 MobileAppConfiguration 套用至您的 HttpConfiguration之後，新增下列專案：

app.UseAppServiceAuthentication(new AppServiceAuthenticationOptions()
{
    SigningKey = ConfigurationManager.AppSettings["authSigningKey"],
    ValidAudiences = new[] { ConfigurationManager.AppSettings["authAudience"] },
    ValidIssuers = new[] { ConfigurationManager.AppSettings["authIssuer"] },
    TokenHandler = config.GetAppServiceTokenHandler()
});

在上述範例中，您應該使用 HTTPS 配置，將 authAudience 和 authIssuer Web.config 檔案內的應用程式設定設為應用程式根目錄的 URL。同樣地，您應該將 authSigningKey 設定為應用程式簽署密鑰的值。

若要取得簽署金鑰：

在 Azure 入口網站內瀏覽至您的應用程式
點選「工具]>Kudu>Go。
在 Kudu 管理網站中，按兩下 [環境]。
尋找 WEBSITE_AUTH_SIGNING_KEY的值。

在本機應用程式組態中使用 authSigningKey 參數的簽署密鑰。您的行動後端現在已準備好在本機執行時驗證令牌，用戶端會從雲端式端點取得令牌。

共用方式為