Azure Mobile Apps için ASP.NET Framework SDK'sını kullanma

  • Makale

Bu konu başlığında, önemli Azure Uygulaması Service Mobile Apps senaryolarında .NET arka uç sunucu SDK'sının nasıl kullanılacağı gösterilmektedir. Azure Mobile Apps SDK'sı, ASP.NET uygulamanızdaki mobil istemcilerle çalışmanıza yardımcı olur.

Uyarı

Bu makale, v5.0.0 kitaplığı tarafından değiştirilen v4.2.0 kitaplık sürümüne ilişkin bilgileri kapsar. En güncel bilgiler için en son sürümün makalesine bakın

Azure Mobile Apps ASP.NET Framework arka ucu oluşturma

Visual Studio 2019 kullanarak bir ASP.NET Framework uygulaması oluşturabilirsiniz.

  • ASP.NET Web Uygulaması (.NET Framework) şablonunu seçin. Bu şablonu bulma konusunda sorun yaşıyorsanız C#, Tüm platformlar ve Web'i seçin.
  • Uygulama için bir ad ve konum seçtikten sonra Web API proje şablonunu seçin. Uygulamanız için doğru temel hizmet koleksiyonu yüklenir.

SDK'yi indirme ve başlatma

SDK NuGet.org kullanılabilir ve Azure Mobile Apps'i kullanmaya başlamak için gereken temel işlevselliği sağlar. Paketi yüklemek için:

  1. Projeye sağ tıklayın, ardından NuGet Paketlerini Yönet...'i seçin.
  2. Gözat sekmesinde, arama kutusuna yazın Microsoft.Azure.Mobile.Server ve Enter tuşuna basın.
  3. Microsoft.Azure.Mobile.Server.Quickstart Paketi seçin.
  4. Yükle'ye tıklayın.
  5. Yüklemeyi tamamlamak için istemleri izleyin.

Yükleme Microsoft.Owin.Host.SystemWeb işlemini de yineleyin.

Dekont

veya System.IdentityModel.Jwtgibi Newtonsoft.JSON bağımlılıklar olarak kullanılan paketleri güncelleştirin. Bu paketlerin API'leri çoğu durumda değişmiştir ve artık ASP.NET Framework için Azure Mobile Apps ile uyumsuzdur.

Sunucu projesini başlatma

Azure Mobile Apps sunucu projesi, diğer ASP.NET Framework projelerine benzer şekilde başlatılır; bir OWIN Başlangıç sınıfı ekleyerek. OWIN Başlangıç sınıfı eklemek için:

  1. Projeye sağ tıklayın, ardından Yeni Öğe Ekle'yi>seçin

  2. Web>Genel'i ve ardından OWIN Başlangıç sınıfı şablonunu seçin.

  3. Adı başlangıç adı Startup.cs olarak girin.

  4. Dosyanın içeriği Startup.cs aşağıdaki koda benzer olmalıdır:

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

    OwinStartupProjenize bağlı olarak , ad alanı ve sınıf adı farklı olacaktır. Özellikle, yönteminin Configuration() içeriğini değiştirmeniz ve yönergeleri uygun şekilde ayarlamanız using gerekir.

Tek tek özellikleri etkinleştirmek için ApplyTo çağrısından önce MobileAppConfiguration nesnesinde uzantı yöntemlerini çağırmanız gerekir. Örneğin, aşağıdaki kod başlatma sırasında özniteliği [MobileAppController] olan tüm API denetleyicilerine varsayılan yolları ekler:

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

Aşağıdaki kurulum, Entity Framework kullanan tablo ve API denetleyicilerinin bir SQL hizmetine erişmesini sağlayan "normal" bir kullanım olarak kabul edilir.

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

