Bagikan melalui


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
Tambahkan templat rute dan header ke halaman aplikasi.
Konvensi tindakan rute halaman Tambahkan templat rute ke halaman dalam folder dan ke satu halaman.
Konvensi tindakan model halaman 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:

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:

The About page is requested with a route segment of GlobalRouteValue. The rendered page shows that the route data value is captured in the OnGet method of the page.

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:

Response headers of the About page show that the GlobalHeader has been added.

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:

Page1 in the OtherPages folder is requested with a route segment of GlobalRouteValue and OtherPagesRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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:

About page is requested with route segments for GlobalRouteValue and AboutRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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:

Sample app Contact link in the navigation bar

Inspecting the Contact link in the rendered HTML indicates that the href is set to '/TheContactPage'

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:

Edge browser example of supplying an optional 'text' route segment of 'TextValue' in the URL. The rendered page shows the 'text' segment value.

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:

Response headers of the OtherPages/Page1 page show that the OtherPagesHeader has been added.

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:

Response headers of the About page show that the AboutHeader has been added.

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:

The OtherPagesPage2Header is added to the response for Page2.

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:

Response headers of the About page show that two FilterFactoryHeader headers have been added.

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:

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

Saat Anda perlu mengonfigurasi rute halaman kustom untuk halaman individual, konfigurasikan perutean ke halaman dengan konvensi AddPageRoute yang dijelaskan nanti dalam topik ini.

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
  • TambahkanFolderRouteModelConvention
  • AddPageRouteModelConvention
  • AddPageRoute
