라우트 파라미터와 라우트 제약 조건
이 문서는 Visual Studio에서 Blazor 컴포넌트를 생성하는 단계부터 @page 라우트와 라우트 파라미터를 적용하는 전체 과정을 순서대로 정리합니다.
0단계. DotNetNote 프로젝트 준비 여부를 확인합니다
0-1. DotNetNote 프로젝트가 이미 존재하는 경우
이미 DotNetNote 솔루션 파일과 프로젝트가 정상적으로 존재하면, 기존 프로젝트를 그대로 사용합니다.
0-2. DotNetNote 프로젝트가 없는 경우 새로 생성합니다
Visual Studio를 실행합니다. 새 프로젝트 만들기를 선택합니다.
프로젝트 템플릿에서 Blazor Server App 또는 ASP.NET Core Web App (Blazor Server) 를 선택합니다.
프로젝트 이름을 DotNetNote로 지정합니다.
필자의 저장 위치는 다음과 같이 설정합니다.
C:\dotnet10\DotNetNote
.NET 버전은 사용 중인 환경에 맞게 선택합니다. 프로젝트 생성이 완료되면 솔루션이 정상적으로 열리는 것을 확인합니다.
1단계. PayNow 컴포넌트를 생성합니다
솔루션 탐색기에서 다음 경로로 이동합니다.
Components > Pages > Portal
Portal 폴더가 없다면 새 폴더를 생성합니다. Portal 폴더에서 마우스 오른쪽 버튼을 클릭한 후 새 항목 추가를 선택합니다. Razor Component를 선택하고 파일 이름을 다음과 같이 지정합니다.
PayNow.razor
파일이 정상적으로 생성되면 편집 화면을 엽니다.
2단계. /portal/pay 기본 라우트를 설정합니다
PayNow.razor 파일에 다음 코드를 작성합니다.
@page "/portal/pay"
<h3>Pay Now</h3>
@code {
}
이후 프로젝트를 실행합니다. 브라우저에서 다음 주소로 접속합니다.
/portal/pay
페이지가 정상적으로 출력되며, 화면에는 Pay Now라는 제목이 표시됩니다. 이 단계에서는 기본 라우트가 정상적으로 동작하는지 확인합니다.
3단계. {Id:long} 라우트 파라미터를 추가합니다
같은 파일에서 @page 구문을 다음과 같이 수정합니다.
@page "/portal/pay/{Id:long}"
<h3>Pay Now</h3>
@code {
}
다시 프로젝트를 실행합니다. 브라우저에서 다음 주소로 접속합니다.
/portal/pay/1234
이 상태에서는 페이지가 정상적으로 출력되지 않고, 매치되는 속성이 없다는 오류가 발생합니다.
이는 라우트에는 Id 파라미터가 정의되어 있지만, 해당 값을 받을 [Parameter] 속성이 아직 추가되지 않았기 때문입니다.
이 단계에서는 라우트 파라미터만 추가했을 때 발생하는 오류 상황을 확인합니다.
4단계. [Parameter] 속성을 추가하여 오류를 해결합니다
이제 Id 값을 받을 [Parameter] 속성을 추가합니다.
PayNow.razor 파일을 다음과 같이 수정합니다.
@page "/portal/pay/{Id:long}"
<h3>Pay Now</h3>
@code {
[Parameter]
public long Id { get; set; }
}
다시 프로젝트를 실행합니다. 브라우저에서 다음 주소로 접속합니다.
/portal/pay/1234
이번에는 오류 없이 페이지가 정상적으로 실행됩니다.
Id 값이 1234로 정상적으로 바인딩되는 것을 확인합니다.
5단계. {Id:long} 구문의 동작 방식을 확인합니다
@page "/portal/pay/{Id:long}" 구문에서 {Id}는 라우트 파라미터 역할을 합니다.
long은 해당 값이 반드시 정수형 long 타입이어야 함을 의미합니다.
이 설정에 따라 다음 주소는 정상적으로 처리됩니다.
/portal/pay/1/portal/pay/1234
반대로 다음 주소는 라우트 매칭에서 제외됩니다.
/portal/pay/abc/portal/pay/12.5
이 과정을 통해 라우트 단계에서 타입 검증이 자동으로 적용되는 것을 확인합니다.
6단계. Blazor 라우트 파라미터 바인딩 규칙을 확인합니다
Blazor에서 @page에 라우트 파라미터를 사용하는 경우 다음 조건을 반드시 만족해야 합니다.
첫째, {} 안에 선언한 이름과 동일한 이름의 속성이 컴포넌트 내부에 존재해야 합니다.
둘째, 해당 속성에는 반드시 [Parameter] 특성이 선언되어야 합니다.
셋째, 라우트에서 지정한 타입과 속성의 자료형은 서로 정확하게 일치해야 합니다.
예를 들어 다음과 같은 라우트가 설정되어 있다면,
@page "/test/{UserId:int}"
컴포넌트 내부에는 반드시 다음 코드가 함께 존재해야 합니다.
@code {
[Parameter]
public int UserId { get; set; }
}
이 세 조건이 모두 충족되어야 라우트 파라미터가 정상적으로 동작합니다.
7단계. /portal/pay와 /portal/pay/1234의 동작 차이를 확인합니다
/portal/pay는 파라미터가 없는 정적 라우트로 처리됩니다.
/portal/pay/1234는 Id 값을 포함하는 동적 라우트로 처리됩니다.
Blazor 내부에서는 이 두 주소가 서로 다른 라우트로 구분되어 동작합니다.
따라서 두 주소를 모두 처리하려면 @page를 각각 추가하거나 라우트 구조를 명확하게 설계해야 합니다.
마무리
다음과 같은 라우트를 사용하는 경우,
@page "/portal/pay/{Id:long}"
반드시 다음 코드가 함께 구성되어야 합니다.
@code {
[Parameter]
public long Id { get; set; }
}
이 구성이 완성되면 /portal/pay/1234 형식의 주소가 정상적으로 라우팅되며, 파라미터 값도 정상적으로 바인딩됩니다.