使ってみる¶

導入¶

BlazorプロジェクトにBlazorPathHelperをインストールします。

BlazorPathHelperをインストールする
dotnet add package BlazorPathHelper

URLビルダー¶

最小限のURLビルダー¶

以下の内容でファイルを作成します。ファイル名は何でも良いですが、説明のためにWebPaths.csとします。

WebPaths.cs
using BlazorPathHelper;

// BlazorPath属性を付与することで自動生成が行われます。
// また、クラス定義の際には必ずpartial属性が必要です。
[BlazorPath]
public partial class WebPaths
{
  // 以下のように定数でURLページを定義します。
  // public const string (VariableName) = "/your-path";
  public const string Index = "/";
  public const string Sample = "/sample";
  public const string SampleChild = "/sample/child";
  public const string Counter = "/counter";
  public const string CounterWithState = "/counter/{count:int}";
  public const string CounterWithQuery = "/counter/query";
}

このように定義すると、以下のクラス定義が自動的に生成されます。

自動生成されたURLビルダー

Auto Generated Code
// <auto-generated />
public partial class WebPaths
{
  // HelperクラスにURLビルダーが生成されます
  public partial class Helper
  {
    public static string Index() => "/";
    public static string Sample() => "/sample";
    public static string SampleChild() => "/sample/child";
    public static string Counter() => "/counter";
    public static string CounterWithState(int Count)
      => string.Format("/counter/{0}", ToStringForUrl(Count));
    public static string CounterWithQuery() => "/counter/query";
  }
}

WebPaths.Helper.CounterWithStateにint型のパラメータを受け取るURLビルダーが生成されました。
しかし、CounterWithQueryはまだクエリを受け取る形になっていません。
これは、どのようなクエリを受け取るかがまだ定義されていないためです。

クエリ付きURLビルダー¶

では、クエリを受け取るように定義してみましょう。

WebPaths.cs
using BlazorPathHelper;

[BlazorPath]
public partial class WebPaths
{
  public const string Index = "/";
  public const string Sample = "/sample";
  public const string SampleChild = "/sample/child";
  public const string Counter = "/counter";
  public const string CounterWithState = "/counter/{count:int}";
  [Query<QueryRecord>] // このようにQuery属性を指定します
  public const string CounterWithQuery = "/counter/query";
}

// クエリパラメータを受け取るクラスを定義します。
// このクラスは必ず.csファイルに記述してください。(下記注釈を参照)
// 各パラメータはデフォルト値を指定するか、nullableにすることを推奨します。
public record QueryRecord(string query = "hello", int page = 0, bool? opt = null);

注意！

上記QueryRecordのクラス定義は、.razorファイルに記述すると正しく生成されません。
これは、ソースジェネレータの仕様によるものです。（RazorファイルもソースジェネレータによってC#に変換されるため、競合が発生します。）

すると、以下のクラス定義が自動的に生成されます。

自動生成されたURLクエリビルダー

Auto Generated Code
// <auto-generated />
public partial class WebPaths
{
  public partial class Helper
  {
    // 共通部分は省略
    public static string CounterWithQuery(QueryRecord __query)
      => string.Format("/counter/query{0}", BuildQuery([
        ToEscapedStrings("query", __query.query),
        ToEscapedStrings("page", __query.page),
        ToEscapedStrings("opt", __query.opt)
      ]));
  }
}

これで、CounterWithQueryのURLビルダーがクエリを受け取れるようになりました。
クエリ定義の詳細については、クエリサポートを参照してください。

使い方¶

(クラス名).Helper.(変数名)がURLビルダー関数です。以下のように使用できます。

Usage.cs
// URLを生成する関数を呼び出す
var homeUrl = WebPaths.Helper.Index();
// パラメータ付き
var counterStateUrl = WebPaths.Helper.CounterWithState(1);
// クエリ付き
var counterQueryUrl1 = WebPaths.Helper.CounterWithQuery(new());
var counterQueryUrl2 = WebPaths.Helper.CounterWithQuery(new() { query = "test" });
var counterQueryUrl3 = WebPaths.Helper.CounterWithQuery(new() { query = "foo", page = 1, opt = true });

Console.WriteLine(homeUrl);          // -> "/"
Console.WriteLine(counterStateUrl);  // -> "/counter/1"
Console.WriteLine(counterQueryUrl1); // -> "/counter/query?query=hello&page=0"
Console.WriteLine(counterQueryUrl2); // -> "/counter/query?query=test&page=0"
Console.WriteLine(counterQueryUrl3); // -> "/counter/query?query=foo&page=1&opt=true"

// 別のページに遷移する場合
// @inject NavigationManager Nav
Nav.NavigateTo(counterStateUrl);

より詳細な使い方は、URLビルダーの使い方を参照してください。

自動ページ属性指定¶

Blazorページ側には@page、[Parameter]、[SupplyParameterFromQuery]などの属性を指定する必要がありますが、これらもURL定義情報を元に自動生成できます。