Tambahkan templat rute ke halaman dalam folder dan ke satu halaman.
Konvensi tindakan model halaman
  • AddFolderApplicationModelConvention
  • AddPageApplicationModelConvention
  • KonfigurasikanFilter (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 dikonfigurasi RazorPagesOptions di Startup.ConfigureServices. Contoh konvensi berikut dijelaskan nanti dalam topik ini:

public void ConfigureServices(IServiceCollection services)
{
    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).

Pesanan 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 menambahkan {globalTemplate?} templat rute ke semua halaman di aplikasi:

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. Rute Halaman Kontak memiliki urutan null default (Order = 0), sehingga cocok sebelum {globalTemplate?} templat rute.
  • {aboutTemplate?} Templat rute ditambahkan nanti dalam topik. {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 ditambahkan nanti dalam topik. {otherPagesTemplate?} Templat diberikan Order dari 2. Ketika halaman apa pun di folder Pages/OtherPages diminta dengan 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.

Razor Opsi halaman, seperti menambahkan Conventions, ditambahkan saat Razor Pages ditambahkan ke kumpulan layanan di Startup.ConfigureServices. Misalnya, lihat aplikasi sampel.

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

Minta halaman Tentang sampel di localhost:5000/About/GlobalRouteValue dan periksa hasilnya:

The About page is requested with a route segment of GlobalRouteValue. The rendered page shows that the route data value is captured in the OnGet method of the page.

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

Startup.cs:

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

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

Response headers of the About page show that the GlobalHeader has been added.

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

Startup.cs:

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

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:

Page1 in the OtherPages folder is requested with a route segment of GlobalRouteValue and OtherPagesRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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:5000/About/GlobalRouteValue/AboutRouteValue dan periksa hasilnya:

About page is requested with route segments for GlobalRouteValue and AboutRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

Menggunakan transformator parameter untuk menyesuaikan rute halaman

Rute halaman yang dihasilkan oleh ASP.NET Core dapat dikustomisasi menggunakan transformator parameter. Transformator parameter mengimplementasikan IOutboundParameterTransformer dan mengubah nilai parameter. Misalnya, transformator parameter kustom SlugifyParameterTransformer mengubah SubscriptionManagement nilai rute menjadi subscription-management.

Konvensi PageRouteTransformerConvention model rute halaman menerapkan transformator parameter ke segmen folder dan nama file dari rute halaman yang dihasilkan secara otomatis di aplikasi. Misalnya, Razor file Pages di /Pages/SubscriptionManagement/ViewAll.cshtml akan memiliki rutenya ditulis ulang dari /SubscriptionManagement/ViewAll ke /subscription-management/view-all.

PageRouteTransformerConvention hanya mengubah segmen yang dihasilkan secara otomatis dari rute halaman yang berasal dari Razor folder Pages dan nama file. Ini tidak mengubah segmen rute yang ditambahkan dengan direktif @page . Konvensi ini juga tidak mengubah rute yang ditambahkan oleh AddPageRoute.

PageRouteTransformerConvention terdaftar sebagai opsi di Startup.ConfigureServices:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages(options =>
    {
        options.Conventions.Add(
            new PageRouteTransformerConvention(
                new SlugifyParameterTransformer()));
    });
}
public class SlugifyParameterTransformer : IOutboundParameterTransformer
{
    public string TransformOutbound(object value)
    {
        if (value == null) { return null; }

        return Regex.Replace(value.ToString(),
                             "([a-z])([A-Z])",
                             "$1-$2",
                             RegexOptions.CultureInvariant,
                             TimeSpan.FromMilliseconds(100)).ToLowerInvariant();
    }
}

Peringatan

Saat menggunakan System.Text.RegularExpressions untuk memproses masukan yang tidak tepercaya, berikan batas waktu. Pengguna jahat dapat memberikan masukan ke RegularExpressions yang menyebabkan Penolakan Serangan Layanan. ASP.NET API kerangka kerja Core yang menggunakan RegularExpressions batas waktu.

Mengonfigurasi rute halaman

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

Aplikasi sampel membuat rute ke /TheContactPage untuk Contact.cshtml:

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

Halaman Kontak juga dapat dijangkau melalui /Contact rute defaultnya.

Rute kustom aplikasi sampel ke halaman Kontak 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:

Sample app Contact link in the navigation bar

Inspecting the Contact link in the rendered HTML indicates that the href is set to '/TheContactPage'

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

Edge browser example of supplying an optional 'text' route segment of 'TextValue' in the URL. The rendered page shows the 'text' segment value.

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:

Response headers of the OtherPages/Page1 page show that the OtherPagesHeader has been added.

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:

Response headers of the About page show that the AboutHeader has been added.

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:

The OtherPagesPage2Header is added to the response for Page2.

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:

Response headers of the About page show that two FilterFactoryHeader headers have been added.

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:

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

Saat Anda perlu mengonfigurasi rute halaman kustom untuk halaman individual, konfigurasikan perutean ke halaman dengan konvensi AddPageRoute yang dijelaskan nanti dalam topik ini.

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
  • TambahkanFolderRouteModelConvention
  • AddPageRouteModelConvention
  • AddPageRoute
Tambahkan templat rute ke halaman dalam folder dan ke satu halaman.
Konvensi tindakan model halaman
  • AddFolderApplicationModelConvention
  • AddPageApplicationModelConvention
  • KonfigurasikanFilter (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 ditambahkan dan dikonfigurasi menggunakan AddRazorPagesOptions metode ekstensi ke AddMvc pada koleksi layanan di Startup kelas . Contoh konvensi berikut dijelaskan nanti dalam topik ini:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddRazorPagesOptions(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).

Pesanan 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 menambahkan {globalTemplate?} templat rute ke semua halaman di aplikasi:

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. Rute Halaman Kontak memiliki urutan null default (Order = 0), sehingga cocok sebelum {globalTemplate?} templat rute.
  • {aboutTemplate?} Templat rute ditambahkan nanti dalam topik. {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 ditambahkan nanti dalam topik. {otherPagesTemplate?} Templat diberikan Order dari 2. Ketika halaman apa pun di folder Pages/OtherPages diminta dengan 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.

Razor Opsi halaman, seperti menambahkan Conventions, ditambahkan saat MVC ditambahkan ke kumpulan layanan di Startup.ConfigureServices. Misalnya, lihat aplikasi sampel.

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

Minta halaman Tentang sampel di localhost:5000/About/GlobalRouteValue dan periksa hasilnya:

The About page is requested with a route segment of GlobalRouteValue. The rendered page shows that the route data value is captured in the OnGet method of the page.

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

Startup.cs:

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

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

Response headers of the About page show that the GlobalHeader has been added.

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

Startup.cs:

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

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:

Page1 in the OtherPages folder is requested with a route segment of GlobalRouteValue and OtherPagesRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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:5000/About/GlobalRouteValue/AboutRouteValue dan periksa hasilnya:

About page is requested with route segments for GlobalRouteValue and AboutRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

Mengonfigurasi rute halaman

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

Aplikasi sampel membuat rute ke /TheContactPage untuk Contact.cshtml:

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

Halaman Kontak juga dapat dijangkau melalui /Contact rute defaultnya.

Rute kustom aplikasi sampel ke halaman Kontak 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:

Sample app Contact link in the navigation bar

Inspecting the Contact link in the rendered HTML indicates that the href is set to '/TheContactPage'

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

Edge browser example of supplying an optional 'text' route segment of 'TextValue' in the URL. The rendered page shows the 'text' segment value.

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:

Response headers of the OtherPages/Page1 page show that the OtherPagesHeader has been added.

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:

Response headers of the About page show that the AboutHeader has been added.

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:

The OtherPagesPage2Header is added to the response for Page2.

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:

Response headers of the About page show that two FilterFactoryHeader headers have been added.

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: