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

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.

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 plattformar och Webben.
• När du har valt ett namn och en plats för programmet väljer du projektmallen Webb-API . Rätt samling bastjänster för ditt program installeras.

Ladda ned och initiera SDK

SDK:et är tillgängligt på NuGet.org och 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:

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

Upprepa även den process som ska installeras Microsoft.Owin.Host.SystemWeb .

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:

1. Högerklicka på projektet och välj sedan Lägg till>nytt objekt

2. Välj Webb>allmänt och välj sedan klassmallen OWIN Startup.

3. Ange namnet Startup.cs som startnamn.

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

   Namnrymden OwinStartup, och klassnamnet kommer att vara olika, beroende på ditt projekt. Mer specifikt bör du ersätta innehållet i Configuration() metoden och justera direktiven using i enlighet med detta.

Om du vill aktivera enskilda funktioner måste du anropa tilläggsmetoder i MobileAppConfiguration-objektet 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 [MobileAppController] attributet .
• AddTables() tillhandahåller en mappning av /tables slutpunkterna till tabellkontrollanter.
• AddTablesWithEntityFramework() är en kort hand för att mappa /tables slutpunkterna 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. Lades till i konfigurationen genom att anropa tilläggsmetoden UseDefaultConfiguration 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 standardinställningen att den här mobilappen är igång för webbplatsroten. Lägg till i konfigurationen genom att anropa tilläggsmetoden AddMobileAppHomeController .
• 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 tilläggsmetoden AddTables .
• 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 tilläggsmetoden AddTablesWithEntityFramework .
• Microsoft.Azure.Mobile.Server.Authentication Möjliggör autentisering och konfigurerar OWIN-mellanprogrammet som används för att verifiera token. Lägg till i konfigurationen genom att anropa AddAppServiceAuthentication och IAppBuilder.Använd tilläggsmetoder förAppServiceAuthentication .
• Microsoft.Azure.Mobile.Server.Notifications Aktiverar push-meddelanden och definierar en push-registreringsslutpunkt. Lägg till i konfigurationen genom att anropa tilläggsmetoden AddPushNotifications .
• 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 metoden MapLegacyCrossDomainController-tillägg .
• Microsoft.Azure.Mobile.Server.Login Tillhandahåller AppServiceLoginHandler.CreateToken() metoden, 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 Dokumentation om Azure App Service.

1. I Visual Studio återskapar du projektet för att återställa NuGet-paket.
2. Högerklicka på projektet i Solution Explorer och klicka på Publicera.
3. 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 en använder du för + att skapa en.
   • Klicka på Finish.
4. 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å database anslutningssträng. Fyll i användarnamnet och lösenordet i de angivna rutorna.
   • Klicka på Slutför
5. 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:

1. Skapa en DTO-klass (Data Transfer Object).
2. Konfigurera en tabellreferens i klassen Mobile DbContext.
3. 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 DbSet<> egenskap som 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:

1. Högerklicka på Controllers mappen.

2. Välj Web API>Web API 2 Controller – tom

3. Ange ett namn på kontrollanten.

4. 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 växlingsstorleken för tabellen ökar du serversidans "tillåtna frågestorlek" och sidstorleken på klientsidan Serversidans "tillåtna EnableQuery frågestorlek" justeras med hjälp av attributet:

[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 MobileAppController attributet 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ägga till autentisering i ett serverprojekt
• Använda 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 Objektet MobileAppConfiguration och konfigurera OWIN-mellanprogram.

1. Installera paketet Microsoft.Azure.Mobile.Server.Authentication i Visual Studio.

2. Startup.cs I projektfilen lägger du till följande kodrad i början av konfigurationsmetoden:

   app.UseAppServiceAuthentication(config);
   

   Den här OWIN-mellanprogramskomponenten validerar token som utfärdats av den associerade App Service-gatewayen.

3. [Authorize] Lägg till attributet till valfri kontrollant eller metod som kräver autentisering.

Använda anpassad autentisering för ditt program

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 AppServiceLoginHandler.CreateToken() metoden . ApiController ska inte använda attributet [MobileAppController] .

Ett exempel login på en å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 LoginResult och LoginResultUser är 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ärdarparameter. 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 som 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 WEBSITE_AUTH_SIGNING_KEY referera till 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 ämnesanspråk (under).

Du kan stödja standardklientmetoden loginAsync() 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" });

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ägget för att hämta inloggningsuppgifterna, som inkluderar den åtkomsttoken som krä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 för System.Security.Principal att ange metoden GetAppServiceIdentityAsync-tillägg .

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:

• Övervaka Azure App Service
• Aktivera diagnostikloggning i Azure App Service
• Felsöka en Azure App Service i Visual Studio

Loggning

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:

1. Följ stegen i Aktivera programloggning (Windows).

2. Lägg till följande instruktion med hjälp av i kodfilen:

   using System.Web.Http.Tracing;
   

3. 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");
   

4. Publicera om serverprojektet och få åtkomst till Azure Mobile Apps-serverdelen för att köra kodsökvägen med loggningen.

5. 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. I programmets OWIN-startklass lägger du sedan till följande efter MobileAppConfiguration att ha tillämpats på :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 programinställningarna authAudience och authIssuer i web.config-filen så att de är url:en för programroten med hjälp av HTTPS-schemat. På samma sätt bör du ange authSigningKey som värdet för ditt programs signeringsnyckel.

Så här hämtar du signeringsnyckeln:

1. Navigera till din app i Azure-portalen
2. Klicka på Verktyg>Kudu>Go.
3. Klicka på Miljö på kuduhanteringswebbplatsen.
4. 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.