Så här använder du ASP.NET Framework SDK för Azure Mobile Apps

Artikel
12/19/2022

Not

Den här produkten har dragits tillbaka. En ersättning för projekt som använder .NET 8 eller senare finns i Community Toolkit Datasync-biblioteket.

Det här avsnittet visar hur du använder .NET-server-SDK:et i viktiga Azure App Service Mobile Apps-scenarier. Azure Mobile Apps SDK hjälper dig att arbeta med mobila klienter från ditt ASP.NET program.

Varning

Den här artikeln beskriver information för biblioteksversionen v4.2.0, som ersätts av v5.0.0-biblioteket. Den senaste informationen finns i artikeln om senaste versionen

Skapa en Azure Mobile Apps ASP.NET Framework-serverdel

Du kan skapa en ASP.NET Framework-app med Visual Studio 2019.

Välj mallen ASP.NET Web Application (.NET Framework). Om du har problem med att hitta den här mallen väljer du C#, Alla plattformaroch Web.
När du har valt ett namn och en plats för programmet väljer du webb-API projektmall. Rätt samling bastjänster för ditt program installeras.

Ladda ned och initiera SDK

SDK:et är tillgängligt på NuGet.orgoch tillhandahåller de grundläggande funktioner som krävs för att komma igång med Azure Mobile Apps. Så här installerar du paketet:

Högerklicka på projektet och välj sedan Hantera NuGet-paket....
På fliken Bläddra anger du Microsoft.Azure.Mobile.Server i sökrutan och trycker sedan på Retur.
Välj det Microsoft.Azure.Mobile.Server.Quickstart paketet.
Klicka på Installera.
Följ anvisningarna för att slutföra installationen.

Upprepa processen för att installera Microsoft.Owin.Host.SystemWeb också.

Not

Uppdatera inte de paket som används som beroenden, till exempel Newtonsoft.JSON eller System.IdentityModel.Jwt. API:erna för dessa paket har i många fall ändrats och är nu inkompatibla med Azure Mobile Apps för ASP.NET Framework.

Initiera serverprojektet

Ett Azure Mobile Apps-serverprojekt initieras på liknande sätt som andra ASP.NET Framework-projekt. genom att inkludera en OWIN Startup-klass. Så här lägger du till en OWIN-startklass:

Högerklicka på projektet och välj sedan Lägg till>nytt objekt
Välj Web>Allmäntoch välj sedan mallen OWIN-startklass.
Ange namnet Startup.cs som startnamn.

Innehållet i Startup.cs-filen bör likna följande kod:

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, namnrymd och klassnamn skiljer sig beroende på ditt projekt. Mer specifikt bör du ersätta innehållet i metoden Configuration() och justera using direktiven i enlighet med detta.

Om du vill aktivera enskilda funktioner måste du anropa tilläggsmetoder på objektet MobileAppConfiguration innan du anropar ApplyTo. Följande kod lägger till standardvägarna till alla API-kontrollanter som har attributet [MobileAppController] under initieringen:

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

Följande konfiguration anses vara en "normal" användning som gör att både tabell- och API-kontrollanter som använder Entity Framework kan komma åt en SQL-tjänst.

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

De tilläggsmetoder som används är:

AddMobileAppHomeController() tillhandahåller standardstartsidan för Azure Mobile Apps.
MapApiControllers() tillhandahåller anpassade API-funktioner för WebAPI-styrenheter som är dekorerade med attributet [MobileAppController].
AddTables() innehåller en mappning av /tables slutpunkter till tabellkontrollanter.
AddTablesWithEntityFramework() är en kort hand för att mappa /tables slutpunkter med entity framework-baserade kontrollanter.
MapLegacyCrossDomainController() tillhandahåller CORS-standardhuvuden för lokal utveckling.

SDK-tillägg

Följande NuGet-baserade tilläggspaket innehåller olika mobila funktioner som kan användas av ditt program. Du aktiverar tillägg under initieringen med hjälp av objektet MobileAppConfiguration.

