De ASP.NET Framework SDK voor Azure Mobile Apps gebruiken

In dit onderwerp wordt beschreven hoe u de SDK voor de .NET-back-endserver gebruikt in belangrijke scenario's Azure-app Service Mobile Apps. Met de Azure Mobile Apps SDK kunt u werken met mobiele clients vanuit uw ASP.NET-toepassing.

Een back-end voor Azure Mobile Apps ASP.NET Framework maken

U kunt een ASP.NET Framework-app maken met Visual Studio 2019.

• Kies de sjabloon ASP.NET Web Application (.NET Framework ). Als u problemen ondervindt bij het vinden van deze sjabloon, selecteert u C#, Alle platforms en web.
• Nadat u een naam en locatie voor de toepassing hebt geselecteerd, selecteert u de web-API-projectsjabloon . De juiste verzameling basisservices voor uw toepassing wordt geïnstalleerd.

De SDK downloaden en initialiseren

De SDK is beschikbaar op NuGet.org en biedt de basisfunctionaliteit die nodig is om aan de slag te gaan met Azure Mobile Apps. Het pakket installeren:

1. Klik met de rechtermuisknop op het project en selecteer NuGet-pakketten beheren....
2. Voer Microsoft.Azure.Mobile.Server op het tabblad Bladeren het zoekvak in en druk op Enter.
3. Selecteer het Microsoft.Azure.Mobile.Server.Quickstart pakket.
4. Klik op Install.
5. Volg de aanwijzingen om de installatie te voltooien.

Herhaal het proces dat u ook wilt installeren Microsoft.Owin.Host.SystemWeb .

Het serverproject initialiseren

Een Azure Mobile Apps-serverproject wordt geïnitialiseerd die vergelijkbaar is met andere ASP.NET Framework-projecten; door een OWIN Startup-klasse op te maken. Een OWIN-opstartklasse toevoegen:

1. Klik met de rechtermuisknop op het project en selecteer Nieuw item toevoegen>

2. Selecteer Web>Algemeen en selecteer vervolgens de OWIN-opstartklassesjabloon.

3. Voer de naam in als opstartnaam Startup.cs .

4. De inhoud van het Startup.cs bestand moet vergelijkbaar zijn met de volgende code:

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

   De OwinStartupnaamruimte en de klassenaam verschillen, afhankelijk van uw project. In het bijzonder moet u de inhoud van de Configuration() methode vervangen en de using instructies dienovereenkomstig aanpassen.

Als u afzonderlijke functies wilt inschakelen, moet u extensiemethoden aanroepen op het MobileAppConfiguration-object voordat u ApplyTo aanroept. Met de volgende code worden bijvoorbeeld de standaardroutes toegevoegd aan alle API-controllers die het kenmerk [MobileAppController] hebben tijdens de initialisatie:

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

De volgende installatie wordt beschouwd als een 'normaal' gebruik waarmee zowel tabel- als API-controllers met behulp van Entity Framework toegang krijgen tot een SQL-service.

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

De gebruikte extensiemethoden zijn:

• AddMobileAppHomeController() biedt de standaard startpagina van Azure Mobile Apps.
• MapApiControllers() biedt aangepaste API-mogelijkheden voor WebAPI-controllers die zijn ingericht met het [MobileAppController] kenmerk.
• AddTables() biedt een toewijzing van de /tables eindpunten aan tabelcontrollers.
• AddTablesWithEntityFramework() is een korte hand voor het toewijzen van de /tables eindpunten met behulp van op Entity Framework gebaseerde controllers.
• MapLegacyCrossDomainController() biedt standaard CORS-headers voor lokale ontwikkeling.

SDK-extensies

De volgende op NuGet gebaseerde uitbreidingspakketten bieden verschillende mobiele functies die door uw toepassing kunnen worden gebruikt. U schakelt extensies in tijdens de initialisatie met behulp van het MobileAppConfiguration-object .