Kullanılan uzantı yöntemleri şunlardır:

  • AddMobileAppHomeController() varsayılan Azure Mobile Apps giriş sayfasını sağlar.
  • MapApiControllers() özniteliğiyle [MobileAppController] dekore edilmiş WebAPI denetleyicileri için özel API özellikleri sağlar.
  • AddTables() , uç noktaların /tables tablo denetleyicilerine eşlemini sağlar.
  • AddTablesWithEntityFramework() , Entity Framework tabanlı denetleyiciler kullanarak uç noktaları eşlemek /tables için kısa bir adımdır.
  • MapLegacyCrossDomainController() yerel geliştirme için standart CORS üst bilgileri sağlar.

SDK uzantıları

Aşağıdaki NuGet tabanlı uzantı paketleri, uygulamanız tarafından kullanılabilecek çeşitli mobil özellikler sağlar. Başlatma sırasında MobileAppConfiguration nesnesini kullanarak uzantıları etkinleştirirsiniz.

Sunucu projesini yayımlama

Bu bölümde, .NET arka uç projenizi Visual Studio'dan nasıl yayımlayabileceğiniz gösterilmektedir. Uygulamanızı yayımlayabileceğiniz başka yöntemler de vardır. Daha fazla bilgi için Azure Uygulaması Hizmeti belgelerine bakın.

  1. Visual Studio'da NuGet paketlerini geri yüklemek için projeyi yeniden derleyin.
  2. Çözüm Gezgini'de projeye sağ tıklayın ve Yayımla'ya tıklayın.
  3. Bu projeyi daha önce yayımlamadıysanız yayımlamayı yapılandıracaksınız.
    • Hedef için Azure'ı seçin.
    • Belirli bir hedef için Azure Uygulaması Hizmeti 'ni (Windows) seçin.
    • Dağıtmak istediğiniz app service örneğini seçin. Yoksa, oluşturmak için öğesini + kullanın.
    • Finish (Son) düğmesine tıklayın.
  4. Daha önce bir SQL veritabanına bağlanmadıysanız, SQL Veritabanı yanındaki Yapılandır'a tıklayın.
    • Azure SQL Veritabanı seçin
    • Veritabanınızı seçin. Bir veritabanınız yoksa veya farklı bir veritabanı kullanmak istiyorsanız, yeni bir veritabanı ve sunucu oluşturmak için öğesine tıklayın + .
    • Veritabanı bağlantı dizesi adı olarak girinMS_TableConnectionString. Sağlanan kutulara kullanıcı adını ve parolayı girin.
    • Son’a tıklayın
  5. Yayımla'ya tıklayın

Azure'da yayımlamak biraz zaman alır. Daha fazla bilgi için Visual Studio belgelerine bakın.

Tablo denetleyicisi tanımlama

Sql tablosunu mobil istemcilere göstermek için Tablo Denetleyicisi tanımlayın. Tablo Denetleyicisi'ni yapılandırmak için üç adım gerekir:

  1. Veri Aktarım Nesnesi (DTO) sınıfı oluşturun.
  2. Mobile DbContext sınıfında bir tablo başvurusu yapılandırın.
  3. Tablo denetleyicisi oluşturma.

Veri Aktarım Nesnesi (DTO), öğesinden EntityDatadevralan düz bir C# nesnesidir. Örneğin:

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

DTO, SQL veritabanında tabloyu tanımlamak için kullanılır. Veritabanı girdisini oluşturmak için, kullanmakta DbContext olduğunuz öğesine bir DbSet<> özellik ekleyin:

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

Son olarak yeni bir denetleyici oluşturun:

  1. Klasöre Controllers sağ tıklayın.

  2. Web API'si Web API>2 Denetleyicisi - Boş'ı seçin

  3. Denetleyici için bir ad girin.

  4. Yeni denetleyicinin içeriğini aşağıdaki kodla değiştirin:

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

Tablo sayfalama boyutunu ayarlama