Microsoft.Azure.Mobile.Server.Snabbstart Stöder den grundläggande konfigurationen av mobilappar. Har lagts till i konfigurationen genom att anropa metoden UseDefaultConfiguration-tillägg under initieringen. Det här tillägget innehåller följande tillägg: Meddelanden, autentisering, entitet, tabeller, korsdomäner och hempaket.
Microsoft.Azure.Mobile.Server.Home Implementerar standardvärdet den här mobilappen är igång och kör sidan för webbplatsroten. Lägg till i konfigurationen genom att anropa AddMobileAppHomeController tilläggsmetod.
Microsoft.Azure.Mobile.Server.Tables innehåller klasser för att arbeta med data och konfigurera datapipelinen. Lägg till i konfigurationen genom att anropa metoden AddTables-tillägg.
Microsoft.Azure.Mobile.Server.Entity Gör att Entity Framework kan komma åt data i SQL Database. Lägg till i konfigurationen genom att anropa metoden AddTablesWithEntityFramework-tillägg.
Microsoft.Azure.Mobile.Server.Authentication Aktiverar autentisering och konfigurerar OWIN-mellanprogrammet som används för att verifiera token. Lägg till i konfigurationen genom att anropa AddAppServiceAuthentication och IAppBuilder.UseAppServiceAuthentication tilläggsmetoder.
Microsoft.Azure.Mobile.Server.Notifications Aktiverar push-meddelanden och definierar en push-registreringsslutpunkt. Lägg till i konfigurationen genom att anropa AddPushNotifications tilläggsmetod.
Microsoft.Azure.Mobile.Server.CrossDomain Skapar en kontrollant som hanterar data till äldre webbläsare från din mobilapp. Lägg till i konfigurationen genom att anropa MapLegacyCrossDomainController tilläggsmetod.
Microsoft.Azure.Mobile.Server.Login Tillhandahåller metoden AppServiceLoginHandler.CreateToken(), som är en statisk metod som används vid anpassade autentiseringsscenarier.

Publicera serverprojektet

Det här avsnittet visar hur du publicerar ditt .NET-serverdelsprojekt från Visual Studio. Det finns andra metoder som du kan publicera programmet med. Mer information finns i Azure App Service-dokumentationen.

I Visual Studio återskapar du projektet för att återställa NuGet-paket.
Högerklicka på projektet i Solution Explorer och klicka på Publicera.
Om du inte har publicerat det här projektet tidigare konfigurerar du publicering.
- Välj Azure som mål.
- Välj Azure App Service (Windows) för det specifika målet.
- Välj den App Service-instans som du vill distribuera till. Om du inte har någon använder du + för att skapa en.
- Klicka på Slutför.
Om du inte har länkat en SQL-databas tidigare klickar du på Konfigurera bredvid SQL Database.
- Välj Azure SQL Database
- Välj din databas. Om du inte har en eller vill använda en annan klickar du på + för att skapa en ny databas och server.
- Ange MS_TableConnectionString som namnet på databasanslutningssträngen. Fyll i användarnamnet och lösenordet i de angivna rutorna.
- Klicka på Slutför
Klicka på Publicera

Det tar lite tid att publicera till Azure. Mer information finns i Visual Studio-dokumentationen.

Definiera en tabellkontrollant

Definiera en tabellstyrenhet för att exponera en SQL-tabell för mobila klienter. Det krävs tre steg för att konfigurera en tabellkontrollant:

Skapa en DTO-klass (Data Transfer Object).
Konfigurera en tabellreferens i klassen Mobile DbContext.
Skapa en tabellkontrollant.

Ett dataöverföringsobjekt (DTO) är ett vanligt C#-objekt som ärver från EntityData. Till exempel:

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

DTO används för att definiera tabellen i SQL-databasen. Om du vill skapa databasposten lägger du till en egenskap för DbSet<> i DbContext du använder:

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()));
    }
}

Skapa slutligen en ny kontrollant:

Högerklicka på mappen Controllers.
Välj webb-API>Web API 2-kontrollant – tom
Ange ett namn på kontrollanten.

Ersätt innehållet i den nya kontrollanten med följande kod:

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);
    }
}

Justera tabellens växlingsstorlek

Som standard returnerar Azure Mobile Apps 50 poster per begäran. Växling säkerställer att klienten inte binder upp användargränssnittstråden eller servern för länge, vilket säkerställer en bra användarupplevelse. Om du vill ändra storlek på tabellväxlingen ökar du serversidans "tillåtna frågestorlek" och sidstorleken på klientsidan Serversidans "tillåtna frågestorlek" justeras med attributet EnableQuery:

[EnableQuery(PageSize = 500)]

Kontrollera att PageSize är samma eller större än den storlek som klienten begär. Mer information om hur du ändrar klientsidans storlek finns i den specifika howto-dokumentationen för klienten.

Definiera en anpassad API-kontrollant

