Razor Rute halaman dan konvensi aplikasi di ASP.NET Core

Pelajari cara menggunakan konvensi penyedia rute halaman dan model aplikasi untuk mengontrol perutean halaman, penemuan, dan pemrosesan di Razor aplikasi Pages.

Untuk menentukan rute halaman, tambahkan segmen rute, atau tambahkan parameter ke rute, gunakan arahan halaman @page . Untuk informasi selengkapnya, lihat Rute kustom.

Ada kata yang dipesan yang tidak dapat digunakan sebagai segmen rute atau nama parameter. Untuk informasi selengkapnya, lihat Perutean: Nama perutean yang dicadangkan.

Melihat atau mengunduh kode sampel (cara mengunduh)

Skenario	Sampel menunjukkan
Konvensi model Conventions.Add IPageRouteModelConvention IPageApplicationModelConvention IPageHandlerModelConvention	Tambahkan templat rute dan header ke halaman aplikasi.
Konvensi tindakan rute halaman AddFolderRouteModelConvention AddPageRouteModelConvention AddPageRoute	Tambahkan templat rute ke halaman dalam folder dan ke satu halaman.
Konvensi tindakan model halaman AddFolderApplicationModelConvention AddPageApplicationModelConvention ConfigureFilter (kelas filter, ekspresi lambda, atau pabrik filter)	Tambahkan header ke halaman dalam folder, tambahkan header ke satu halaman, dan konfigurasikan pabrik filter untuk menambahkan header ke halaman aplikasi.

Razor Konvensi halaman dikonfigurasi menggunakan AddRazorPages kelebihan beban yang mengonfigurasi RazorPagesOptions. Contoh konvensi berikut dijelaskan nanti dalam topik ini:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages(options =>
    {
        options.Conventions.Add( ... );
        options.Conventions.AddFolderRouteModelConvention(
            "/OtherPages", model => { ... });
        options.Conventions.AddPageRouteModelConvention(
            "/About", model => { ... });
        options.Conventions.AddPageRoute(
            "/Contact", "TheContactPage/{text?}");
        options.Conventions.AddFolderApplicationModelConvention(
            "/OtherPages", model => { ... });
        options.Conventions.AddPageApplicationModelConvention(
            "/About", model => { ... });
        options.Conventions.ConfigureFilter(model => { ... });
        options.Conventions.ConfigureFilter( ... );
    });
}

Urutan rute

Rute menentukan Order untuk pemrosesan (pencocokan rute).

Urutan rute	Perilaku
-1	Rute diproses sebelum rute lain diproses.
0	Urutan tidak ditentukan (nilai default). Tidak menetapkan Order (Order = null) default rute Order ke 0 (nol) untuk diproses.
1, 2, … n	Menentukan urutan pemrosesan rute.

Pemrosesan rute ditetapkan berdasarkan konvensi:

• Rute diproses secara berurutan (-1, 0, 1, 2, ... n).
• Ketika rute memiliki rute yang sama Order, rute yang paling spesifik dicocokkan terlebih dahulu diikuti oleh rute yang kurang spesifik.
• Saat rute dengan parameter yang sama Order dan jumlah parameter yang sama cocok dengan URL permintaan, rute diproses dalam urutan yang ditambahkan ke PageConventionCollection.

Jika memungkinkan, hindari bergantung pada urutan pemrosesan rute yang ditetapkan. Umumnya, perutean memilih rute yang benar dengan pencocokan URL. Jika Anda harus mengatur properti rute Order untuk merutekan permintaan dengan benar, skema perutean aplikasi mungkin membingungkan bagi klien dan rapuh untuk dipertahankan. Cari untuk menyederhanakan skema perutean aplikasi. Aplikasi sampel memerlukan urutan pemrosesan rute eksplisit untuk menunjukkan beberapa skenario perutean menggunakan satu aplikasi. Namun, Anda harus mencoba menghindari praktik pengaturan rute Order di aplikasi produksi.