• Microsoft.Azure.Mobile.Server.Quickstart ondersteunt de basisinstellingen voor mobiele apps. Toegevoegd aan de configuratie door de UseDefaultConfiguration-extensiemethode aan te roepen tijdens de initialisatie. Deze extensie omvat de volgende extensies: Meldingen, Verificatie, Entiteit, Tabellen, Meerdere domeinen en Thuispakketten.
• Microsoft.Azure.Mobile.Server.Home implementeert de standaardpagina van deze mobiele app voor de hoofdmap van de website. Voeg toe aan de configuratie door de extensiemethode AddMobileAppHomeController aan te roepen.
• Microsoft.Azure.Mobile.Server.Tables bevat klassen voor het werken met gegevens en het instellen van de gegevenspijplijn. Voeg deze toe aan de configuratie door de extensiemethode AddTables aan te roepen.
• Met Microsoft.Azure.Mobile.Server.Entity kan het Entity Framework toegang krijgen tot gegevens in de SQL Database. Voeg deze toe aan de configuratie door de extensiemethode AddTablesWithEntityFramework aan te roepen.
• Microsoft.Azure.Mobile.Server.Authentication maakt verificatie mogelijk en stelt de OWIN-middleware in die wordt gebruikt om tokens te valideren. Voeg toe aan de configuratie door addAppServiceAuthentication en IAppBuilder aan te roepen.UseAppServiceAuthentication-extensiemethoden.
• Microsoft.Azure.Mobile.Server.Notifications maakt pushmeldingen mogelijk en definieert een eindpunt voor pushregistratie. Voeg toe aan de configuratie door de extensiemethode AddPushNotifications aan te roepen.
• Microsoft.Azure.Mobile.Server.CrossDomain maakt een controller die gegevens levert aan verouderde webbrowsers vanuit uw mobiele app. Voeg toe aan de configuratie door de extensiemethode MapLegacyCrossDomainController aan te roepen.
• Microsoft.Azure.Mobile.Server.Login biedt de AppServiceLoginHandler.CreateToken() methode, een statische methode die wordt gebruikt tijdens aangepaste verificatiescenario's.

Het serverproject publiceren

In deze sectie ziet u hoe u uw .NET-back-endproject publiceert vanuit Visual Studio. Er zijn andere methoden waarmee u uw toepassing kunt publiceren. Zie de documentatie van Azure-app Service voor meer informatie.

1. Bouw in Visual Studio het project opnieuw om NuGet-pakketten te herstellen.
2. Klik in Solution Explorer met de rechtermuisknop op het project en klik op Publiceren.
3. Als u dit project nog niet eerder hebt gepubliceerd, configureert u publiceren.
   • Selecteer Azure voor het doel.
   • Selecteer Azure-app Service (Windows) voor het specifieke doel.
   • Selecteer het App Service-exemplaar waarnaar u wilt implementeren. Als u er nog geen hebt, gebruikt u deze + om er een te maken.
   • Klik op Voltooien.
4. Als u nog geen SQL-database hebt gekoppeld, klikt u op Configureren naast de SQL Database.
   • Azure SQL Database selecteren
   • Selecteer uw database. Als u nog geen database hebt of een andere wilt gebruiken, klikt u op de + knop om een nieuwe database en server te maken.
   • Voer MS_TableConnectionString de naam van de database verbindingsreeks in. Vul de gebruikersnaam en het wachtwoord in de opgegeven vakken in.
   • Klik op Voltooien
5. Klik op Publiceren

Het duurt enige tijd om naar Azure te publiceren. Zie de Visual Studio-documentatie voor meer informatie.

Een tabelcontroller definiëren

Definieer een tabelcontroller om een SQL-tabel beschikbaar te maken voor mobiele clients. Voor het configureren van een tabelcontroller zijn drie stappen vereist:

1. Maak een DTO-klasse (Data Transfer Object).
2. Configureer een tabelreferentie in de klasse Mobile DbContext.
3. Maak een tabelcontroller.

Een DTO (Data Transfer Object) is een gewoon C#-object dat overgaat van EntityData. Voorbeeld:

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

De DTO wordt gebruikt om de tabel in de SQL-database te definiëren. Als u de databasevermelding wilt maken, voegt u een DbSet<> eigenschap toe aan het bestand dat DbContext u gebruikt:

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

Maak ten slotte een nieuwe controller:

1. Klik met de rechtermuisknop op de Controllers map.

2. Web-API-web-API>2-controller selecteren - leeg

3. Voer een naam in voor de controller.

4. Vervang de inhoud van de nieuwe controller door de volgende code:

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

De paginagrootte van de tabel aanpassen

Standaard retourneert Azure Mobile Apps 50 records per aanvraag. Paginering zorgt ervoor dat de client hun UI-thread en de server niet te lang koppelt, waardoor een goede gebruikerservaring wordt gegarandeerd. Als u de paginagrootte van de tabel wilt wijzigen, verhoogt u de serverzijde 'toegestane querygrootte' en het paginaformaat aan de clientzijde De 'toegestane querygrootte' aan de serverzijde wordt aangepast met behulp van het EnableQuery kenmerk:

[EnableQuery(PageSize = 500)]

Zorg ervoor dat PageSize hetzelfde is of groter is dan de grootte die door de client is aangevraagd. Raadpleeg de specifieke client-PROCEDUREdocumentatie voor meer informatie over het wijzigen van het paginaformaat van de client.

