• C# 7.3:
  • This page describes the latest features in the C# language. C# 7.3 is currently available in Visual Studio 2017 version 15.7, and in the .NET Core 2.1 SDK 2.1.300 RC1.
• C# 7.2:
  • This page describes the features added in the C# language. C# 7.2 is currently available in Visual Studio 2017 version 15.5, and in the .NET Core 2.0 SDK.
• C# 7.1:
  • This page describes the features added in C# 7.1. These features were added in Visual Studio 2017 version 15.3, and in the .NET Core 2.0 SDK.
• C# 7.0:
  • This page describes the features added in C# 7.0. These features were added in Visual Studio 2017 and .NET Core 1.0 and later
• C# 6:
  • This page describes the features that were added in C# 6. These features are available in Visual Studio 2015 for Windows developers, and on .NET Core 1.0 for developers exploring C# on macOS and Linux.
• Cross Platform Support:
  • C#, through .NET Core support, runs on multiple platforms. If you are interested in trying C# on macOS, or on one of the many supported Linux distributions, learn more about .NET Core.
• .NET Compiler Platform SDK:
  • The .NET Compiler Platform SDK enables you to write code that performs static analysis on C# code. You can use these APIs to find potential errors, or bad practices, suggest fixes, and even implement those fixes.

Previous Versions

• Visual Studio .NET 2013:
  • This version of Visual Studio included bug fixes, performance improvements, and technology previews of .NET Compiler Platform (“Roslyn”) which became the .NET Compiler Platform SDK.
• C# 5, Visual Studio .NET 2012:
  • Async / await, and caller information attributes.
• C# 4, Visual Studio .NET 2010:
  • Dynamic, named arguments, optional parameters, and generic covariance and contra variance.
• C# 3, Visual Studio .NET 2008:
  • Object and collection initializers, lambda expressions, extension methods, anonymous types, automatic properties, local var type inference, and Language Integrated Query (LINQ).
• C# 2, Visual Studio .NET 2005:
  • Anonymous methods, generics, nullable types, iterators/yield, static classes, and covariance and contra variance for delegates.
• C# 1.1, Visual Studio .NET 2003:
  • #line pragma and xml doc comments.
• C# 1, Visual Studio .NET 2002:
  • The first release of C#.

.NET

Languages

• C# is a simple, modern, object-oriented, and type-safe programming language.
• F# is a cross-platform, open-source, functional programming language for .NET. It also includes object-oriented and imperative programming.
• Visual Basic is an approachable language with a simple syntax for building type-safe, object-oriented apps.

Cross Platform

• .NET Core is a cross-platform .NET implementation for websites, servers, and console apps on Windows, Linux, and macOS.
• .NET Framework supports websites, services, desktop apps, and more on Windows.
• Xamarin/Mono is a .NET implementation for running apps on all the major mobile operating systems.

One consistent API

Libraries

What is ASP.NET Core ?

ASP.NET Core is a new open-source and cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.
ASP.NET Core is the open-source version of ASP.NET, that runs on Windows, Linux, macOS, and Docker.
ASP.NET Core is a cross-platform, high-performance, open-source framework for building modern, cloud-based, Internet-connected applications. With ASP.NET Core, you can:
• Build web apps and services, IoT apps, and mobile backends.
• Use your favorite development tools on Windows, macOS, and Linux.
• Deploy to the cloud or on-premises.
• Run on .NET Core or .NET Framework.
ASP.NET is a popular web-development framework for building web apps on the .NET platform.
ASP.NET Core is the open-source version of ASP.NET, that runs on macOS, Linux, and Windows. ASP.NET Core was first released in 2016 and is a re-design of earlier Windows-only versions of ASP.NET.
Why ASP.NET Core?
Millions of developers have used (and continue to use) ASP.NET 4.x to create web apps. ASP.NET Core is a redesign of ASP.NET 4.x, with architectural changes that result in a leaner, more modular framework.
ASP.NET Core provides the following benefits:
• A unified story for building web UI and web APIs.
• Architected for testability.
• Razor Pages makes coding page-focused scenarios easier and more productive.
• Ability to develop and run on Windows, macOS, and Linux.
• Open-source and community-focused.
• Integration of modern, client-side frameworks and development workflows.
• A cloud-ready, environment-based configuration system.
• Built-in dependency injection.
• A lightweight, high-performance, and modular HTTP request pipeline.
• Ability to host on IIS, Nginx, Apache, Docker, or self-host in your own process.
• Side-by-side app versioning when targeting .NET Core.
• Tooling that simplifies modern web development.