Razor Perutean halaman dan perutean pengontrol MVC berbagi implementasi. Informasi tentang urutan rute dalam topik MVC tersedia di Tindakan perutean ke pengontrol: Mengurutkan rute atribut.

Konvensi model

Tambahkan delegasi untuk IPageConvention menambahkan konvensi model yang berlaku untuk Razor Pages.

Menambahkan konvensi model rute ke semua halaman

Gunakan Conventions untuk membuat dan menambahkan IPageRouteModelConvention ke kumpulan IPageConvention instans yang diterapkan selama konstruksi model rute halaman.

Aplikasi sampel berisi GlobalTemplatePageRouteModelConvention kelas untuk menambahkan {globalTemplate?} templat rute ke semua halaman di aplikasi:

using Microsoft.AspNetCore.Mvc.ApplicationModels;
namespace SampleApp.Conventions;

public class GlobalTemplatePageRouteModelConvention : IPageRouteModelConvention
{
    public void Apply(PageRouteModel model)
    {
        var selectorCount = model.Selectors.Count;
        for (var i = 0; i < selectorCount; i++)
        {
            var selector = model.Selectors[i];
            model.Selectors.Add(new SelectorModel
            {
                AttributeRouteModel = new AttributeRouteModel
                {
                    Order = 1,
                    Template = AttributeRouteModel.CombineTemplates(
                        selector.AttributeRouteModel!.Template, 
                        "{globalTemplate?}"),
                }
            });
        }
    }
}

Dalam kode sebelumnya:

• diteruskan PageRouteModel ke Apply metode .
• PageRouteModel.Selectors mendapatkan jumlah pemilih.
• SelectorModel Baru ditambahkan yang berisiAttributeRouteModel

Razor Opsi halaman, seperti menambahkan Conventions, ditambahkan saat Razor Halaman ditambahkan ke kumpulan layanan. Misalnya, lihat aplikasi sampel.

using Microsoft.AspNetCore.Mvc.ApplicationModels;
using Microsoft.EntityFrameworkCore;
using SampleApp.Conventions;
using SampleApp.Data;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
                                   options.UseInMemoryDatabase("InMemoryDb"));

builder.Services.AddRazorPages(options =>
   {
       options.Conventions.Add(new GlobalTemplatePageRouteModelConvention());

       options.Conventions.AddFolderRouteModelConvention("/OtherPages", model =>
       {
           var selectorCount = model.Selectors.Count;
           for (var i = 0; i < selectorCount; i++)
           {
               var selector = model.Selectors[i];
               model.Selectors.Add(new SelectorModel
               {
                   AttributeRouteModel = new AttributeRouteModel
                   {
                       Order = 2,
                       Template = AttributeRouteModel.CombineTemplates(
                           selector.AttributeRouteModel!.Template,
                           "{otherPagesTemplate?}"),
                   }
               });
           }
       });

       options.Conventions.AddPageRouteModelConvention("/About", model =>
       {
           var selectorCount = model.Selectors.Count;
           for (var i = 0; i < selectorCount; i++)
           {
               var selector = model.Selectors[i];
               model.Selectors.Add(new SelectorModel
               {
                   AttributeRouteModel = new AttributeRouteModel
                   {
                       Order = 2,
                       Template = AttributeRouteModel.CombineTemplates(
                           selector.AttributeRouteModel!.Template,
                           "{aboutTemplate?}"),
                   }
               });
           }
       });

   });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthorization();
app.MapRazorPages();
app.Run();

GlobalTemplatePageRouteModelConvention Pertimbangkan kelas:

using Microsoft.AspNetCore.Mvc.ApplicationModels;
namespace SampleApp.Conventions;

public class GlobalTemplatePageRouteModelConvention : IPageRouteModelConvention
{
    public void Apply(PageRouteModel model)
    {
        var selectorCount = model.Selectors.Count;
        for (var i = 0; i < selectorCount; i++)
        {
            var selector = model.Selectors[i];
            model.Selectors.Add(new SelectorModel
            {
                AttributeRouteModel = new AttributeRouteModel
                {
                    Order = 1,
                    Template = AttributeRouteModel.CombineTemplates(
                        selector.AttributeRouteModel!.Template, 
                        "{globalTemplate?}"),
                }
            });
        }
    }
}

