From db5ce9d8ded238be9beca342ac56877aec6f1b55 Mon Sep 17 00:00:00 2001 From: Steve Smith Date: Wed, 8 Apr 2015 11:20:17 -0400 Subject: [PATCH] Updated based on @danroth27 feedback --- .../migratingfromwebapi2.rst | 55 ++++++++++--------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/docs/webapi/migratingfromwebapi2/migratingfromwebapi2.rst b/docs/webapi/migratingfromwebapi2/migratingfromwebapi2.rst index 25ca4115c6..043134e3b9 100644 --- a/docs/webapi/migratingfromwebapi2/migratingfromwebapi2.rst +++ b/docs/webapi/migratingfromwebapi2/migratingfromwebapi2.rst @@ -1,10 +1,10 @@ -Migrating From ASP.NET Web API 2 to ASP.NET 5 -============================================= +Migrating From ASP.NET Web API 2 to MVC 6 +========================================= By `Steve Smith`_ | Originally Published: 1 June 2015 .. _`Steve Smith`: Author_ -ASP.NET Web API 2 was separate from ASP.NET MVC 5, with each using their own libraries for dependency resolution, among other things. In ASP.NET 6, Web API has been merged with MVC, providing a single, consistent way of building web applications. In this article we demonstrate the steps required to migrate from an ASP.NET Web API 2 project to ASP.NET 5. +ASP.NET Web API 2 was separate from ASP.NET MVC 5, with each using their own libraries for dependency resolution, among other things. In MVC 6, Web API has been merged with MVC, providing a single, consistent way of building web applications. In this article we demonstrate the steps required to migrate from an ASP.NET Web API 2 project to MVC 6. This article covers the following topics: - Review Web API 2 Project @@ -17,7 +17,7 @@ You can view the finished source from the project created in this article `on Gi Review Web API 2 Project ^^^^^^^^^^^^^^^^^^^^^^^^ -This article uses the sample project, ProductsApp, created in the article, `Getting Started with ASP.NET Web API 2 (C#) `_ as its starting point. +This article uses the sample project, ProductsApp, created in the article, `Getting Started with ASP.NET Web API 2 (C#) `_ as its starting point. In that project, a simple Web API 2 project is configured as follows. In Global.asax.cs, a call is made to WebApiConfig.Register: @@ -33,7 +33,7 @@ WebApiConfig is defined in App_Start, and has just one static Register method: :emphasize-lines: 15-20 :linenos: -This class configures `attribute routing `_, which isn't actually being used in this project, as well as the routing table that Web API 2 uses. In this case, Web API will expect URLs to match /api/{controller}/{id}, with {id} being optional. +This class configures `attribute routing `_, although it's not actually being used in the project, as well as the routing table that Web API 2 uses. In this case, Web API will expect URLs to match the format */api/{controller}/{id}*, with *{id}* being optional. The ProductsApp project includes just one simple controller, which inherits from ApiController and exposes two methods: @@ -48,10 +48,12 @@ Finally, the model, Product, used by the ProductsApp, is a simple class: :language: c# :linenos: +Now that we have a simple project from which to start, we can demonstrate how to migrate this Web API 2 project to ASP.NET MVC 6. + Create the Destination Project ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Using Visual Studio 2015, create a new, empty solution, and add the existing ProductsApp project to it. Then, add a new Web Project to the solution. In this case, I'm naming the new project 'ProductsDnx'. +Using Visual Studio 2015, create a new, empty solution, and add the existing ProductsApp project to it. Then, add a new Web Project to the solution. Name the new project 'ProductsDnx'. .. image:: _static/add-web-project.png @@ -59,50 +61,49 @@ Next, choose the ASP.NET 5 Web API template project. We will migrate the Product .. image:: _static/aspnet-5-webapi.png -Delete the Project_Readme.html file from the new project. You can also delete the Your solution should now look like this: +Delete the Project_Readme.html file from the new project. Your solution should now look like this: .. image:: _static/webapimigration-solution.png +.. migrate-webapi-config: + Migrate Configuration ^^^^^^^^^^^^^^^^^^^^^ -ASP.NET 5 no longer uses global.asax, web.config, or App_Start folders. Instead, all startup tasks are done in Startup.cs in the root of the project, and static configuration files can be wired up from there if needed. Since Web API is now built into ASP.NET 5, there is less need to configure it. Attribute-based routing is now included by default when UseMvc() is called, and this is how the Web API starter project handles routing. +ASP.NET 5 no longer uses global.asax, web.config, or App_Start folders. Instead, all startup tasks are done in Startup.cs in the root of the project, and static configuration files can be wired up from there if needed (Learn more about :ref:`ASP.NET 5 Application Startup `). Since Web API is now built into MVC 6, there is less need to configure it. Attribute-based routing is now included by default when UseMvc() is called, and this is the recommended approach for configuring Web API routes (and is how the Web API starter project handles routing). .. literalinclude:: ../../../samples/WebAPIMigration/ProductsDnx/Startup.cs :language: c# :emphasize-lines: 27 :linenos: -If you want to use attribute routing in your project going forward, you don't need to do any additional configuration. You can simply apply the attributes as needed to the API methods or controllers, as is done in the sample ValuesController.cs class that is included in the Web API starter project: +Assuming you want to use attribute routing in your project going forward, you don't need to do any additional configuration. You can simply apply the attributes as needed to your controllers and actions,, as is done in the sample ValuesController.cs class that is included in the Web API starter project: .. literalinclude:: ../../../samples/WebAPIMigration/ProductsDnx/Controllers/ValuesController.cs :language: c# :emphasize-lines: 8,12,19,32,38 :linenos: -In this case, once we copy ProductsController to the new project, we would simply include the route attribute on the controller: +Note the presence of *[controller]* on line 8. Attribute-based routing now supports certain tokens, such as *[controller]* and *[action]* that are replaced at runtime with the name of the controller or action to which the attribute has been applied. This serves to reduce the number of magic strings in the project, and ensures the routes will be kept synchronized with their corresponding controllers and actions when automatic rename refactorings are applied. + +To migrate the Products API controller, we must first copy ProductsController to the new project. Then simply include the route attribute on the controller: .. code-block:: c# [Route("api/[controller]")] -However, if you have a large number of files, or you simply want to configure your routes in one place, rather than on each Controller, you can still configure routing globally. Back in Startup.cs, the UseMvc() call accepts a parameter that defines routing information. You can pass in the same route configuration that was previously defined in WebApiConfig.cs in the old project, like so: +You also need to add the [HttpGet] attribute to the two methods, since they both should be called via HTTP Get. Include the expectation of an "id" parameter in the attribute for GetProduct(): -.. code-block:: c# +.. code-block:: c# - app.UseMvc(routes => - { - routes.MapRoute( - name: "DefaultApi", - template: "api/{controller}/{action}/{id:int?}", - defaults: new { controller = "Products", action = "GetAllProducts" }); - }); + // /api/products + [HttpGet] + ... + + // /api/products/1 + [HttpGet("{id}")] -**Note** `routeTemplate` has been renamed to `template`, and the id parameter has now been marked as being an `int` and option (`?`) without the need for specifying anything in the `defaults` parameter. - -If you are using the `sample project `_, you will need to uncomment the above code block in Startup.cs. - -No additional configuration is required for us to complete the migration. +At this point routing is configured correctly, but we can't yet test it because there are changes we must make before ProductsController will compile. Migrate Models and Controllers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -127,15 +128,15 @@ Once these changes have been made and unused using statements removed, the migra .. literalinclude:: ../../../samples/WebAPIMigration/ProductsDnx/Controllers/ProductsController.cs :language: c# - :emphasize-lines: 1,2,6,8,22,27,29 + :emphasize-lines: 1,2,6,8-9,27,32,34 :linenos: -You should now be able to run the migrated project and browse to /api/products, and you should see the full list of 3 products. +You should now be able to run the migrated project and browse to /api/products, and you should see the full list of 3 products. Browse to /api/products/1 and you should see the first product. Summary ^^^^^^^ -Migrating a simple Web API 2 project to ASP.NET 5 is fairly straightforward, thanks to the fact that Web API has been merged with MVC in ASP.NET 5. The main pieces every Web API 2 project will need to migrate are routes, controllers, and models, along with updates to the types used by ASP.NET 5 controllers and actions. +Migrating a simple Web API 2 project to MVC 6 is fairly straightforward, thanks to the fact that Web API has been merged with MVC 6 in ASP.NET 5. The main pieces every Web API 2 project will need to migrate are routes, controllers, and models, along with updates to the types used by MVC 6 controllers and actions. Related Resources ^^^^^^^^^^^^^^^^^