如何設定一部即裝即用的 .NET 開發機

Note: this article was drafted with AI assistance and reviewed by Softinbit Technology before publishing. It is part of the series Zero to Full-Stack .NET.

Install the SDK, a database, Git, and Node once, pin them per repository, and stop losing your first week to "it works on my machine".

Part 1 of the "Zero to Full-Stack .NET" series. Section: Getting Started.

TL;DR

• Install the .NET 10 SDK and pin each repository's SDK with global.json, so a teammate's preview install never changes your build.
• Run a throwaway SQL Server in Docker or LocalDB, and trust the local HTTPS certificate once with dotnet dev-certs https --trust.
• Finish with a console app, a Web API, .http smoke tests, and a dotnet CLI cheat sheet you will use every day.

Level: Beginner · Prerequisites: A Windows, macOS, or Linux machine where you can install software · Reading time: 10 min

It is your first Monday. You clone the project, open it, and press Build. The output says the project targets a .NET version you do not have. You install something, try again, and now the app starts but crashes because it cannot reach SQL Server. You fix that, open the browser, and get a red "Your connection is not private" warning on localhost.

None of this is a real bug. It is a machine that was never set up. The team has been working on their laptops for years and nobody remembers which tools they installed, so the onboarding document is three lines long and two of them are wrong.

This article is the setup I wish someone had handed me. It goes in the order you will hit the problems, and every step ends with a command you can run to prove it worked.

What you will be able to do after this

• Install the current .NET SDK and pin the version a repository uses with global.json
• Run SQL Server locally in Docker or as LocalDB and connect to it from a query tool
• Trust the local HTTPS certificate so https://localhost stops warning
• Create, run, and test a console app and a Web API from the command line
• Use a dotnet CLI cheat sheet instead of clicking through menus

Installing the SDK and pinning it per repository

Download the SDK (not just the runtime) for the current LTS release from the .NET download page on dot.net. LTS means long-term support: it is the version most teams target because it receives fixes for three years. .NET 8 and .NET 10 are both LTS releases; pick the one your team uses, or .NET 10 if you are starting fresh (.NET 8 support ends in November 2026).

Check what you have:

dotnet --list-sdks
# 8.0.xxx [C:\Program Files\dotnet\sdk]
# 10.0.xxx [C:\Program Files\dotnet\sdk]
dotnet --version
# prints the SDK that will be used in the current folder

Having several SDKs installed is normal. The surprise is which one dotnet build picks: without any configuration, it uses the newest one on the machine. That is fine until a teammate installs a preview and a build starts behaving differently. The fix is a global.json at the root of the repository:

{
  "sdk": {
    "version": "8.0.100",
    "rollForward": "latestFeature"
  }
}

rollForward: latestFeature means "use 8.0.100 or any newer 8.0.x feature band, but never jump to 9 or 10". You can generate the file instead of typing it:

dotnet new globaljson --sdk-version 8.0.100 --roll-forward latestFeature

Run dotnet --version inside the repo afterwards. If it prints an error saying the requested SDK was not found, you now know exactly what to install.

Choosing an editor

Both are fine. Many teams use Visual Studio for the API and VS Code for the frontend folder of the same repository. When you install Visual Studio, select the "ASP.NET and web development" workload and, if you will touch desktop tools, ".NET desktop development".

SQL Server for development

You need a SQL Server you can break without consequences. There are two good options.

Docker works on every OS and is the easiest to reset. Install Docker Desktop (on Windows, with the WSL 2 backend), then:

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=Dev_Passw0rd" -p 1433:1433 --name sqldev -d mcr.microsoft.com/mssql/server:2022-latest
# check it stayed up
docker ps
# if it is missing, read why
docker logs sqldev

The password for the sa (system administrator) account must meet SQL Server's complexity rules: at least eight characters, using three of the four groups uppercase, lowercase, digits, and symbols. If it does not, the container exits within seconds and docker ps shows nothing. docker logs tells you.

On Windows without Docker, install SQL Server Express, or use LocalDB, which comes with SQL Server Express and as an optional Visual Studio component. LocalDB is a tiny on-demand instance that starts when you connect:

sqllocaldb info
# MSSQLLocalDB
sqllocaldb start MSSQLLocalDB

Connection strings for the two setups:

Docker:  Server=localhost,1433;Database=Store;User Id=sa;Password=Dev_Passw0rd;TrustServerCertificate=True
LocalDB: Server=(localdb)\MSSQLLocalDB;Database=Store;Trusted_Connection=True

TrustServerCertificate=True is needed for the container because recent SqlClient versions encrypt by default and the container's certificate is self-signed.

To look at tables and run queries, install SQL Server Management Studio (SSMS, Windows only) or, on any OS, VS Code with the MSSQL extension. Azure Data Studio was the older cross-platform option; Microsoft has retired it, so prefer the VS Code extension for new installs. Connect with the values above and run SELECT @@VERSION to confirm.

Git and a GitHub account

Install Git from git-scm.com (on Windows, keep the default "Git from the command line" option). Then tell Git who you are, because every commit is stamped with it:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git --version

Create a GitHub account if you do not have one and set up authentication. The simplest path is the GitHub CLI: gh auth login walks you through a browser login and configures Git to use it. Your team may use Azure DevOps or GitLab instead; the Git commands are identical.

Node.js for the frontend you will write later

Angular, and most frontend tooling, run on Node.js. Do not install Node from the plain installer; use a version manager so you can switch when a project needs a different version. On Windows that is nvm-windows (the nvm-windows project by coreybutler on GitHub):