Azure Mobile Apps varsayılan olarak istek başına 50 kayıt döndürür. Disk belleği, istemcinin kullanıcı arabirimi iş parçacığını veya sunucuyu çok uzun süre bağlamamasını sağlayarak iyi bir kullanıcı deneyimi sağlar. Tablo sayfalama boyutunu değiştirmek için sunucu tarafı "izin verilen sorgu boyutu" ve istemci tarafı sayfa boyutunu artırın Sunucu tarafı "izin verilen sorgu boyutu" özniteliği kullanılarak EnableQuery ayarlanır:

[EnableQuery(PageSize = 500)]

PageSize'ın istemci tarafından istenen boyuttan aynı veya daha büyük olduğundan emin olun. İstemci sayfası boyutunu değiştirme hakkında ayrıntılı bilgi için belirli istemci HOWTO belgelerine bakın.

Özel API denetleyicisi tanımlama

Özel API denetleyicisi, bir uç noktayı kullanıma sunarak Mobil Uygulama arka ucunuza en temel işlevleri sağlar. [MobileAppController] özniteliğini kullanarak mobile özgü bir API denetleyicisi kaydedebilirsiniz. MobileAppController özniteliği yolu kaydeder, Mobile Apps JSON seri hale getiricisini ayarlar ve istemci sürümü denetimini açar.

Özel API denetleyicisinin içeriği şunlardır:

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

özniteliğiyle MobileAppController yapılandırıldıktan sonra, özel API'yi diğer Web API'leriyle aynı şekilde tanımlayabilirsiniz.

Kimlik doğrulaması ile çalışma

Azure Mobile Apps, mobil arka ucunuzun güvenliğini sağlamak için App Service Kimlik Doğrulaması / Yetkilendirme kullanır. Bu bölümde, .NET arka uç sunucu projenizde kimlik doğrulamasıyla ilgili aşağıdaki görevlerin nasıl gerçekleştirebileceğiniz gösterilmektedir:

Sunucu projesine kimlik doğrulaması ekleme

MobileAppConfiguration nesnesini genişleterek ve OWIN ara yazılımını yapılandırarak sunucu projenize kimlik doğrulaması ekleyebilirsiniz.

  1. Visual Studio'da Microsoft.Azure.Mobile.Server.Authentication paketini yükleyin.

  2. Startup.cs Proje dosyasında Configuration yönteminin başına aşağıdaki kod satırını ekleyin:

    app.UseAppServiceAuthentication(config);

    Bu OWIN ara yazılım bileşeni, ilişkili App Service ağ geçidi tarafından verilen belirteçleri doğrular.

  3. özniteliğini [Authorize] kimlik doğrulaması gerektiren herhangi bir denetleyiciye veya yönteme ekleyin.

Uygulamanız için özel kimlik doğrulaması kullanma

Önemli

Özel kimlik doğrulamasını etkinleştirmek için önce Azure portalında App Service'iniz için bir sağlayıcı seçmeden App Service Kimlik Doğrulamasını etkinleştirmeniz gerekir. Bu, barındırıldığında ortam değişkenini WEBSITE_AUTH_SIGNING_KEY etkinleştirir.

App Service Kimlik Doğrulaması/Yetkilendirme sağlayıcılarından birini kullanmak istemiyorsanız, kendi oturum açma sisteminizi uygulayabilirsiniz. Kimlik doğrulama belirteci oluşturma konusunda yardımcı olması için Microsoft.Azure.Mobile.Server.Login paketini yükleyin. Kullanıcı kimlik bilgilerini doğrulamak için kendi kodunuzu sağlayın. Örneğin, veritabanındaki tuzlanmış ve karma parolalara karşı denetleyebilirsiniz. Aşağıdaki örnekte yöntemi isValidAssertion() (başka bir yerde tanımlanmıştır) bu denetimlerden sorumludur.

Özel kimlik doğrulaması bir ApiController oluşturularak, kullanıma sunulur ve eylemler kullanıma registerlogin sunulur. İstemci, kullanıcıdan bilgi toplamak için özel bir kullanıcı arabirimi kullanmalıdır. Daha sonra bilgiler standart bir HTTP POST çağrısıyla API'ye gönderilir. Sunucu onaylamayı doğruladıktan sonra yöntemi kullanılarak AppServiceLoginHandler.CreateToken() bir belirteç verilir. ApiController özniteliğini [MobileAppController] kullanmamalıdır.