WebPaths.cs
using BlazorPathHelper;
using Microsoft.AspNetCore.Components;

[BlazorPath]
public partial class WebPaths
{
  [Page<Home>] // <- Page<ページコンポーネント> 属性を追加
  public const string Index = "/";
  [Page<Sample>]
  public const string Sample = "/sample";
  [Page<SampleChild>]
  public const string SampleChild = "/sample/child";
  [Page<Counter>]
  public const string Counter = "/counter";
  [Page<Counter2>]
  public const string CounterWithState = "/counter/{count:int}";
  [Page<Counter3>, Query<QueryRecord>]
  public const string CounterWithQuery = "/counter/query";
}

public record QueryRecord(string query = "hello", int page = 0, bool? opt = null);
// 各コンポーネントの定義（実際には各コンポーネントに記述されます）
public partial class Home : ComponentBase;
public partial class Sample : ComponentBase;
public partial class SampleChild : ComponentBase;
public partial class Counter : ComponentBase;
public partial class Counter2 : ComponentBase;
public partial class Counter3 : ComponentBase;

すると、@page、[Parameter]、[SupplyParameterFromQuery]クラス定義を含んだファイルが自動的に生成されます。

自動生成されたページ定義ファイル(折りたたみ)

Auto Generated Code
// <auto-generated />
// -------------------
// Index(Home)
[Route("/")] // -> razorファイルに [@page "/"] と書いたのと同じ
public partial class Home;

// 中略

// CounterWithState(Counter2)
[Route("/counter/{count:int}")]
public partial class Counter2
{
  // パラメーター定義が自動生成されます
  [Parameter]
  public int Count { get; set; }
}
// -------------------
// CounterWithQuery(Counter3)
[Route("/counter/query")]
public partial class Counter3
{
  // クエリパラメーター定義が自動生成されます
  [SupplyParameterFromQuery]
  public string Query { get; set; }
  [SupplyParameterFromQuery]
  public int Page { get; set; }
  [SupplyParameterFromQuery]
  public bool? Opt { get; set; }
}

これで、ページ属性が自動的に設定されるため、.razorファイルの記述が不要になります。
よって、.razorファイルから@page属性などを削除できます。
詳細な使い方は、自動ページ属性を参照してください。

いつでも取り外し可能です

[Page]属性指定による自動生成は完全に独立した機能です。
そのため、自動定義が不要であれば、いつでも[Page]属性を削除できます。

メニュー構造自動生成¶

URL定義を元にして、メニュー構造データも自動生成されます。これはメニューを動的に作成するのに便利です。

最小限のメニュー生成¶

[Item]属性を各URL定義に追加します。

WebPaths.cs
using BlazorPathHelper;

[BlazorPath]
public partial class WebPaths
{
  // [Item("メニュー名")]属性を付与することで自動生成が行われます。
  // [Page]/[Query]属性とは完全に独立しているため、併用可能です。
  [Item("TopPage")]
  public const string Index = "/";
  [Item("Sample1a")]
  public const string Sample = "/sample";
  [Item("Sample1b")]
  public const string SampleChild = "/sample/child";
  [Item("Sample2a")]
  public const string Counter = "/counter";
  // パラメータ/クエリを持つページはメニューに表示するべきでないため[Item]属性を省略しています。
  // （セットしても自動的にメニューから省略されます）
  public const string CounterWithState = "/counter/{count:int}";
}

すると、WebPaths.MenuItemに、メニュー構造データが自動的に生成されます。

自動生成されたメニュー構造データ(折りたたみ)

Auto Generated Code
// <auto-generated />
public partial class WebPaths
{
  public static readonly BlazorPathMenuItem[] MenuItem = [
    new BlazorPathMenuItem(){
      Name = "TopPage", // メニュー名。指定しない場合は変数名が使用されます
      Path = "/",       // ページURL
      Children = []     // サブメニュー
      // その他、メニュー作成に便利な自動生成されるプロパティがいくつかあります。
    },
    new BlazorPathMenuItem(){
      Name = "Sample1a",
      Path = "/sample", 
      // URL構造を元に自動的にサブメニューが生成されます
      Children = [
        new BlazorPathMenuItem(){
          Name = "Sample1b",
          Path = "/sample/child", 
          Children = []
        }
      ]
    },
    new BlazorPathMenuItem(){
      Name = "Sample2a",
      Path = "/counter",
      Children = []
    }
  ]
}

ここでは、メニュー構造データの生成のみが行われ、メニュー表示は別途実装する必要があります。
つまり、どのフレームワークを使ってメニューを作成するかはあなた次第です！

詳細は各フレームワークごとのサンプルを参照してください。

カスタマイズ¶

メニューの生成に際して、説明文・アイコン・ローカライズなどのカスタマイズが可能です。
詳細はメニュー構造のカスタマイズを参照してください。