Performance

Performance is a key focus of ASP.NET Core. It’s faster than other popular web frameworks in the independent TechEmpower benchmarks.

Modern & innovative

ASP.NET Core is designed to allow runtime components, APIs, compilers and languages evolve quickly, while still providing a stable and supported platform to keep apps running.
Multiple versions of ASP.NET Core can exists side-by-side on the same server. Meaning one app can adopt the latest version, while other apps keep running on the version they were tested on.
ASP.NET Core provides various support lifecycle options to meet the needs of your app. You can chose a long-term support release, or run with the latest release if you commit to upgrade more often. See our support policy for more details.

Open-source

Like the rest of .NET, ASP.NET is open source on GitHub. Over 60,000 developers and 3,700 companies have already contributed to .NET.

Windows, Linux, macOS, and Docker

ASP.NET apps can be developed and run on Windows, Linux, macOS, and Docker.
The Visual Studio family of products has tools for building .NET apps on any operating system. There are also command line tools and extensions for many popular editors.

Flexible deployment

The ASP.NET Core runtime that your app runs on can be deployed as part of your app, or installed centrally on your web server. ASP.NET Core is also perfectly suited for Docker containers.

What is ASP.NET ?

In recent years, it has become clear that HTTP is not just for serving up HTML pages. It is also a powerful platform for building Web APIs, using a handful of verbs (GET, POST, and so forth) plus a few simple concepts such as URIs and headers. ASP.NET Web API is a set of components that simplify HTTP programming. Because it is built on top of the ASP.NET MVC runtime, Web API automatically handles the low-level transport details of HTTP. At the same time, Web API naturally exposes the HTTP programming model. In fact, one goal of Web API is to not abstract away the reality of HTTP. As a result, Web API is both flexible and easy to extend. In this hands-on lab, you will use Web API to build a simple REST API for a contact manager application. You will also build a client to consume the API. The REST architectural style has proven to be an effective way to leverage HTTP – although it is certainly not the only valid approach to HTTP. The contact manager will expose the RESTful for listing, adding and removing contacts, among others. This lab requires a basic understanding of HTTP, REST, and assumes you have a basic working knowledge of HTML, JavaScript, and jQuery.

Note

The ASP.NET Web site has an area dedicated to the ASP.NET Web API framework at https://asp.net/web-api. This site will continue to provide late-breaking information, samples, and news related to Web API, so check it frequently if you’d like to delve deeper into the art of creating custom Web APIs available to virtually any device or development framework.

ASP.NET Web API, similar to ASP.NET MVC 4, has great flexibility in terms of separating the service layer from the controllers allowing you to use several of the available Dependency Injection frameworks fairly easy. There is a good sample in MSDN that shows how to use Ninject for dependency injection in an ASP.NET Web API project that you can download it from here.

Objectives

• Implement a RESTful Web API
• Call the API from an HTML client

Prerequisites

• Microsoft Visual Studio Express 2012 for Web or superior (read Appendix B for instructions on how to install it).

Setup

Exercises

1. Exercise 1: Create a Read-Only Web API
2. Exercise 2: Create a Read/Write Web API
3. Exercise 3: Consume the Web API from an HTML Client

Exercise 1: Create a Read-Only Web API

Task 1 – Creating the API Project

1. Run Visual Studio 2012 Express for Web, to do this go to Start and type VS Express for Web then press Enter.
2. From the File menu, select New Project. Select the Visual C# | Web project type from the project type tree view, then select the ASP.NET MVC 4 Web Application project type. Set the project’s Name to ContactManager and the Solution name to Begin, then click OK.
   
   Creating a new ASP.NET MVC 4.0 Web Application Project
3. In the ASP.NET MVC 4 project type dialog, select the Web API project type. Click OK.
   
   Specifying the Web API project type

Task 2 – Creating the Contact Manager API Controllers

1. Delete the file named ValuesController.cs within Controllers folder from the project.
2. Right-click the Controllers folder in the project and select Add | Controller from the context menu.
   
   Adding a new controller to the project
3. In the Add Controller dialog that appears, select Empty API Controller from the Template menu. Name the controller class ContactController. Then, click Add.
   
   Using the Add Controller dialog to create a new Web API controller