Örnek login bir eylem:

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

Yukarıdaki örnekte LoginResult ve LoginResultUser gerekli özellikleri ortaya seren serileştirilebilir nesnelerdir. İstemci, oturum açma yanıtlarının formun JSON nesneleri olarak döndürülmesini bekler:

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

yöntemi bir AppServiceLoginHandler.CreateToken()hedef kitle ve veren parametresi içerir. Bu parametrelerin her ikisi de HTTPS şeması kullanılarak uygulama kökünüzün URL'sine ayarlanır. Benzer şekilde secretKey değerini uygulamanızın imzalama anahtarının değeri olarak ayarlamanız gerekir. Anahtarları dağıtmak ve kullanıcıların kimliğine bürünmek için kullanılabildiğinden, imzalama anahtarını bir istemcide dağıtmayın. App Service'te barındırırken, ortam değişkenine WEBSITE_AUTH_SIGNING_KEY başvurarak imzalama anahtarını alabilirsiniz. Yerel hata ayıklama bağlamında gerekirse, anahtarı almak ve bir uygulama ayarı olarak depolamak için Kimlik doğrulamasıyla yerel hata ayıklama bölümündeki yönergeleri izleyin.

Verilen belirteç başka talepler ve bir süre sonu tarihi de içerebilir. En düşük düzeyde, verilen belirtecin bir konu (alt) talebi içermesi gerekir.

Kimlik doğrulama yolunu aşırı yükleyerek standart istemci loginAsync() yöntemini destekleyebilirsiniz. İstemci oturum açmak için çağırırsa client.loginAsync('custom'); , yolunuz olmalıdır /.auth/login/custom. kullanarak özel kimlik doğrulama denetleyicisinin MapHttpRoute()yolunu ayarlayabilirsiniz:

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

Bahşiş

Yaklaşımın loginAsync() kullanılması, kimlik doğrulama belirtecinin hizmete yapılan sonraki her çağrıya eklenmesini sağlar.

Kimliği doğrulanmış kullanıcı bilgilerini alma

Bir kullanıcının kimliği App Service tarafından doğrulandığında, atanan kullanıcı kimliğine ve .NET arka uç kodunuzdaki diğer bilgilere erişebilirsiniz. Kullanıcı bilgileri, arka uçta yetkilendirme kararları vermek için kullanılabilir. Aşağıdaki kod, bir istekle ilişkili kullanıcı kimliğini elde eder:

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

SID, sağlayıcıya özgü kullanıcı kimliğinden türetilir ve belirli bir kullanıcı ve oturum açma sağlayıcısı için statiktir. Geçersiz kimlik doğrulama belirteçleri için SID null.

App Service ayrıca oturum açma sağlayıcınızdan belirli talepler istemenizi sağlar. Her kimlik sağlayıcısı, kimlik sağlayıcısı SDK'sını kullanarak daha fazla bilgi sağlayabilir. Örneğin, arkadaş bilgileri için Facebook Graph API'sini kullanabilirsiniz. İstenen talepleri Azure portalındaki sağlayıcı dikey penceresinde belirtebilirsiniz. Bazı talepler, kimlik sağlayıcısında daha fazla yapılandırma gerektirir.

Aşağıdaki kod, Facebook Graph API'sine yönelik isteklerde bulunmak için gereken erişim belirtecini içeren oturum açma kimlik bilgilerini almak için GetAppServiceIdentityAsync uzantısı yöntemini çağırır:

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

GetAppServiceIdentityAsync uzantısı yöntemini sağlamak için için System.Security.Principal bir using deyimi ekleyin.

Yetkili kullanıcılar için veri erişimini kısıtlama