Den anpassade API-kontrollanten tillhandahåller de mest grundläggande funktionerna till mobilappens serverdel genom att exponera en slutpunkt. Du kan registrera en mobilspecifik API-styrenhet med hjälp av attributet [MobileAppController]. Attributet MobileAppController registrerar vägen, konfigurerar Mobile Apps JSON-serialiseraren och aktiverar klientversionskontroll.

Innehållet i den anpassade API-kontrollanten är:

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

När du har konfigurerat med attributet MobileAppController kan du definiera det anpassade API:et på samma sätt som andra webb-API:er.

Arbeta med autentisering

Azure Mobile Apps använder App Service-autentisering/auktorisering för att skydda din mobila serverdel. Det här avsnittet visar hur du utför följande autentiseringsrelaterade uppgifter i ditt .NET-serverprojekt:

Lägg till autentisering i ett serverprojekt
Använd anpassad autentisering för ditt program
Hämta autentiserad användarinformation
Begränsa dataåtkomst för behöriga användare

Lägga till autentisering i ett serverprojekt

Du kan lägga till autentisering i serverprojektet genom att utöka MobileAppConfiguration-objektet och konfigurera OWIN-mellanprogram.

Installera paketet Microsoft.Azure.Mobile.Server.Authentication i Visual Studio.
I Startup.cs-projektfilen lägger du till följande kodrad i början av metoden Configuration:
```
app.UseAppServiceAuthentication(config);
```
Den här OWIN-mellanprogramskomponenten validerar token som utfärdats av den associerade App Service-gatewayen.
Lägg till attributet [Authorize] till valfri kontrollant eller metod som kräver autentisering.

Använda anpassad autentisering för ditt program

Viktig

För att kunna aktivera anpassad autentisering måste du först aktivera App Service-autentisering utan att välja en provider för din App Service i Azure-portalen. Detta aktiverar WEBSITE_AUTH_SIGNING_KEY miljövariabeln när den finns.

Om du inte vill använda någon av App Service-autentiserings-/auktoriseringsprovidrar kan du implementera ditt eget inloggningssystem. Installera paketet Microsoft.Azure.Mobile.Server.Login för att hjälpa till med generering av autentiseringstoken. Ange din egen kod för att verifiera användarautentiseringsuppgifter. Du kan till exempel kontrollera saltade och hashade lösenord i en databas. I exemplet nedan ansvarar isValidAssertion()-metoden (definierad någon annanstans) för dessa kontroller.

Den anpassade autentiseringen exponeras genom att skapa en ApiController och exponera register och login åtgärder. Klienten bör använda ett anpassat användargränssnitt för att samla in informationen från användaren. Informationen skickas sedan till API:et med ett standard-HTTP POST-anrop. När servern har verifierat försäkran utfärdas en token med hjälp av metoden AppServiceLoginHandler.CreateToken(). ApiController-bör inte använda attributet [MobileAppController].

Ett exempel login åtgärd:

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();
    }
}

I föregående exempel är LoginResult och LoginResultUser serialiserbara objekt som exponerar nödvändiga egenskaper. Klienten förväntar sig att inloggningssvar returneras som JSON-objekt i formuläret:

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

Metoden AppServiceLoginHandler.CreateToken() innehåller en målgrupp och en utfärdare parameter. Båda dessa parametrar är inställda på URL:en för programroten med hjälp av HTTPS-schemat. På samma sätt bör du ange secretKey vara värdet för ditt programs signeringsnyckel. Distribuera inte signeringsnyckeln i en klient eftersom den kan användas för att mynta nycklar och personifiera användare. Du kan hämta signeringsnyckeln när den finns i App Service genom att referera till WEBSITE_AUTH_SIGNING_KEY miljövariabeln. Om det behövs i en lokal felsökningskontext följer du anvisningarna i avsnittet Lokal felsökning med autentisering för att hämta nyckeln och lagra den som en programinställning.

Den utfärdade token kan också innehålla andra anspråk och ett utgångsdatum. Den utfärdade token måste minst innehålla ett ämne (under) anspråk.

Du kan stödja standardklientens loginAsync() metod genom att överbelasta autentiseringsvägen. Om klienten anropar client.loginAsync('custom'); för att logga in måste vägen vara /.auth/login/custom. Du kan ange vägen för den anpassade autentiseringsstyrenheten med hjälp av MapHttpRoute():

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

Dricks