Properti Order untuk AttributeRouteModel diatur ke 1. Ini memastikan perilaku pencocokan rute berikut di aplikasi sampel:

• Templat rute untuk TheContactPage/{text?} ditambahkan nanti dalam topik ini. Rute Contact Page memiliki urutan null default (Order = 0), sehingga cocok sebelum {globalTemplate?} templat rute yang memiliki Order = 1.

• {aboutTemplate?} Templat rute ditampilkan dalam kode sebelumnya. {aboutTemplate?} Templat diberikan Order dari 2. Ketika halaman Tentang diminta di /About/RouteDataValue, "RouteDataValue" dimuat ke dalam RouteData.Values["globalTemplate"] (Order = 1) dan bukan RouteData.Values["aboutTemplate"] (Order = 2) karena pengaturan Order properti.

• {otherPagesTemplate?} Templat rute ditampilkan dalam kode sebelumnya. {otherPagesTemplate?} Templat diberikan Order dari 2. Ketika halaman apa pun di folder Pages/OtherPages diminta dengan parameter rute:

• Misalnya: /OtherPages/Page1/xyz

• Nilai "xyz" data rute dimuat ke dalam RouteData.Values["globalTemplate"] (Order = 1).

• RouteData.Values["otherPagesTemplate"] dengan (Order = 2) tidak dimuat karena Order properti 2 memiliki nilai yang lebih tinggi.

Jika memungkinkan, jangan atur Order. Ketika Order tidak diatur, defaultnya ke Order = 0. Mengandalkan perutean untuk memilih rute yang benar daripada Order properti .

Minta halaman sampel About di localhost:{port}/About/GlobalRouteValue dan periksa hasilnya:

Aplikasi sampel menggunakan paket Rick.Docs.Samples.RouteInfo NuGet untuk menampilkan informasi perutean dalam output pengelogan. Menggunakan localhost:{port}/About/GlobalRouteValue, pencatat menampilkan permintaan, Order, dan templat yang digunakan:

info: SampleApp.Pages.AboutModel[0]
       /About/GlobalRouteValue   Order = 1 Template = About/{globalTemplate?}

Menambahkan konvensi model aplikasi ke semua halaman

Gunakan Conventions untuk membuat dan menambahkan IPageApplicationModelConvention ke kumpulan IPageConvention instans yang diterapkan selama konstruksi model aplikasi halaman.

Untuk menunjukkan ini dan konvensi lain nanti dalam topik, aplikasi sampel menyertakan AddHeaderAttribute kelas. Konstruktor kelas menerima name string dan values array string. Nilai-nilai ini digunakan dalam metodenya OnResultExecuting untuk mengatur header respons. Kelas lengkap ditampilkan di bagian Konvensi tindakan model halaman nanti dalam topik.

Aplikasi sampel menggunakan AddHeaderAttribute kelas untuk menambahkan header, GlobalHeader, ke semua halaman di aplikasi:

public class GlobalHeaderPageApplicationModelConvention 
    : IPageApplicationModelConvention
{
    public void Apply(PageApplicationModel model)
    {
        model.Filters.Add(new AddHeaderAttribute(
            "GlobalHeader", new string[] { "Global Header Value" }));
    }
}

Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseInMemoryDatabase("InMemoryDb"));