4. Add the following code to the ContactController.
   (Code Snippet – Web API Lab – Ex01 – Get API Method)
   C#Copy

   public string[] Get()
   {
       return new string[]
       {
           "Hello",
           "World"
       };
   }
   

5. Press F5 to debug the application. The default home page for a Web API project should appear.
   
   The default home page of an ASP.NET Web API application
6. In the Internet Explorer window, press the F12 key to open the Developer Tools window. Click the Network tab, and then click the Start Capturing button to begin capturing network traffic into the window.
   
   Opening the network tab and initiating network capture
7. Append the URL in the browser’s address bar with /api/contact and press enter. The transmission details will appear in the network capture window. Note that the response’s MIME type is application/json. This demonstrates how the default output format is JSON.
   
   Viewing the output of the Web API request in the Network view
   Note

   Internet Explorer 10’s default behavior at this point will be to ask if the user would like to save or open the stream resulting from the Web API call. The output will be a text file containing the JSON result of the Web API URL call. Do not cancel the dialog in order to be able to watch the response’s content through Developers Tool window.
8. Click the Go to detailed view button to see more details about the response of this API call.
   
   Switch to Detailed View
9. Click the Response body tab to view the actual JSON response text.
   
   Viewing the JSON output text in the network monitor

Task 3 – Creating the Contact Models and Augment the Contact Controller

1. Right-click the Models folder and select Add | Class… from the context menu.
   
   Adding a new model to the web application
2. In the Add New Item dialog, name the new file Contact.cs and click Add.
   
   Creating the new Contact class file
3. Add the following highlighted code to the Contact class.
   (Code Snippet – Web API Lab – Ex01 – Contact Class)
   C#Copy

   public class Contact
   {
       public int Id { get; set; }
   
       public string Name { get; set; }
   }
   

4. In the ContactController class, select the word string in method definition of the Getmethod, and type the word Contact. Once the word is typed in, an indicator will appear at the beginning of the word Contact. Either hold down the Ctrl key and press the period (.) key or click the icon using your mouse to open up the assistance dialog in the code editor, to automatically fill in the using directive for the Models namespace.
   
   Using Intellisense assistance for namespace declarations
5. Modify the code for the Get method so that it returns an array of Contact model instances.
   (Code Snippet – Web API Lab – Ex01 – Returning a list of contacts)
   C#Copy

   public Contact[] Get()
   {
       return new Contact[]
       {
           new Contact
           {
               Id = 1,
               Name = "Glenn Block"
           },
           new Contact
           {
               Id = 2,
               Name = "Dan Roth"
           }
       };
   }
   

6. Press F5 to debug the web application in the browser. To view the changes made to the response output of the API, perform the following steps.
   1. Once the browser opens, press F12 if the developer tools are not open yet.
   2. Click the Network tab.
   3. Press the Start Capturing button.
   4. Add the URL suffix /api/contact to the URL in the address bar and press the Enterkey.
   5. Press the Go to detailed view button.
   6. Select the Response body tab. You should see a JSON string representing the serialized form of an array of Contact instances.
      
      JSON serialized output of a complex Web API method call

Task 4 – Extracting Functionality into a Service Layer

1. Create a new folder in the solution root and name it Services. To do this, right-click ContactManager project, select Add | New Folder, name it Services.
   
   Creating Services folder
2. Right-click the Services folder and select Add | Class… from the context menu.
   
   Adding a new class to the Services folder
3. When the Add New Item dialog appears, name the new class ContactRepository and click Add.
   
   Creating a class file to contain the code for the Contact Repository service layer
4. Add a using directive to the ContactRepository.cs file to include the models namespace.
   C#Copy

   using ContactManager.Models;
   

5. Add the following highlighted code to the ContactRepository.cs file to implement GetAllContacts method.
   (Code Snippet – Web API Lab – Ex01 – Contact Repository)
   C#Copy

   public class ContactRepository
   {
       public Contact[] GetAllContacts()
       {
           return new Contact[]
           {
               new Contact
               {
                   Id = 1,
                   Name = "Glenn Block"
               },
               new Contact
               {
                   Id = 2,
                   Name = "Dan Roth"
               }
           };
       }
   }
   

6. Open the ContactController.cs file if it is not already open.
7. Add the following using statement to the namespace declaration section of the file.
   C#Copy

   using ContactManager.Services;
   