Een aangepaste API-controller definiëren

De aangepaste API-controller biedt de meest eenvoudige functionaliteit voor de back-end van uw mobiele app door een eindpunt weer te geven. U kunt een mobiele API-controller registreren met behulp van het kenmerk [MobileAppController]. Het MobileAppController kenmerk registreert de route, stelt de JSON-serializer voor Mobile Apps in en schakelt clientversiecontrole in.

De inhoud van de aangepaste API-controller is:

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

Zodra het is geconfigureerd met het MobileAppController kenmerk, kunt u de aangepaste API op dezelfde manier definiëren als elke andere web-API.

Werken met verificatie

Azure Mobile Apps maakt gebruik van App Service-verificatie/-autorisatie om uw mobiele back-end te beveiligen. In deze sectie ziet u hoe u de volgende verificatiegerelateerde taken uitvoert in uw .NET-back-endserverproject:

• Verificatie toevoegen aan een serverproject
• Aangepaste verificatie gebruiken voor uw toepassing
• Geverifieerde gebruikersgegevens ophalen
• Toegang tot gegevens beperken voor geautoriseerde gebruikers

Verificatie toevoegen aan een serverproject

U kunt verificatie toevoegen aan uw serverproject door het MobileAppConfiguration-object uit te breiden en OWIN middleware te configureren.

1. Installeer in Visual Studio het pakket Microsoft.Azure.Mobile.Server.Authentication .

2. Voeg in het Startup.cs projectbestand de volgende coderegel toe aan het begin van de configuratiemethode :

   app.UseAppServiceAuthentication(config);
   

   Dit OWIN-middlewareonderdeel valideert tokens die zijn uitgegeven door de bijbehorende App Service-gateway.

3. Voeg het [Authorize] kenmerk toe aan een controller of methode waarvoor verificatie is vereist.

Aangepaste verificatie gebruiken voor uw toepassing

De aangepaste verificatie wordt weergegeven door een ApiController te maken en acties weer te geven en login uit te register voeren. De client moet een aangepaste gebruikersinterface gebruiken om de gegevens van de gebruiker te verzamelen. De informatie wordt vervolgens verzonden naar de API met een standaard HTTP POST-aanroep. Zodra de server de assertie valideert, wordt er een token uitgegeven met behulp van de AppServiceLoginHandler.CreateToken() methode. De ApiController mag het [MobileAppController] kenmerk niet gebruiken.

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

In het voorgaande voorbeeld LoginResult zijn LoginResultUser ze serialiseerbare objecten die de vereiste eigenschappen weergeven. De client verwacht dat aanmeldingsreacties worden geretourneerd als JSON-objecten van het formulier:

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

De AppServiceLoginHandler.CreateToken() methode bevat een doelgroep en een parameter voor verleners . Beide parameters worden ingesteld op de URL van de hoofdmap van uw toepassing, met behulp van het HTTPS-schema. Op dezelfde manier moet u secretKey instellen als de waarde van de ondertekeningssleutel van uw toepassing. Distribueer de ondertekeningssleutel niet in een client, omdat deze kan worden gebruikt om sleutels te munten en gebruikers te imiteren. U kunt de ondertekeningssleutel verkrijgen terwijl deze wordt gehost in App Service door te verwijzen naar de WEBSITE_AUTH_SIGNING_KEY omgevingsvariabele. Volg indien nodig in een lokale foutopsporingscontext de instructies in de sectie Lokale foutopsporing met verificatie om de sleutel op te halen en op te slaan als toepassingsinstelling.

Het uitgegeven token kan ook andere claims en een vervaldatum bevatten. Het uitgegeven token moet minimaal een onderwerpclaim (subclaim) bevatten.

U kunt de standaardclientmethode loginAsync() ondersteunen door de verificatieroute te overbelasten. Als de client aanroept client.loginAsync('custom'); om u aan te melden, moet uw route zijn /.auth/login/custom. U kunt de route voor de aangepaste verificatiecontroller instellen met behulp van MapHttpRoute():

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

Geverifieerde gebruikersgegevens ophalen

Wanneer een gebruiker wordt geverifieerd door App Service, hebt u toegang tot de toegewezen gebruikers-id en andere informatie in uw .NET-back-endcode. De gebruikersgegevens kunnen worden gebruikt voor het nemen van autorisatiebeslissingen in de back-end. Met de volgende code wordt de gebruikers-id verkregen die is gekoppeld aan een aanvraag:

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

De SID wordt afgeleid van de providerspecifieke gebruikers-id en is statisch voor een bepaalde gebruiker en aanmeldingsprovider. De SID is null voor ongeldige verificatietokens.

