{"id":1714,"date":"2013-04-04T12:25:33","date_gmt":"2013-04-04T12:25:33","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/webdev\/2013\/04\/04\/debugging-asp-net-web-api-with-route-debugger\/"},"modified":"2022-08-10T00:40:46","modified_gmt":"2022-08-10T07:40:46","slug":"debugging-asp-net-web-api-with-route-debugger","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/debugging-asp-net-web-api-with-route-debugger\/","title":{"rendered":"Debugging ASP.NET Web API with Route Debugger"},"content":{"rendered":"

Tutorial and Tool written by Troy Dai (Twitter @troy_dai) with assistance from Rick Anderson<\/a> (Twitter @RickAndMSFT<\/a>)<\/p>\n

Search for \u201casp.net web api routing\u201d on stackoverflow<\/a>, you\u2019ll find many questions. How exactly does Web API routing work? Why doesn\u2019t my route work? Why is this action not invoked? Often time it is difficult to debug route. <\/p>\n

To address this issue I wrote this tool named \u201cASP.NET Web API Route Debugger\u201d trying to make Web API developers\u2019 lives a bit easier. <\/p>\n

In this article I\u2019ll first introduce stdebugger. Then I\u2019ll introduce how routing works in Web Api. It is followed by three examples of how to use the route debugger in real cases.<\/p>\n

How to step up the Route Debugger<\/h2>\n

You can install Route Debugger from NuGet (http:\/\/www.nuget.org\/packages\/WebApiRouteDebugger\/<\/a>)<\/p>\n

\n
\n
   1:<\/span> PM> Install-Package WebApiRouteDebugger<\/pre>\n
<\/div>\n<\/div>\n
The NuGet package will add a new area and to your project. The image below shows the new files added to the project. (The + icon shows new files and the red check icon shows changed files)<\/p>\n
\"clip_image002\"<\/a><\/p>\n
Hit F5 to compile and then navigate to http:\/\/ localhost:xxx\/rd for the route debugger page.<\/p>\n
\"clip_image004\"<\/a><\/p>\n
Enter the URL you want to test and press Send<\/b>. The results page is displayed. <\/p>\n
\"clip_image006\"<\/a><\/p>\n
I\u2019ll explain how to read the results in the following sections.<\/p>\n
How does routing works in ASP.NET Web Api<\/h2>\n
The routing mechanism of ASP.NET Web API is composed of three steps: find the matching route and parse the route data, find the matching controller, and find the matching action. In any step fails to find a selection the steps following will not be executed. For example, if no controller is found, the matching ends and no action is looked for. <\/p>\n
In the first step, a route will be matched. Every route is defined with route template, defaults, constraints, data tokens and handler. (Routes are configured by default in App_StartWebApiConfig.cs<\/i> ) Once a route is matched, the request URL is parsed into route data<\/b> based on the route template. Route data<\/b> is a dictionary mapping from string to object.<\/p>\n
Controller matching is purely done based on the value of \u201ccontroller\u201d key in route data. If the key \u201ccontroller\u201d doesn\u2019t exist in route data, controller selection will fail.<\/p>\n
After controller is matched, all the public methods on the controller are found through reflection. To match the action, it uses the following algorithm:<\/p>\n
\"clip_image008\"<\/a><\/p>\n
    \n
  1. If route data contains key \u201caction\u201d, then the action will be searched based on action name. Unlike ASP.NET MVC, Web API routes generally do not use action names in routing.<\/li>\n
      \n
    1. Find all actions where the action name is \u201caction\u201d in the route data;<\/li>\n
    2. Each action supports one or more HTTP Verbs (GET, POST, PUT, etc.). Eliminate those actions which don\u2019t support the current HTTP request\u2019s verb. <\/li>\n<\/ol>\n
    3. If the route data doesn\u2019t contains key \u201caction\u201d, then the action will be searched based on the supported request method directly. <\/li>\n
    4. For selected actions in either of above two steps, examine the parameters of action method. Eliminate those actions that don\u2019t match all the parameters in the route data.<\/li>\n
    5. Eliminate all actions that are marked by the NonAction<\/a> attribute.<\/li>\n
        \n
      1. If more than one action matches, an HTTP 500 error is thrown. (Internally an HttpResponseException is thrown.)<\/li>\n
      2. If there is no matching action, an HTTP 404 error is thrown. <\/li>\n<\/ol>\n<\/ol>\n
        How to use the Route bugger<\/h2>\n
        Example 1: Missing Controller Value<\/h2>\n
        Source: http:\/\/stackoverflow.com\/questions\/13876816\/web-api-routing<\/a><\/p>\n
        Issue<\/h3>\n
        The controller and routes are shown below. The URL doesn\u2019t match the MachineApi route.<\/p>\n
        \n
        \n
           1:<\/span> localhost\/api\/machine\/somecode\/all<\/pre>\n
        <\/div>\n<\/div>\n
         <\/p>\n
        You can download <\/em>Sample1<\/em><\/a> and install the route debugger NuGet package to follow along.<\/em><\/p>\n
        Controller<\/h3>\n
        \n
        \n
           1:<\/span> public<\/span> class<\/span> MachineController : ApiController<\/pre>\n
        <\/p>\n
           2:<\/span> {<\/pre>\n
        <\/p>\n
           3:<\/span>     public<\/span> IEnumerable<Machine> Get()<\/pre>\n
        <\/p>\n
           4:<\/span>     {<\/pre>\n
        <\/p>\n
           5:<\/span>         return<\/span> new<\/span> List<Machine>{<\/pre>\n
        <\/p>\n
           6:<\/span>             new<\/span> Machine    {<\/pre>\n
        <\/p>\n
           7:<\/span>                 LastPlayed = DateTime.UtcNow,<\/pre>\n
        <\/p>\n
           8:<\/span>                 MachineAlertCount = 1,<\/pre>\n
        <\/p>\n
           9:<\/span>                 MachineId = "122"<\/span>,<\/pre>\n
        <\/p>\n
          10:<\/span>                 MachineName = "test"<\/span>,<\/pre>\n
        <\/p>\n
          11:<\/span>                 MachinePosition = "12"<\/span>,<\/pre>\n
        <\/p>\n
          12:<\/span>                 MachineStatus = "test"<\/span><\/pre>\n
        <\/p>\n
          13:<\/span>             }<\/pre>\n
        <\/p>\n
          14:<\/span>         };<\/pre>\n
        <\/p>\n
          15:<\/span>     }<\/pre>\n
        <\/p>\n
          16:<\/span>  <\/pre>\n
        <\/p>\n
          17:<\/span>     public<\/span> IEnumerable<Machine> All(string<\/span> code)<\/pre>\n
        <\/p>\n
          18:<\/span>     {<\/pre>\n
        <\/p>\n
          19:<\/span>         return<\/span> new<\/span> List<Machine><\/pre>\n
        <\/p>\n
          20:<\/span>         {<\/pre>\n
        <\/p>\n
          21:<\/span>          new<\/span> Machine<\/pre>\n
        <\/p>\n
          22:<\/span>             {<\/pre>\n
        <\/p>\n
          23:<\/span>                 LastPlayed = DateTime.UtcNow,<\/pre>\n
        <\/p>\n
          24:<\/span>                 MachineAlertCount = 1,<\/pre>\n
        <\/p>\n
          25:<\/span>                 MachineId = "122"<\/span>,<\/pre>\n
        <\/p>\n
          26:<\/span>                 MachineName = "test"<\/span>,<\/pre>\n
        <\/p>\n
          27:<\/span>                 MachinePosition = "12"<\/span>,<\/pre>\n
        <\/p>\n
          28:<\/span>                 MachineStatus = "test"<\/span><\/pre>\n
        <\/p>\n
          29:<\/span>             }<\/pre>\n
        <\/p>\n
          30:<\/span>         };<\/pre>\n
        <\/p>\n
          31:<\/span>     }<\/pre>\n
        <\/p>\n
          32:<\/span> }<\/pre>\n
        <\/div>\n<\/div>\n
        Route<\/h3>\n
        \n
        \n
        \n
           1:<\/span> config.Routes.MapHttpRoute(<\/pre>\n
        <\/p>\n
           2:<\/span>     name: "MachineApi"<\/span>,<\/pre>\n
        <\/p>\n
           3:<\/span>     routeTemplate: "api\/machine\/{code}\/all"<\/span><\/pre>\n
        <\/p>\n
           4:<\/span> );<\/pre>\n
        <\/p>\n
           5:<\/span>  <\/pre>\n
        <\/p>\n
           6:<\/span> config.Routes.MapHttpRoute(<\/pre>\n
        <\/p>\n
           7:<\/span>     name: "DefaultApi"<\/span>,<\/pre>\n
        <\/p>\n
           8:<\/span>     routeTemplate: "api\/{controller}\/{id}"<\/span>,<\/pre>\n
        <\/p>\n
           9:<\/span>     defaults: new<\/span> { id = RouteParameter.Optional }<\/pre>\n
        <\/div>\n<\/p><\/div>\n<\/h5>\n
        Test<\/h3>\n
        Test http:\/\/localhost\/api\/machine\/somecode\/all<\/u> in the route debugger:<\/p>\n
        \"clip_image010\"<\/a><\/p>\n
        Observation<\/h3>\n
          \n
        1. The HTTP status code is 404 (resource not found);<\/li>\n
        2. The route data contains only one key value pair, mapping \u201cSomecode\u201d to \u201cCode\u201d<\/li>\n
        3. The selected route is \u201cApi\/Machine\/{Code}\/All\u201d because the template fits the URL. However there are no default values<\/u> defined for this route.<\/li>\n
        4. No controller matches (none of the rows are highlighted in controller selecting table)<\/li>\n<\/ol>\n
          Analysis<\/h3>\n
          The route debugger output shows the \u201ccontroller\u201d value is not found in the route data or route defaults. The default controller selector relies on \u201ccontroller\u201d value to find a proper controller. <\/p>\n
          A common misunderstanding of route templates is that the values are mapped based on their position. That\u2019s not true. In this case even though Machine<\/b> is placed right after Api<\/b>, there is no hint that this segment of URL should be picked up.<\/p>\n
          Solution<\/h3>\n
          Add a default value specifying the machine controller to the first route:<\/p>\n
          \n
          \n
             1:<\/span> config.Routes.MapHttpRoute(<\/pre>\n
          <\/p>\n
             2:<\/span>     name: "MachineApi"<\/span>,<\/pre>\n
          <\/p>\n
             3:<\/span>     routeTemplate: "api\/machine\/{code}\/all"<\/span>,<\/pre>\n
          <\/p>\n
             4:<\/span>     defaults: new<\/span> { controller = "Machine"<\/span> });<\/pre>\n
          <\/div>\n<\/div>\n
          After this change, you get an HTTP 200 return, the machine controller is matched and the Action is matched. The matching route, controller and action are highlighted in green in the route debugger as shown below.<\/p>\n
          \"clip_image012\"<\/a><\/p>\n
          Similar issue:<\/h3>\n
          http:\/\/stackoverflow.com\/questions\/13869541\/why-is-my-message-handler-running-even-when-it-is-not-defined-in-webapi<\/a><\/p>\n
          Example 2: Ambiguous default<\/h2>\n
          Source: http:\/\/stackoverflow.com\/questions\/14058228\/asp-net-web-api-no-action-was-found-on-the-controller<\/a><\/p>\n
          Controller<\/h3>\n
          \n
          \n
             1:<\/span> public<\/span> class<\/span> ValuesController : ApiController<\/pre>\n
          <\/p>\n
             2:<\/span> {<\/pre>\n
          <\/p>\n
             3:<\/span>     \/\/ GET api\/values<\/span><\/pre>\n
          <\/p>\n
             4:<\/span>     public<\/span> IEnumerable<string<\/span>> Get()<\/pre>\n
          <\/p>\n
             5:<\/span>     {<\/pre>\n
          <\/p>\n
             6:<\/span>         return<\/span> new<\/span> string<\/span>[] { "value1"<\/span>, "value2"<\/span> };<\/pre>\n
          <\/p>\n
             7:<\/span>     }<\/pre>\n
          <\/p>\n
             8:<\/span>     \/\/ GET api\/values\/5<\/span><\/pre>\n
          <\/p>\n
             9:<\/span>     public<\/span> string<\/span> Get(int<\/span> id)<\/pre>\n
          <\/p>\n
            10:<\/span>     {<\/pre>\n
          <\/p>\n
            11:<\/span>         return<\/span> "value"<\/span>;<\/pre>\n
          <\/p>\n
            12:<\/span>     }<\/pre>\n
          <\/p>\n
            13:<\/span>     \/\/ POST api\/values<\/span><\/pre>\n
          <\/p>\n
            14:<\/span>     public<\/span> void<\/span> Post([FromBody]string<\/span> value<\/span>)<\/pre>\n
          <\/p>\n
            15:<\/span>     {<\/pre>\n
          <\/p>\n
            16:<\/span>     }<\/pre>\n
          <\/p>\n
            17:<\/span>     \/\/ PUT api\/values\/5<\/span><\/pre>\n
          <\/p>\n
            18:<\/span>     public<\/span> void<\/span> Put(int<\/span> id, [FromBody]string<\/span> value<\/span>)<\/pre>\n
          <\/p>\n
            19:<\/span>     {<\/pre>\n
          <\/p>\n
            20:<\/span>     }<\/pre>\n
          <\/p>\n
            21:<\/span>     \/\/ DELETE api\/values\/5<\/span><\/pre>\n
          <\/p>\n
            22:<\/span>     public<\/span> void<\/span> Delete(int<\/span> id)<\/pre>\n
          <\/p>\n
            23:<\/span>     {<\/pre>\n
          <\/p>\n
            24:<\/span>     }<\/pre>\n
          <\/p>\n
            25:<\/span>  <\/pre>\n
          <\/p>\n
            26:<\/span>     [HttpGet]<\/pre>\n
          <\/p>\n
            27:<\/span>     public<\/span> void<\/span> Machines()<\/pre>\n
          <\/p>\n
            28:<\/span>     {<\/pre>\n
          <\/p>\n
            29:<\/span>     }<\/pre>\n
          <\/p>\n
            30:<\/span>     public<\/span> void<\/span> Machines(int<\/span> id)<\/pre>\n
          <\/p>\n
            31:<\/span>     {<\/pre>\n
          <\/p>\n
            32:<\/span>     }<\/pre>\n
          <\/p>\n
            33:<\/span> }<\/pre>\n
          <\/div>\n<\/div>\n
          Route definition<\/h3>\n
          \n
          \n
             1:<\/span> config.Routes.MapHttpRoute(<\/pre>\n
          <\/p>\n
             2:<\/span>     name: "DefaultApi"<\/span>,<\/pre>\n
          <\/p>\n
             3:<\/span>     routeTemplate: "api\/{controller}\/{action}\/{id}"<\/span>,<\/pre>\n
          <\/p>\n
             4:<\/span>     defaults: new<\/span> { action = "get"<\/span>, id = RouteParameter.Optional });<\/pre>\n
          <\/div>\n<\/div>\n
          Test<\/h3>\n
          Try the following three routes which work correctly<\/p>\n