8. Add the following highlighted code to the ContactController.cs class to add a private field to represent the instance of the repository, so that the rest of the class members can make use of the service implementation.
   (Code Snippet – Web API Lab – Ex01 – Contact Controller)
   C#Copy

   public class ContactController : ApiController
   {
       private ContactRepository contactRepository;
   
       public ContactController()
       {
           this.contactRepository = new ContactRepository();
       } 
       ...
   }
   

9. Change the Get method so that it makes use of the contact repository service.
   (Code Snippet – Web API Lab – Ex01 – Returning a list of contacts via the repository)
   C#Copy

   public Contact[] Get()
   {
       return contactRepository.GetAllContacts();
   }
   

10. Put a breakpoint on the ContactController‘s Get method definition.

![Network view in Internet Explorer showing results of the Web API call](build-restful-apis-with-aspnet-web-api/_static/image19.png "Network view in Internet Explorer showing results of the Web API call")

*Network view in Internet Explorer showing results of the Web API call*

19. Click the Go to detailed view button.
20. Click the Response body tab. Note the JSON output of the API call, and how it represents the two contacts retrieved by the service layer.
    
    Viewing the JSON output from the Web API in the developer tools window

Exercise 2: Create a Read/Write Web API

Task 1 – Opening the Web API Project

1. Run Visual Studio 2012 Express for Web, to do this go to Start and type VS Express for Web then press Enter.
2. Open the Begin solution located at Source/Ex02-ReadWriteWebAPI/Begin/ folder. Otherwise, you might continue using the End solution obtained by completing the previous exercise.
   1. If you opened the provided Begin solution, you will need to download some missing NuGet packages before continue. To do this, click the Project menu and select Manage NuGet Packages.
   2. In the Manage NuGet Packages dialog, click Restore in order to download missing packages.
   3. Finally, build the solution by clicking Build | Build Solution.
      Note

      One of the advantages of using NuGet is that you don’t have to ship all the libraries in your project, reducing the project size. With NuGet Power Tools, by specifying the package versions in the Packages.config file, you will be able to download all the required libraries the first time you run the project. This is why you will have to run these steps after you open an existing solution from this lab.
3. Open the Services/ContactRepository.cs file.

Task 2 – Adding Data-Persistence Features to the Contact Repository Implementation

1. Add the following constant to the ContactRepository class to represent the name of the web server cache item key name later in this exercise.
   C#Copy

   private const string CacheKey = "ContactStore";
   

2. Add a constructor to the ContactRepository containing the following code.
   (Code Snippet – Web API Lab – Ex02 – Contact Repository Constructor)
   C#Copy

   public ContactRepository()
   {
       var ctx = HttpContext.Current;
   
       if (ctx != null)
       {
           if (ctx.Cache[CacheKey] == null)
           {
               var contacts = new Contact[]
               {
                   new Contact
                   {
                       Id = 1, Name = "Glenn Block"
                   },
                   new Contact
                   {
                       Id = 2, Name = "Dan Roth"
                   }
               };
   
               ctx.Cache[CacheKey] = contacts;
           }
       }
   }
   

3. Modify the code for the GetAllContacts method as demonstrated below.
   (Code Snippet – Web API Lab – Ex02 – Get All Contacts)
   C#Copy

   public Contact[] GetAllContacts()
   {
       var ctx = HttpContext.Current;
   
       if (ctx != null)
       {
           return (Contact[])ctx.Cache[CacheKey];
       }
   
       return new Contact[]
           {
               new Contact
               {
                   Id = 0,
                   Name = "Placeholder"
               }
           };
   }
   

   Note

   This example is for demonstration purposes and will use the web server’s cache as a storage medium, so that the values will be available to multiple clients simultaneously, rather than use a Session storage mechanism or a Request storage lifetime. One could use Entity Framework, XML storage, or any other variety in place of the web server cache.
4. Implement a new method named SaveContact to the ContactRepository class to do the work of saving a contact. The SaveContact method should take a single Contactparameter and return a Boolean value indicating success or failure.
   (Code Snippet – Web API Lab – Ex02 – Implementing the SaveContact Method)
   C#Copy

   public bool SaveContact(Contact contact)
   {
       var ctx = HttpContext.Current;
   
       if (ctx != null)
       {
            try
            {
                 var currentData = ((Contact[])ctx.Cache[CacheKey]).ToList();
                 currentData.Add(contact);
                 ctx.Cache[CacheKey] = currentData.ToArray();
   
                 return true;
            }
            catch (Exception ex)
            {
                 Console.WriteLine(ex.ToString());
                 return false;
            }
       }
   
       return false;
   }
   