Önceki bölümde kimliği doğrulanmış bir kullanıcının kullanıcı kimliğini nasıl alacağımızı gösterdik. Verilere ve diğer kaynaklara erişimi bu değere göre kısıtlayabilirsiniz. Örneğin, tablolara userId sütunu eklemek ve sorgu sonuçlarını kullanıcı kimliğine göre filtrelemek, döndürülen verileri yalnızca yetkili kullanıcılarla sınırlamanın basit bir yoludur. Aşağıdaki kod yalnızca SID, TodoItem tablosundaki UserId sütunundaki değerle eşleştiğinde veri satırları döndürür:

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

yöntemi, Query() filtrelemeyi işlemek için LINQ tarafından işlenebilen bir IQueryable döndürür.

.NET Server SDK'sının hatalarını ayıklama ve sorunlarını giderme

Azure Uygulaması Hizmeti, ASP.NET uygulamaları için çeşitli hata ayıklama ve sorun giderme teknikleri sağlar:

Günlük Kaydı

Standart ASP.NET izleme yazısını kullanarak App Service tanılama günlüklerine yazabilirsiniz. Günlüklere yazabilmeniz için önce Azure Mobile Apps arka ucunuzda tanılamayı etkinleştirmeniz gerekir.

Tanılamayı etkinleştirmek ve günlüklere yazmak için:

  1. Uygulama günlüğünü etkinleştirme (Windows) içindeki adımları izleyin.

  2. Kod dosyanıza aşağıdaki using deyimini ekleyin:

    using System.Web.Http.Tracing;

  3. .NET arka uçtan tanılama günlüklerine yazmak için aşağıdaki gibi bir izleme yazıcısı oluşturun:

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

  4. Sunucu projenizi yeniden yayımlayın ve günlük kaydıyla kod yolunu yürütmek için Azure Mobile Apps arka ucuna erişin.

  5. Access günlük dosyalarında açıklandığı gibi günlükleri indirin ve değerlendirin.

Kimlik doğrulaması ile yerel hata ayıklama

Değişiklikleri bulutta yayımlamadan önce test etmek için uygulamanızı yerel olarak çalıştırabilirsiniz. Çoğu Azure Mobile Apps arka ucu için Visual Studio'dayken F5 tuşuna basın. Ancak, kimlik doğrulaması kullanılırken dikkat edilmesi gereken bazı ek noktalar vardır.

App Service Kimlik Doğrulaması/Yetkilendirme yapılandırılmış bulut tabanlı bir mobil uygulamanız ve istemcinizde alternatif oturum açma ana bilgisayarı olarak belirtilen bulut uç noktası olmalıdır. Gerekli belirli adımlar için istemci platformunuzun belgelerine bakın.

Mobil arka uçta Microsoft.Azure.Mobile.Server.Authentication'ın yüklü olduğundan emin olun. Ardından, uygulamanızın OWIN başlangıç sınıfına aşağıdakini ekleyin:MobileAppConfigurationHttpConfiguration

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

Yukarıdaki örnekte, Web.config dosyanızdaki authAudience ve authIssuer uygulama ayarlarını, HTTPS düzenini kullanarak uygulama kökünüzün URL'si olacak şekilde yapılandırmanız gerekir. Benzer şekilde, authSigningKey değerini uygulamanızın imzalama anahtarının değeri olarak ayarlamanız gerekir.

İmzalama anahtarını almak için:

  1. Azure portalında uygulamanıza gidin
  2. Araçlar>Kudu Go'ya> tıklayın.
  3. Kudu Yönetimi sitesinde Ortam'a tıklayın.
  4. değerini WEBSITE_AUTH_SIGNING_KEYbulun.

Yerel uygulama yapılandırmanızda authSigningKey parametresi için imzalama anahtarını kullanın. Mobil arka ucunuz artık yerel olarak çalışırken belirteçleri doğrulayacak şekilde donatılmıştır ve istemci bu belirteci bulut tabanlı uç noktadan alır.