Creating the WeatherForecast project

The first thing you need is a project to use. This project will rely on an existing Visual Studio 2022 template with some modifications that you normally make when creating a data generator. To create the project, follow these steps:

1. Click Create a New Project in the Visual Studio 2022 start window.

   You see a list of templates to use.

2. Choose C#, All Platforms, and Web in the drop-down list boxes. Locate the ASP.NET Core Web API template, shown in Figure 3-1.

   Notice that the list of environments that the template supports includes desktop operating systems and cloud-based setups. An API can normally run anywhere it has the required support and can service consumers from any browser, which makes APIs extremely versatile. However, you normally start an API locally before moving it to the cloud.

   

3. Highlight the ASP.NET Core Web API template and click Next.

   You see the Configure Your New Project dialog box, shown in Figure 3-2.

4. Type WeatherForecast in the Project Name field and select a location for the project on your hard drive. Make sure that you select the Place Solution and Project in the Same Directory entry, and then click Next.

   You see the Additional Information dialog box, shown in Figure 3-3.

   

   

5. Select .NET Core 3.1 (Long-term Support) in the Framework field and None in the Authentication Type field, and select Configure for HTTPS.

   Public APIs, which number now in the hundreds of thousands (or perhaps even millions), usually don't require any authentication. Private and paid APIs usually do requirement authentication, but this authentication may not take the form of a logon dialog box. Instead, the client passes a special token to the API for verification. Consequently, you may not actually use the standard authentication features for your API very often. Think about how you want clients to authenticate before you create the project.

   It is standard practice to use Secure Sockets Layer (SSL) security for APIs of any sort because it’s incredibly hard to trust the data the client receives otherwise (see https://www.bluehost.com/resources/does-my-website-need-ssl-learn-the-benefits-of-ssl-for-website-security/ and https://www.kaspersky.com/resource-center/definitions/what-is-a-ssl-certificate for details). Deselecting the Configure for HTTPS check box is such a bad idea that it’s hard to understand why Microsoft would even include it in this case. The bottom line is, if you want your client to feel comfortable, always use SSL.

6. Click Create.

   Visual Studio 2022 creates a new web API project for you.

Making the data believable

The default API provided by the Visual Studio 2022 generates weather information randomly. In other words, this is fake data that you could use for testing purposes, but it isn’t based on any real data, nor does it rely on machine learning techniques to compute a forecast. Rather, it’s just values. However, the default setup is lacking in two ways:

• The dates don’t reflect any sort of progression normally associated with weather forecasts. Normally, you see one-, seven-, and ten-day forecasts. Some setups even offer hourly forecasts, but there is always some sort of progression, which the example lacks.
• It’s hard to believe weather data that claims that it’s scorching at 20 degrees below zero, yet the default setup will try its best to convince you that it is indeed scorching. Ignore that icicle hanging off your nose; you’re really overheated!

The code you need to change to make the output more realistic appears in the Controllers folder as WeatherForecastController.cs. Open this file and make the changes shown here:

[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 10).Select(index => GetWeatherForecast())
.ToArray();
}

private int DaysToAdd = 0;

public WeatherForecast GetWeatherForecast()
{
var rng = new Random();

WeatherForecast thisForecast = new WeatherForecast();
thisForecast.Date = DateTime.Now.AddDays(DaysToAdd);
DaysToAdd += 1;
thisForecast.TemperatureC = rng.Next(-20, 40);
switch (thisForecast.TemperatureC)
{
case int n when (n < -14):
thisForecast.Summary = Summaries[0];
break;
case int n when (n >= -14 && n < -7):
thisForecast.Summary = Summaries[1];
break;
case int n when (n >= -7 && n < 0):
thisForecast.Summary = Summaries[2];
break;
case int n when (n >= 0 && n < 6):
thisForecast.Summary = Summaries[3];
break;
case int n when (n >= 6 && n < 12):
thisForecast.Summary = Summaries[4];
break;
case int n when (n >= 12 && n < 18):
thisForecast.Summary = Summaries[5];
break;
case int n when (n >= 18 && n < 24):
thisForecast.Summary = Summaries[6];
break;
case int n when (n >= 24 && n < 30):
thisForecast.Summary = Summaries[7];
break;
case int n when (n >= 30 && n < 36):
thisForecast.Summary = Summaries[8];
break;
case int n when (n >= 36):
thisForecast.Summary = Summaries[9];
break;
}

return thisForecast;
}