Met App Service kunt u ook specifieke claims aanvragen bij uw aanmeldingsprovider. Elke id-provider kan meer informatie bieden met behulp van de SDK van de id-provider. U kunt bijvoorbeeld de Facebook Graph API gebruiken voor informatie over vrienden. U kunt claims opgeven die worden aangevraagd op de blade provider in Azure Portal. Voor sommige claims is meer configuratie met de id-provider vereist.

Met de volgende code wordt de methode GetAppServiceIdentityAsync-extensie aangeroepen om de aanmeldingsreferenties op te halen, waaronder het toegangstoken dat nodig is om aanvragen te doen voor de 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();
}

Voeg een using-instructie toe om System.Security.Principal de getAppServiceIdentityAsync-extensiemethode op te geven.

Toegang tot gegevens beperken voor geautoriseerde gebruikers

In de vorige sectie hebben we laten zien hoe we de gebruikers-id van een geverifieerde gebruiker kunnen ophalen. U kunt de toegang tot gegevens en andere resources beperken op basis van deze waarde. Het toevoegen van een kolom userId aan tabellen en het filteren van de queryresultaten op basis van de gebruikers-id is bijvoorbeeld een eenvoudige manier om geretourneerde gegevens alleen te beperken tot geautoriseerde gebruikers. De volgende code retourneert alleen gegevensrijen wanneer de SID overeenkomt met de waarde in de kolom UserId in de tabel 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);

De Query() methode retourneert een IQueryable die kan worden bewerkt door LINQ voor het afhandelen van filters.

Fouten opsporen en problemen met de .NET Server SDK oplossen

Azure-app Service biedt verschillende foutopsporings- en probleemoplossingstechnieken voor ASP.NET toepassingen:

• Azure-app-service bewaken
• Diagnostische logboekregistratie inschakelen in Azure-app Service
• Problemen met een Azure-app-service in Visual Studio oplossen

Logboekregistratie

U kunt schrijven naar diagnostische logboeken van App Service met behulp van de standaard-ASP.NET tracering schrijven. Voordat u naar de logboeken kunt schrijven, moet u diagnostische gegevens inschakelen in uw Back-end van Azure Mobile Apps.

Diagnostische gegevens inschakelen en schrijven naar de logboeken:

1. Volg de stappen in Logboekregistratie van toepassingen inschakelen (Windows).

2. Voeg de volgende using-instructie toe in uw codebestand:

   using System.Web.Http.Tracing;
   

3. Maak als volgt een traceringsschrijver om vanuit de .NET-back-end naar de diagnostische logboeken te schrijven:

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

4. Publiceer uw serverproject opnieuw en open de back-end van Azure Mobile Apps om het codepad uit te voeren met de logboekregistratie.

5. Download en evalueer de logboeken, zoals beschreven in Access-logboekbestanden.

Lokale foutopsporing met verificatie

U kunt uw toepassing lokaal uitvoeren om wijzigingen te testen voordat u ze publiceert in de cloud. Voor de meeste Back-ends van Azure Mobile Apps drukt u op F5 in Visual Studio. Er zijn echter enkele extra overwegingen bij het gebruik van verificatie.

U moet een mobiele app in de cloud hebben geconfigureerd met App Service-verificatie/-autorisatie en uw client moet het cloudeindpunt hebben opgegeven als de alternatieve aanmeldingshost. Raadpleeg de documentatie voor uw clientplatform voor de specifieke stappen die nodig zijn.

Zorg ervoor dat op uw mobiele back-end Microsoft.Azure.Mobile.Server.Authentication is geïnstalleerd. Voeg vervolgens in de OWIN-opstartklasse van uw toepassing het volgende toe nadat MobileAppConfiguration deze is toegepast op uw HttpConfiguration:

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

In het voorgaande voorbeeld moet u de instellingen voor de toepassing authAudience en authIssuer in uw Web.config-bestand zo configureren dat deze de URL van de hoofdmap van uw toepassing zijn, met behulp van het HTTPS-schema. Op dezelfde manier moet u authSigningKey instellen als de waarde van de ondertekeningssleutel van uw toepassing.

De ondertekeningssleutel verkrijgen:

1. Navigeer naar uw app in Azure Portal
2. Klik op Extra>Kudu>Go.
3. Klik op de Kudu-beheersite op Omgeving.
4. Zoek de waarde voor WEBSITE_AUTH_SIGNING_KEY.

Gebruik de ondertekeningssleutel voor de parameter authSigningKey in de configuratie van uw lokale toepassing. Uw mobiele back-end is nu uitgerust om tokens te valideren wanneer deze lokaal wordt uitgevoerd, waardoor de client het token verkrijgt van het cloudeindpunt.