builder.Services.AddRazorPages(options =>
   {
       options.Conventions.Add(new GlobalTemplatePageRouteModelConvention());

       options.Conventions.Add(new GlobalHeaderPageApplicationModelConvention());

Minta halaman Tentang sampel di localhost:{port}/About dan periksa header untuk melihat hasilnya:

Menambahkan konvensi model handler ke semua halaman

Gunakan Conventions untuk membuat dan menambahkan IPageHandlerModelConvention ke kumpulan IPageConvention instans yang diterapkan selama konstruksi model handler halaman.

public class GlobalPageHandlerModelConvention
    : IPageHandlerModelConvention
{
    public void Apply(PageHandlerModel model)
    {
        // Access the PageHandlerModel
    }
}

Konvensi tindakan rute halaman

Penyedia model rute default yang berasal dari IPageRouteModelProvider memanggil konvensi yang dirancang untuk menyediakan titik ekstensibilitas untuk mengonfigurasi rute halaman.

Konvensi model rute folder

Gunakan AddFolderRouteModelConvention untuk membuat dan menambahkan IPageRouteModelConvention yang memanggil tindakan pada PageRouteModel untuk semua halaman di bawah folder yang ditentukan.

Aplikasi sampel menggunakan AddFolderRouteModelConvention untuk menambahkan {otherPagesTemplate?} templat rute ke halaman di folder OtherPages :

options.Conventions.AddFolderRouteModelConvention("/OtherPages", model =>
{
    var selectorCount = model.Selectors.Count;
    for (var i = 0; i < selectorCount; i++)
    {
        var selector = model.Selectors[i];
        model.Selectors.Add(new SelectorModel
        {
            AttributeRouteModel = new AttributeRouteModel
            {
                Order = 2,
                Template = AttributeRouteModel.CombineTemplates(
                    selector.AttributeRouteModel!.Template,
                    "{otherPagesTemplate?}"),
            }
        });
    }
});

Properti Order untuk AttributeRouteModel diatur ke 2. Ini memastikan bahwa templat untuk {globalTemplate?} (diatur sebelumnya dalam topik ke 1) diberikan prioritas untuk posisi nilai data rute pertama saat nilai rute tunggal disediakan. Jika halaman di folder Pages/OtherPages diminta dengan nilai parameter rute (misalnya, /OtherPages/Page1/RouteDataValue), "RouteDataValue" dimuat ke dalam RouteData.Values["globalTemplate"] (Order = 1) dan bukan RouteData.Values["otherPagesTemplate"] (Order = 2) karena pengaturan Order properti.

Jika memungkinkan, jangan atur Order, yang menghasilkan Order = 0. Mengandalkan perutean untuk memilih rute yang benar.

Minta halaman Page1 sampel di localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue dan periksa hasilnya:

Konvensi model rute halaman

Gunakan AddPageRouteModelConvention untuk membuat dan menambahkan IPageRouteModelConvention yang memanggil tindakan pada PageRouteModel halaman dengan nama yang ditentukan.

Aplikasi sampel menggunakan AddPageRouteModelConvention untuk menambahkan {aboutTemplate?} templat rute ke halaman Tentang:

options.Conventions.AddPageRouteModelConvention("/About", model =>
{
    var selectorCount = model.Selectors.Count;
    for (var i = 0; i < selectorCount; i++)
    {
        var selector = model.Selectors[i];
        model.Selectors.Add(new SelectorModel
        {
            AttributeRouteModel = new AttributeRouteModel
            {
                Order = 2,
                Template = AttributeRouteModel.CombineTemplates(
                    selector.AttributeRouteModel!.Template,
                    "{aboutTemplate?}"),
            }
        });
    }
});

Properti Order untuk AttributeRouteModel diatur ke 2. Ini memastikan bahwa templat untuk {globalTemplate?} (diatur sebelumnya dalam topik ke 1) diberikan prioritas untuk posisi nilai data rute pertama saat nilai rute tunggal disediakan. Jika halaman Tentang diminta dengan nilai parameter rute di /About/RouteDataValue, "RouteDataValue" dimuat ke dalam RouteData.Values["globalTemplate"] (Order = 1) dan bukan RouteData.Values["aboutTemplate"] (Order = 2) karena pengaturan Order properti.

Jika memungkinkan, jangan atur Order, yang menghasilkan Order = 0. Mengandalkan perutean untuk memilih rute yang benar.

Minta halaman Tentang sampel di localhost:{port}/About/GlobalRouteValue/AboutRouteValue dan periksa hasilnya:

Output pencatat menampilkan:

info: SampleApp.Pages.AboutModel[0]
       /About/GlobalRouteValue/AboutRouteValue   Order = 2 Template = About/{globalTemplate?}/{aboutTemplate?}

Menggunakan transformator parameter untuk menyesuaikan rute halaman

Lihat Transformer parameter.

Mengonfigurasi rute halaman

Gunakan AddPageRoute untuk mengonfigurasi rute ke halaman di jalur halaman yang ditentukan. Tautan yang dihasilkan ke halaman menggunakan rute yang ditentukan. AddPageRouteAddPageRouteModelConvention menggunakan untuk menetapkan rute.

Aplikasi sampel membuat rute ke /TheContactPage halaman ContactRazor :

options.Conventions.AddPageRoute("/Contact", "TheContactPage/{text?}");

Halaman Contact juga dapat dijangkau di /Contact1' melalui rute defaultnya.

Rute kustom aplikasi sampel ke Contact halaman memungkinkan segmen rute opsional text ({text?}). Halaman ini juga menyertakan segmen opsional ini dalam arahannya @page jika pengunjung mengakses halaman di rutenya /Contact :

@page "{text?}"
@model ContactModel
@{
    ViewData["Title"] = "Contact";
}

<h1>@ViewData["Title"]</h1>
<h2>@Model.Message</h2>

<address>
    One Microsoft Way<br>
    Redmond, WA 98052-6399<br>
    <abbr title="Phone">P:</abbr>
    425.555.0100
</address>

<address>
    <strong>Support:</strong> <a href="mailto:Support@example.com">Support@example.com</a><br>
    <strong>Marketing:</strong> <a href="mailto:Marketing@example.com">Marketing@example.com</a>
</address>

<p>@Model.RouteDataTextTemplateValue</p>

Perhatikan bahwa URL yang dihasilkan untuk tautan Kontak di halaman yang dirender mencerminkan rute yang diperbarui:

Contact Kunjungi halaman di rute biasa, , /Contactatau rute kustom, /TheContactPage. Jika Anda menyediakan segmen rute tambahan text , halaman menunjukkan segmen yang dikodekan HTML yang Anda sediakan:

Konvensi tindakan model halaman

Penyedia model halaman default yang menerapkan IPageApplicationModelProvider konvensi pemanggilan yang dirancang untuk menyediakan titik ekstensibilitas untuk mengonfigurasi model halaman. Konvensi ini berguna saat membangun dan memodifikasi skenario penemuan dan pemrosesan halaman.

Untuk contoh di bagian ini, aplikasi sampel menggunakan AddHeaderAttribute kelas, yang merupakan ResultFilterAttribute, yang menerapkan header respons:

public class AddHeaderAttribute : ResultFilterAttribute
{
    private readonly string _name;
    private readonly string[] _values;

    public AddHeaderAttribute(string name, string[] values)
    {
        _name = name;
        _values = values;
    }

    public override void OnResultExecuting(ResultExecutingContext context)
    {
        context.HttpContext.Response.Headers.Add(_name, _values);
        base.OnResultExecuting(context);
    }
}

Menggunakan konvensi, sampel menunjukkan cara menerapkan atribut ke semua halaman dalam folder dan ke satu halaman.

Konvensi model aplikasi folder

Gunakan AddFolderApplicationModelConvention untuk membuat dan menambahkan IPageApplicationModelConvention yang memanggil tindakan pada PageApplicationModel instans untuk semua halaman di bawah folder yang ditentukan.

Sampel menunjukkan penggunaan AddFolderApplicationModelConvention dengan menambahkan header, OtherPagesHeader, ke halaman di dalam folder OtherPages aplikasi:

options.Conventions.AddFolderApplicationModelConvention("/OtherPages", model =>
{
    model.Filters.Add(new AddHeaderAttribute(
        "OtherPagesHeader", new string[] { "OtherPages Header Value" }));
});

Minta halaman Page1 sampel di localhost:5000/OtherPages/Page1 dan periksa header untuk melihat hasilnya:

Konvensi model aplikasi halaman

Gunakan AddPageApplicationModelConvention untuk membuat dan menambahkan IPageApplicationModelConvention yang memanggil tindakan pada PageApplicationModel halaman dengan nama yang ditentukan.

Sampel menunjukkan penggunaan AddPageApplicationModelConvention dengan menambahkan header, AboutHeader, ke halaman Tentang:

options.Conventions.AddPageApplicationModelConvention("/About", model =>
{
    model.Filters.Add(new AddHeaderAttribute(
        "AboutHeader", new string[] { "About Header Value" }));
});

Minta halaman Tentang sampel di localhost:5000/About dan periksa header untuk melihat hasilnya:

Mengonfigurasi filter

ConfigureFilter mengonfigurasi filter yang ditentukan untuk diterapkan. Anda dapat menerapkan kelas filter, tetapi aplikasi sampel menunjukkan cara mengimplementasikan filter dalam ekspresi lambda, yang diimplementasikan di belakang layar sebagai pabrik yang mengembalikan filter:

options.Conventions.ConfigureFilter(model =>
{
    if (model.RelativePath.Contains("OtherPages/Page2"))
    {
        return new AddHeaderAttribute(
            "OtherPagesPage2Header",
            new string[] { "OtherPages/Page2 Header Value" });
    }
    return new EmptyFilter();
});

Model aplikasi halaman digunakan untuk memeriksa jalur relatif untuk segmen yang mengarah ke halaman Page2 di folder OtherPages . Jika kondisi berlalu, header ditambahkan. Jika tidak, EmptyFilter diterapkan.

EmptyFilteradalah filter Tindakan. Karena Filter tindakan diabaikan oleh Razor Halaman, EmptyFilter tidak berpengaruh seperti yang dimaksudkan jika jalur tidak berisi OtherPages/Page2.

Minta halaman Page2 sampel di localhost:5000/OtherPages/Page2 dan periksa header untuk melihat hasilnya:

Mengonfigurasi pabrik filter

ConfigureFilter mengonfigurasi pabrik yang ditentukan untuk menerapkan filter ke semua Razor Halaman.

Aplikasi sampel menyediakan contoh penggunaan pabrik filter dengan menambahkan header, FilterFactoryHeader, dengan dua nilai ke halaman aplikasi:

options.Conventions.ConfigureFilter(new AddHeaderWithFactory());

AddHeaderWithFactory.cs:

public class AddHeaderWithFactory : IFilterFactory
{
    // Implement IFilterFactory
    public IFilterMetadata CreateInstance(IServiceProvider serviceProvider)
    {
        return new AddHeaderFilter();
    }

    private class AddHeaderFilter : IResultFilter
    {
        public void OnResultExecuting(ResultExecutingContext context)
        {
            context.HttpContext.Response.Headers.Add(
                "FilterFactoryHeader", 
                new string[] 
                { 
                    "Filter Factory Header Value 1",
                    "Filter Factory Header Value 2"
                });
        }

        public void OnResultExecuted(ResultExecutedContext context)
        {
        }
    }

    public bool IsReusable
    {
        get
        {
            return false;
        }
    }
}

Minta halaman Tentang sampel di localhost:5000/About dan periksa header untuk melihat hasilnya:

Filter MVC dan filter Halaman (IPageFilter)

Filter Tindakan MVC diabaikan oleh Razor Pages, karena Razor Pages menggunakan metode handler. Jenis filter MVC lainnya tersedia untuk Anda gunakan: Otorisasi, Pengecualian, Sumber Daya, dan Hasil. Untuk informasi selengkapnya, lihat topik Filter .

Filter Halaman (IPageFilter) adalah filter yang berlaku untuk Razor Pages. Untuk informasi selengkapnya, lihat Metode filter untuk Razor Halaman.

Sumber Daya Tambahan:

• Razor Perutean Halaman
• Konvensi otorisasi Razor Pages di ASP.NET Core
• Area di ASP.NET Core