update WebApi to .NET 9 (without Swagger) #34746

timdeschryver · 2025-02-17T18:25:55Z

This PR:

updates example to .NET 9, including NuGet packages
- migrates to file-scoped namespaces to keep things consistent
add swagger example to test with VSCode (similar to the minimal web api docs at https://learn.microsoft.com/en-us/aspnet/core/tutorials/min-web-api?view=aspnetcore-9.0&tabs=visual-studio-code)
create and use new screenshots because of some small differences
update docs to reference .NET 9 standard support
update docs to use new sample and screenshots
- update code reference import style from [!code-csharp[](~/tutorials/first-web-api/samples/9.0/TodoApi/Models/TodoItem.cs)] to :::code language="csharp" source="~/tutorials/first-web-api/samples/9.0/TodoApi_SwaggerVersion/Models/TodoItem.cs":::
remove swashbuckle references and update with http files (Visual Studio) and NSwag Swagger (Visual Studio code)

Review tip: because of the namespaces it can be easier to hide whitespace changes.

Internal previews

📄 File	🔗 Preview link
aspnetcore/tutorials/first-web-api.md	Tutorial: Create a controller-based web API with ASP.NET Core

wadepickett · 2025-02-18T21:52:12Z

I'm so sorry @timdeschryver, I was already in the middle of updating this topic after another community member started a PR #34676 on it more than a week ago. It went through a review along with more updates which I am currently dropping in for that PR.

Looking back I see you asked about updating this topic and I missed it!!!

I will look this over but, it has already been done, so this one will likely be closed.

Rick-Anderson · 2025-02-18T23:31:07Z

I'm so sorry @timdeschryver, I was already in the middle of updating this topic after another community member started a PR #34676 on it more than a week ago. It went through a review along with more updates which I am currently dropping in for that PR.

Looking back I see you asked about updating this topic and I missed it!!!

I will look this over but, it has already been done, so this one will likely be closed.

This one is ready, why don't we take it and apologize to #34676?
I can get the review on this finished today and have it merged and live tonight.

wadepickett · 2025-02-19T08:16:13Z

@Rick-Anderson, closed the other one.

timdeschryver · 2025-02-19T09:08:34Z

No problem.
Sorry, I didn't see the other PR.

timdeschryver · 2025-02-19T19:02:36Z

I went over the other PR, and applied minor changes (2edb359) within this PR.

Looking at the comments, I also want to highlight I added Visual Studio instructions using http files, and Visual Studio Code examples using Swagger (with NSwag.AspNetCore). These samples are using a different project.

I based this on the Minimal API docs, which is also created with this structure.

wadepickett · 2025-02-19T20:38:47Z

aspnetcore/tutorials/first-web-api/_static/9/create-new-project-empty-vs17.11.0.png

This screenshot does not get used in the update. (It also shows the wrong project template, Empty instead of ASP.NET Core web API). I think we don't really need the screenshot anyway for this tutorial so it could just be deleted.

Good catch, I must have have copy-pasted this from the previous docs and forgot to remove it.
Thanks for the review!

Rick-Anderson · 2025-02-19T23:42:05Z

@Rick-Anderson, closed the other one.

Who closed what? #34676 is still open. Need to close one of them.

Control-click on a project in VSC on windows does not work, must be Right-click for Windows and Control-click on macOS for VSC.

wadepickett · 2025-02-20T00:12:28Z

@Rick-Anderson, closed the other one.

Who closed what? #34676 is still open. Need to close one of them.

I re-opened for a moment to get a build to check against and left a note there indicating so. Closing it in a minute.

aspnetcore/tutorials/first-web-api.md

Rick-Anderson · 2025-02-20T00:31:55Z

aspnetcore/tutorials/first-web-api.md

+* Run the following command:
+
+  ```dotnetcli
+  dotnet add package NSwag.AspNetCore
+  ```


I think this is where you need # [Visual Studio Code](#tab/visual-studio-code) and VSC

@Rick-Anderson, NSwag/Swagger setup is only being used for VSC here. The VSC tab is set currently for the entire section here: ## Create API testing UI with Swagger

That seems right the way the tabs are set here. Maybe I don't understand what you are referring to.

aspnetcore/tutorials/first-web-api.md

wadepickett

@timdeschryver, excellent work. Thanks also for adding in my changes from dupe PR. I just made some minor changes here. See my comment on removing the New Project screenshot (_static/9/create-new-project-empty-vs17.11.0.png) and Rick's notes.

Rick-Anderson · 2025-02-20T01:21:48Z

@timdeschryver see my commits, I think you had an errant VS/VSC block which I removed.

Public review of the doc build:

download the HTML files
unzip
view HTML file in a browser.
For links outside the doc, remove the review. from URL.

Rick-Anderson

I'm going to merge this once you have a look at the build @timdeschryver
I'll then publish live and you can take a closer look.

Rick-Anderson

revert comment out VSC

aspnetcore/tutorials/first-web-api.md

revert

Rick-Anderson · 2025-02-20T01:43:03Z

aspnetcore/tutorials/first-web-api.md

+# [Visual Studio](#tab/visual-studio) -->
+
+This tutorial uses [Endpoints Explorer and .http files](xref:test/http-files#use-endpoints-explorer) to test the API.
+


@timdeschryver @wadepickett the change was so abrupt I thought it was a mistake. How about a suggestion to Create API testing UI with Swagger?

Suggested change

For an alternative testing approach, select the Visual Studio Code tab and use the CLI to perform the steps.

Do you mean to write "Select the Visual Studio Code" tab? They are already on the VS tab at this point. I think it would make things a little confusing. They could get through it, but it feels a bit awkward.

Do you mean to write "Select the Visual Studio Code" tab? They are already on the VS tab at this point. I think it would make things a little confusing. They could get through it, but it feels a bit awkward.

Yes, forgot Code,
so there's no value in VSC customers doing that section?

There's value, minus a bit of awkward. I ran through at that point from VS to VS Code instruction, it works. Consider making it clear that the Swagger option is instead. Also cap "Swagger"

To be honest, I also find the current wording/format unclear.
If we change this, we should also re-evaluate the minimal api docs (https://learn.microsoft.com/en-us/aspnet/core/tutorials/min-web-api?view=aspnetcore-9.0&tabs=visual-studio-code#add-the-api-code), which uses the same format.

I believe the reasoning behind the current format is that Visual Studio supports http files by default, and thus swagger isn't required.
For Visual Studio Code this is not the case, an extension needs to be installed to use http files. That's why I assume the Swagger setup is added to the Visual Studio Code tabs.

I like the suggestion from @Rick-Anderson .
An alternative is to remove the Visual Studio/Visual Studio Code setup and suggest users to install the http files extension, or point them to the "Test with other tools" section for alternatives.

If I need to update something feel free to add it here.

(Thanks for the thorough review!)

aspnetcore/tutorials/first-web-api.md

wadepickett

Awesome, thanks!

timdeschryver added 7 commits February 16, 2025 09:33

Update .NET version references in first-web-api.md to 9.0

9eba0f4

update sample to target .NET 9.0

e05e297

rename example to _SwaggerExample

0232419

add OpenAPI example (no swagger)

3c483c5

update WebApi to .NET 9 (without swagger)

d532b83

remove unused example

b398f8f

review fixes

f225fc8

guardrex requested a review from wadepickett February 18, 2025 11:56

wadepickett requested a review from Rick-Anderson February 19, 2025 06:33

wadepickett mentioned this pull request Feb 19, 2025

Updated first-web-api tutorial #34676

Closed

wadepickett removed their request for review February 19, 2025 17:08

apply changes from dotnet#34676

2edb359

include IsDevelopment codeblock to match the text description

39250f2

wadepickett reviewed Feb 19, 2025

View reviewed changes

VS new project settings moved to order they appear in dialog

c134c50

Right-click or Command-click on project in VSC

7db873a

Control-click on a project in VSC on windows does not work, must be Right-click for Windows and Control-click on macOS for VSC.

wadepickett reviewed Feb 20, 2025

View reviewed changes

aspnetcore/tutorials/first-web-api.md Outdated Show resolved Hide resolved

Specifying the DTO file and location in the instruction

af7c6b2

wadepickett self-requested a review February 20, 2025 00:33

Rick-Anderson requested changes Feb 20, 2025

View reviewed changes

Apply suggestions from code review

116737a

wadepickett requested changes Feb 20, 2025

View reviewed changes

Update author names in web API tutorial

af28712

Add comment block in first-web-api tutorial

5246910

Rick-Anderson approved these changes Feb 20, 2025

View reviewed changes

Rick-Anderson reviewed Feb 20, 2025

View reviewed changes

aspnetcore/tutorials/first-web-api.md Outdated Show resolved Hide resolved

aspnetcore/tutorials/first-web-api.md Outdated Show resolved Hide resolved

aspnetcore/tutorials/first-web-api.md Outdated Show resolved Hide resolved

Apply suggestions from code review

c01b23e

revert

Rick-Anderson reviewed Feb 20, 2025

View reviewed changes

aspnetcore/tutorials/first-web-api.md Outdated Show resolved Hide resolved

Rick-Anderson and others added 2 commits February 19, 2025 15:45

Update aspnetcore/tutorials/first-web-api.md

7707f76

remove unused file 'create-new-project'

5ee6a42

wadepickett self-requested a review February 20, 2025 18:59

wadepickett approved these changes Feb 20, 2025

View reviewed changes

wadepickett self-assigned this Feb 20, 2025

wadepickett merged commit 517d959 into dotnet:main Feb 20, 2025
3 checks passed

wadepickett mentioned this pull request Feb 20, 2025

Create Web API: v9 update sample update and rewrite for VSC version OpenAPI UI gen #33001

Closed

timdeschryver deleted the issues/34524 branch February 21, 2025 18:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update WebApi to .NET 9 (without Swagger) #34746

update WebApi to .NET 9 (without Swagger) #34746

timdeschryver commented Feb 17, 2025 •

edited by github-actions bot

Loading

wadepickett commented Feb 18, 2025 •

edited

Loading

Rick-Anderson commented Feb 18, 2025

wadepickett commented Feb 19, 2025

timdeschryver commented Feb 19, 2025

timdeschryver commented Feb 19, 2025

wadepickett Feb 19, 2025 •

edited

Loading

timdeschryver Feb 20, 2025

Rick-Anderson commented Feb 19, 2025

wadepickett commented Feb 20, 2025 •

edited

Loading

Rick-Anderson Feb 20, 2025

wadepickett Feb 20, 2025

wadepickett left a comment •

edited

Loading

Rick-Anderson commented Feb 20, 2025

Rick-Anderson left a comment

Rick-Anderson left a comment

Rick-Anderson Feb 20, 2025 •

edited

Loading

wadepickett Feb 20, 2025 •

edited

Loading

Rick-Anderson Feb 20, 2025

wadepickett Feb 20, 2025

timdeschryver Feb 20, 2025 •

edited

Loading

wadepickett left a comment

		# [Visual Studio](#tab/visual-studio) -->

		This tutorial uses [Endpoints Explorer and .http files](xref:test/http-files#use-endpoints-explorer) to test the API.



	For an alternative testing approach, select the Visual Studio Code tab and use the CLI to perform the steps.

update WebApi to .NET 9 (without Swagger) #34746

update WebApi to .NET 9 (without Swagger) #34746

Conversation

timdeschryver commented Feb 17, 2025 • edited by github-actions bot Loading

Internal previews

wadepickett commented Feb 18, 2025 • edited Loading

Rick-Anderson commented Feb 18, 2025

wadepickett commented Feb 19, 2025

timdeschryver commented Feb 19, 2025

timdeschryver commented Feb 19, 2025

wadepickett Feb 19, 2025 • edited Loading

Choose a reason for hiding this comment

timdeschryver Feb 20, 2025

Choose a reason for hiding this comment

Rick-Anderson commented Feb 19, 2025

wadepickett commented Feb 20, 2025 • edited Loading

Rick-Anderson Feb 20, 2025

Choose a reason for hiding this comment

wadepickett Feb 20, 2025

Choose a reason for hiding this comment

wadepickett left a comment • edited Loading

Choose a reason for hiding this comment

Rick-Anderson commented Feb 20, 2025

Public review of the doc build:

Rick-Anderson left a comment

Choose a reason for hiding this comment

Rick-Anderson left a comment

Choose a reason for hiding this comment

Rick-Anderson Feb 20, 2025 • edited Loading

Choose a reason for hiding this comment

wadepickett Feb 20, 2025 • edited Loading

Choose a reason for hiding this comment

Rick-Anderson Feb 20, 2025

Choose a reason for hiding this comment

wadepickett Feb 20, 2025

Choose a reason for hiding this comment

timdeschryver Feb 20, 2025 • edited Loading

Choose a reason for hiding this comment

wadepickett left a comment

Choose a reason for hiding this comment

timdeschryver commented Feb 17, 2025 •

edited by github-actions bot

Loading

wadepickett commented Feb 18, 2025 •

edited

Loading

wadepickett Feb 19, 2025 •

edited

Loading

wadepickett commented Feb 20, 2025 •

edited

Loading

wadepickett left a comment •

edited

Loading

Rick-Anderson Feb 20, 2025 •

edited

Loading

wadepickett Feb 20, 2025 •

edited

Loading

timdeschryver Feb 20, 2025 •

edited

Loading