The public IEnumerable<WeatherForecast> Get() method is shorter than the original source. It doesn't actually define any data now, but it does create an array of weather predictions. The Enumerable.Range(1, 10) method creates a ten-day forecast, which is more believable than the five-day forecast created by default (although if you look hard enough, you can likely find some website that does provide a five-day forecast).

The WeatherForecast GetWeatherForecast() method defines the weather forecasts one day at a time. To create progressive days, the code calls DateTime.Now.AddDays(DaysToAdd) with a variable, DaysToAdd, that is incremented by 1 during each pass. The temperature in degrees Celsius is a randomly generated number. The temperature in degrees Fahrenheit is calculated in the WeatherForecast.cs file using public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);. Calculated data often appears as part of the output of a data generator. Finally, the code uses a switch to define a Summary value based on the actual temperature (rather than randomly generating it as before). So, when the temperature nears 86 degrees Fahrenheit, the forecast will tell you that it's sweltering and not freezing.

Looking at the API configuration

It’s important to know how to contact your API. To discover this information, open the launchSettings.json file found in the Properties folder. There are two important settings in this file that you can't ignore even if you want to use the defaults in every other way. The first is "sslPort": 44327. The number that follows sslPort specifies the port number used to access your web service. You can ignore the applicationUrl setting because you won't use it to access the API; only the sslPort setting matters. This means that you’ll use https://localhost:4432/7/ as the base URL to access this web service. (The port number, 4432, varies by system.)

The second setting you need to know is "launchUrl": "weatherforecast". This setting defines where your client can find the actual API. Consequently, the full URL for accessing the API is https://localhost:44327/weatherforecast. This is an essential bit of information because you need it later when creating the client.

Checking the API for functionality

You can check your API before you develop the client. The output won't be very exciting, but you can see that the API works as expected. The following sections explain how to check your API for functionality.

Viewing the data in a browser

The first place you want to look for API functionality is your browser. Choose Debug⇒  Start Without Debugging. The first thing you’ll normally see is a dialog box asking whether you want to install an SSL certificate for your project, as shown in Figure 3-4.

Unless you really enjoy having your browser ask you about the website you’re testing over and over until you finally go crazy, you’ll click Yes. Because the certificate is working only with your project, you don’t need to worry much about opening huge security holes in your system.

Immediately after you click Yes, Windows will usually display another dialog box asking whether you’re sure you want to install the certificate, as shown in Figure 3-5. Obviously, Visual Studio 2022 and Windows don’t talk, so you have to answer essentially the same question twice.

Just about the time you start to think that you may never see your API in action, a browser window comes up and you see the serialized JSON data shown in Figure 3-6. The background code for your API automatically takes care of the serialization for you based on the array created by the public IEnumerable<WeatherForecast> Get() call. There are a lot of fancy reasons for this happening, such as the addition of the [HttpGet] attribute to the method call, which you can read about at https://docs.microsoft.com/aspnet/core/mvc/controllers/routing and https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.httpgetattribute, but the main thing to know is that it simply works as it should without any additional coding on your part.

Locating the IIS icon

If you've followed the process outlined in previous sections of this chapter, you now have a service. For a service to be useful, it must continue running until you don’t need it any longer. In the Windows Notification Area, you see an IIS Express icon like the one shown in Figure 3-7. Right-clicking this icon displays a list of the running websites. In addition, you see controls for interacting with the websites.

Knowing about the IIS Express icon is very important because developers often spend a great deal of time looking for errors in their website code, only to find that the service isn’t running. You can save yourself time and embarrassment by looking for this icon.