nvm install lts
nvm use lts
node --version
npm --version

On macOS or Linux use nvm from the nvm-sh project; there the commands are nvm install --lts and nvm use --lts. You do not need Angular today. When you do, npm install -g @angular/cli is one line.

Trusting the HTTPS development certificate

When you run a Web API, Kestrel (the built-in web server) serves https://localhost:xxxx with a self-signed certificate. Browsers reject it until you tell the operating system to trust it:

dotnet dev-certs https --trust

Windows and macOS show a confirmation dialog. On Linux, trust stores differ by distribution and browser, so depending on your SDK version the command may only print instructions; follow them. If something is broken, dotnet dev-certs https --clean followed by the trust command again fixes almost every case.

Your first console app

dotnet new console -n Store.Tools
cd Store.Tools
dotnet run

Open Program.cs. The template uses top-level statements: there is no class Program or Main, just code. Replace the contents with:

var customers = new[] { "Ayşe", "Mehmet", "Zeynep" };

foreach (var name in customers)
{
    Console.WriteLine($"Merhaba, {name}");
}

dotnet run prints three greetings. If it does, the SDK, the compiler, and your terminal all work.

Your first Web API

dotnet new webapi -n Store.Api
cd Store.Api
dotnet run --launch-profile https

In .NET 8 and later this template creates a minimal API: endpoints are defined directly in Program.cs with app.MapGet(...). If your team uses controllers, add --use-controllers to the new command. .NET 9 replaced the Swagger UI package with built-in OpenAPI document generation, so do not be surprised when a newer template has no /swagger page.

Plain dotnet run uses the first profile in Properties/launchSettings.json, which in the template is http, so you would only get http://localhost:5xxx. With --launch-profile https the console prints both URLs, typically https://localhost:7xxx and http://localhost:5xxx. Add a small endpoint below the existing ones (above app.Run()):

app.MapGet("/products", () => new[]
{
    new { Id = 1, Name = "Klavye", Price = 1299.90m },
    new { Id = 2, Name = "Mouse", Price = 449.50m }
});

Then test it without a browser.

Testing HTTP requests from your editor

Visual Studio and VS Code (with the REST Client extension) both understand .http files, and the .NET 8 template already creates Store.Api.http next to the project. Replace its contents with this, using the HTTPS port dotnet run --launch-profile https printed:

@baseUrl = https://localhost:7001

GET {{baseUrl}}/products
Accept: application/json

###

GET {{baseUrl}}/weatherforecast

Click "Send Request" above a request and the response opens beside it. The file is plain text, so it goes into Git and the whole team shares the same smoke tests. Postman does the same job with a richer UI if you prefer it; export the collection into the repository so it is not trapped in one person's account.

The dotnet CLI cheat sheet

dotnet new list                                  # see available templates
dotnet new sln -n Store                          # create a solution
dotnet sln add Store.Api/Store.Api.csproj        # add a project to it
dotnet restore                                   # download NuGet packages
dotnet build                                     # compile
dotnet run --project Store.Api                   # run a project from the solution folder
dotnet watch --project Store.Api                 # rebuild and restart on every save
dotnet test                                      # run all tests in the solution
dotnet add Store.Api package Serilog.AspNetCore  # add a NuGet package to a project
dotnet tool install -g dotnet-ef                 # install a global tool
dotnet format                                    # apply code style from .editorconfig

Commands run against the project in the current folder unless you pass --project. Keeping a terminal open next to the editor is faster than the menus once you know these.

The tools and what each one is for

Common mistakes

• Several SDKs and no global.json. The build silently picks the newest SDK and behaves differently on each machine. Add global.json and commit it.
• Cloning into a OneDrive, Dropbox, or Google Drive folder. The sync client locks files in bin and obj mid-build and you get random "file in use" errors. Clone to C:\src or ~/src.
• Running Visual Studio as administrator out of habit. Files and certificates created under admin become unreadable from a normal terminal. Run it as your own user; nothing in a normal web project needs elevation.
• Committing bin and obj. They are build output, change on every build, and cause merge conflicts. Run dotnet new gitignore in the repository root before the first commit.
• Skipping dotnet dev-certs https --trust. Every browser warning and every HttpClient call to your own API fails with a certificate error. One command fixes it.
• Port 1433 already taken. A previously installed SQL Server Express is listening, so the Docker container cannot bind. Either stop the Windows service or map the container to another port with -p 14333:1433 and use localhost,14333 in the connection string.
• An sa password that fails the complexity rules. The container starts, fails validation, and exits. docker logs sqldev shows the message; pick a longer password with mixed character types.

Checklist

• dotnet --list-sdks shows the SDK the team targets
• global.json exists in the repository root and dotnet --version matches it
• SQL Server answers SELECT @@VERSION from SSMS or VS Code
• dotnet dev-certs https --trust ran without errors
• git config --global user.name and user.email are set
• node --version prints an LTS version installed through nvm
• dotnet run --launch-profile https in a fresh webapi project serves /weatherforecast over HTTPS
• .gitignore from dotnet new gitignore is committed before bin and obj ever are

What's next

With a machine that builds and a database that answers, the next article, "Thinking Like a Programmer: Turning a Vague Request Into Working Code", takes a one-sentence request from a product owner and turns it into a small, tested C# program. After that, "Git for Daily Work: Branches, Pull Requests, and Fixing Mistakes" covers the version control habits that keep a team from overwriting each other.

Originally published at www.softinbit.com. Part of Zero to Full-Stack .NET.