Med hjälp av metoden loginAsync() ser du till att autentiseringstoken är kopplad till varje efterföljande anrop till tjänsten.

Hämta autentiserad användarinformation

När en användare autentiseras av App Service kan du komma åt det tilldelade användar-ID:t och annan information i .NET-serverdelskoden. Användarinformationen kan användas för att fatta auktoriseringsbeslut i serverdelen. Följande kod hämtar användar-ID:t som är associerat med en begäran:

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

SID härleds från det providerspecifika användar-ID:t och är statiskt för en viss användare och inloggningsprovider. SID är null för ogiltiga autentiseringstoken.

Med App Service kan du också begära specifika anspråk från din inloggningsprovider. Varje identitetsprovider kan ge mer information med hjälp av identitetsproviderns SDK. Du kan till exempel använda Facebook Graph API för information om vänner. Du kan ange anspråk som begärs på providerbladet i Azure-portalen. Vissa anspråk kräver mer konfiguration med identitetsprovidern.

Följande kod anropar metoden GetAppServiceIdentityAsync-tillägg för att hämta inloggningsuppgifterna, som inkluderar den åtkomsttoken som behövs för att göra begäranden mot 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();
}

Lägg till en using-instruktion för System.Security.Principal för att ange GetAppServiceIdentityAsync-tilläggsmetod.

Begränsa dataåtkomst för behöriga användare

I föregående avsnitt visade vi hur du hämtar användar-ID:t för en autentiserad användare. Du kan begränsa åtkomsten till data och andra resurser baserat på det här värdet. Att till exempel lägga till en userId-kolumn i tabeller och filtrera frågeresultaten efter användar-ID är ett enkelt sätt att begränsa returnerade data endast till behöriga användare. Följande kod returnerar endast datarader när SID matchar värdet i kolumnen UserId i tabellen TodoItem:

// 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);

Metoden Query() returnerar en IQueryable som kan manipuleras av LINQ för att hantera filtrering.

Felsöka .NET Server SDK

Azure App Service innehåller flera felsöknings- och felsökningstekniker för ASP.NET program:

Skogsavverkning

Du kan skriva till App Service-diagnostikloggar med hjälp av standard-ASP.NET spårningsskrivning. Innan du kan skriva till loggarna måste du aktivera diagnostik i Azure Mobile Apps-serverdelen.

Så här aktiverar du diagnostik och skriver till loggarna:

Följ stegen i Aktivera programloggning (Windows).
Lägg till följande instruktion med hjälp av i kodfilen:
```
using System.Web.Http.Tracing;
```

Skapa en spårningsskrivare för att skriva från .NET-serverdelen till diagnostikloggarna enligt följande:

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

Publicera om serverprojektet och få åtkomst till Azure Mobile Apps-serverdelen för att köra kodsökvägen med loggningen.
Ladda ned och utvärdera loggarna enligt beskrivningen i Åtkomstloggfiler.

Lokal felsökning med autentisering

Du kan köra programmet lokalt för att testa ändringar innan du publicerar dem i molnet. Tryck på F5 i Visual Studio för de flesta Azure Mobile Apps-serverdelar. Det finns dock några extra saker att tänka på när du använder autentisering.

Du måste ha en molnbaserad mobilapp med App Service-autentisering/auktorisering konfigurerad, och din klient måste ha molnslutpunkten angiven som alternativ inloggningsvärd. Se dokumentationen för klientplattformen för de specifika steg som krävs.

Kontrollera att din mobila serverdel har Microsoft.Azure.Mobile.Server.Authentication installerat. Lägg sedan till följande i programmets OWIN-startklass efter att MobileAppConfiguration har tillämpats på din HttpConfiguration:

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

I föregående exempel bör du konfigurera authAudience och authIssuer programinställningar i din Web.config-fil till att var och en är URL:en för programroten med hjälp av HTTPS-schemat. På samma sätt bör du ange authSigningKey vara värdet för ditt programs signeringsnyckel.

Så här hämtar du signeringsnyckeln:

Gå till din app i Azure-portalen
Klicka på Tools>Kudu>Go.
Klicka på Miljöpå kuduhanteringswebbplatsen.
Hitta värdet för WEBSITE_AUTH_SIGNING_KEY.

Använd signeringsnyckeln för parametern authSigningKey i din lokala programkonfiguration. Din mobila serverdel är nu utrustad för att verifiera token när den körs lokalt, vilket klienten hämtar token från den molnbaserade slutpunkten.

Dela via