Creating the RetrieveWeatherForecast project

To begin using the WeatherForecast API, you need a web application. Follow these steps to create the example web application:

1. Click Create a New Project in the Visual Studio 2022 start window.

   You see a list of templates to use that are similar to the ones shown previously in Figure 3-1.

2. Choose C#, All Platforms, and Web in the drop-down list boxes. Locate the ASP.NET Core Web App template.

3. Highlight the ASP.NET Core Web App template and click Next.

   You see a Configure Your New Project dialog box similar to the one shown previously in Figure 3-2.

4. Type RetrieveWeatherForecast in the Project Name field and select a location for the project on your hard drive. Make sure to select the Place Solution and Project in the Same Directory entry, and then click Next.

   You see an Additional Information dialog box similar to the one shown previously in Figure 3-3.

5. Select .NET Core 3.1 (Long-term Support) in the Framework field and None in the Authentication Type field, and then select Configure for HTTPS.

   Because this is likely a critical business application, using SSL makes sense in this situation. Whether you use SSL for informational sites depends on the perceived risk from the client interacting with the data. When in doubt, use SSL.

6. Click Create.

   Visual Studio 2022 creates a new web app project for you.

Developing a user interface

Because you have no designer to use for ASP.NET Core Web App applications, it's somewhat important to use a little trial and error in putting the interface together. Most people have a hard time visualizing what the website will eventually look like based solely on the code, so making a few changes and then viewing the website is the best option you have. The following sections tell you more about creating a user interface for this example.

If you make changes to the interface, they may not always show up, which is really frustrating. Unfortunately, if the web application site is kept running, you may see the old code, not the new code. To prevent major hair loss, stop the application website (not the WeatherForecast service website) after each change to your code. You can stop it by clicking Stop Site, as shown in Figure 3-8 in the IIS Express icon in the Notification Area (described in the “Locating the IIS icon” section of the chapter).

Getting and deserializing the data

It's finally time to show how the various elements of this example are put together to display information onscreen. The following sections help you get through the process of working through deserialization and then display as HTML output.

Adding the WeatherForecast class

To deserialize the data from the WeatherForecast API, you need a class that describes the data. Fortunately, you already have such a class. It appears in the WeatherForecast project. Use these steps to add the class to your RetrieveWeatherForecast project:

1. Right-click the RetrieveWeatherForecast entry in Solution Explorer and choose Add⇒  Existing Item from the context menu.

   You see an Add Existing Item dialog box.

2. Navigate to the WeatherForecast project folder, as shown in Figure 3-9, and highlight WeatherForecast.cs. Click Add.

   You see the WeatherForecast.cs file added to your project.

There is only one problem with the file you've just imported. The variable names are all initial capitalized, such as Date. However, if you look at Figure 3-6, shown previously, you see that the variables are lowercase, such as date. Because C# is a case-sensitive language, you need to make the variables in the copy of WeatherForecast.cs that you just imported into your RetrieveWeatherForecast project lowercase as well, so it now appears like this:

using System;

namespace RetrieveWeatherForecast
{
public class WeatherForecast
{
public DateTime date { get; set; }

public int temperatureC { get; set; }

public int temperatureF => 32 + (int)(temperatureC / 0.5556);

public string summary { get; set; }
}
}

Seeing the application in action

After completing the previous sections in the chapter, at this point you can finally run the application and see a result. Make sure that you have both the WeatherForecast and the RetrieveWeatherForecast projects open, and that the WeatherForecast service is running (as described in the “Locating the IIS icon” section of the chapter). Otherwise, the example won't work. Choose Debug⇒  Start Without Debugging. You see the weather forecast (simulated) for the next ten days, as shown in Figure 3-10 (your data likely won’t match).

Even though this is a simplistic view of web design, it’s what happens in a great many instances today. Organizations are only too happy to use data generated by someone else when it suits their needs, and the techniques shown in this chapter help you obtain the required access to the data.