Exercise 3: Consume the Web API from an HTML Client

Task 1 – Modifying the Index View to Provide a GUI for Displaying Contacts

1. Open Visual Studio 2012 Express for Web if it is not already open.
2. Open the Begin solution located at Source/Ex03-ConsumingWebAPI/Begin/ folder. Otherwise, you might continue using the End solution obtained by completing the previous exercise.
   1. If you opened the provided Begin solution, you will need to download some missing NuGet packages before continue. To do this, click the Project menu and select Manage NuGet Packages.
   2. In the Manage NuGet Packages dialog, click Restore in order to download missing packages.
   3. Finally, build the solution by clicking Build | Build Solution.
      Note

      One of the advantages of using NuGet is that you don’t have to ship all the libraries in your project, reducing the project size. With NuGet Power Tools, by specifying the package versions in the Packages.config file, you will be able to download all the required libraries the first time you run the project. This is why you will have to run these steps after you open an existing solution from this lab.
3. Open the Index.cshtml file located at Views/Home folder.
4. Replace the HTML code within the div element with id body so that it looks like the following code.
   HTMLCopy

   <div id="body">
       <ul id="contacts"></ul>
   </div>
   

5. Add the following Javascript code at the bottom of the file to perform the HTTP request to the Web API.
   CSHTMLCopy

   @section scripts{
   <script type="text/javascript">
   $(function()
   {
           $.getJSON('/api/contact', function(contactsJsonPayload)
           {
               $(contactsJsonPayload).each(function(i, item)
               {
                   $('#contacts').append('
   ' + item.Name + '
   ');
               });
           });
   });
   </script>
   }
   

6. Open the ContactController.cs file if it is not already open.
7. Place a breakpoint on the Get method of the ContactController class.
   
   Placing a breakpoint on the Get method of the API controller
8. Press F5 to run the project. The browser will load the HTML document.
   Note

   Ensure that you are browsing to the root URL of your application.
9. Once the page loads and the JavaScript executes, the breakpoint will be hit and the code execution will pause in the controller.
   
   Debugging into the Web API call using Visual Studio 2012 Express for Web
10. Remove the breakpoint and press F5 or the debugging toolbar’s Continue button to continue loading the view in the browser. Once the Web API call completes you should see the contacts returned from the Web API call displayed as list items in the browser.
    
    Results of the API call displayed in the browser as list items
11. Stop debugging.

Task 2 – Modifying the Index View to Provide a GUI for Creating Contacts

1. Open the ContactController.cs file.
2. Add a new method to the controller class named Post as shown in the following code.
   (Code Snippet – Web API Lab – Ex03 – Post Method)
   C#Copy

   public HttpResponseMessage Post(Contact contact)
   {
       this.contactRepository.SaveContact(contact);
   
       var response = Request.CreateResponse(System.Net.HttpStatusCode.Created, contact);
   
       return response;
   }
   

3. Open the Index.cshtml file in Visual Studio if it is not already open.
4. Add the HTML code below to the file just after the unordered list you added in the previous task.
   HTMLCopy

   <form id="saveContactForm" method="post">
   <h3>Create a new Contact</h3>
   <p>
       <label for="contactId">Contact Id:</label>
       <input type="text" name="Id" />
   </p>
   <p>
       <label for="contactName">Contact Name:</label>
       <input type="text" name="Name" />
   </p>
   <input type="button" id="saveContact" value="Save" />
   </form>
   

5. Within the script element at the bottom of the document, add the following highlighted code to handle button-click events, which will post the data to the Web API using an HTTP POST call.
   HTMLCopy

   <script type="text/javascript">
   ... 
   $('#saveContact').click(function()
            {
                 $.post("api/contact",
                       $("#saveContactForm").serialize(),
                       function(value)
                       {
                            $('#contacts').append('
   ' + value.Name + '
   ');
                       },
                       "json"
                 );
            });
   </script>
   

6. In ContactController.cs, place a breakpoint on the Post method.
7. Press F5 to run the application in the browser.
8. Once the page is loaded in the browser, type in a new contact name and Id and click the Save button.
   
   The client HTML document loaded in the browser
9. When the debugger window breaks in the Post method, take a look at the properties of the contact parameter. The values should match the data you entered in the form.
   
   The Contact object being sent to the Web API from the client
10. Step through the method in the debugger until the response variable has been created. Upon inspection in the Locals window in the debugger, you’ll see that all the properties have been set.

Summary