This template should help get you started developing a Web API using .NET Core 6. It includes opinionated configurations for JetBrains Rider, Visual Studio, commitlint with commit hooks (powered by Husky.Net).
This project was generated using Rider's .NET Core Web API template using version 2022.1.1.
JetBrains Rider or Microsoft Visual Studio 2022
You should start by replacing almost all the references to the WAW.API project. This is a non-exhaustive list of possible changes you'll have to make (use your IDEs refactor option so that it helps you):
- C# namespaces in projects
- Root namespaces in
.csprojfiles (see theRootNamespaceproperty in it) - Project filenames:
WAW.API.csprojandWAW.API.Tests.csproj - After renaming projects:
InternalsVisibleToandProjectReferenceproperties in.csprojfiles - Migration files (they include the
WAW.API.Migrationsnamespace) WAW.APIandWAW.API.Testsfolders should be renamed to your new root namespace- Project references and folder names in
WAW.API.sln - GitHub Actions workflow files
dotnet.yml: change thePROJECT_NAMEenvironment variablereports.yml: change thePROJECT_NAMEenvironment variable (its in two different places)
- In case you plan on using/supporting JetBrains Rider: rename the folder inside the
.ideafolder that has the project name- Use your IDE search in files option inside this folder
applicationhost.config: if you have this file, it is auto-generated. Don't edit it manually
- Update the README file
The workflow files for GitHub Actions are setup to use Cloudflare Pages for deploying the LivingDoc generated by SpecFlow. Deployments using the new Direct Upload feature with Wrangler and the new Action.
Some of the changes you should make:
dotnet.yml- Change the
PROJECT_NAMEandCLOUDFLARE_PROJECT_NAMEenvironment variable - If you setup any other long-lived branches, add them to the push branches list
- Change the
reports.yml- Change the
PROJECT_NAMEenvironment variable (its in 2 different places) - Change the
CLOUDFLARE_PROJECT_NAMEenvironment variable (its in 3 different places)
- Change the
- If you're not going to be using Cloudflare Pages: remove all the references to it
Secrets you should set on your repository:
CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account IDCLOUDFLARE_API_TOKEN: API Token with "Cloudflare Pages - Edit" permission
You can find documentation about the Direct Upload with GitHub Actions feature in the docs.
This repository also uses a custom machine account, dalbitresb12-bot, to post comments on PRs and a couple of other things.
If you want to continue using the custom machine account, register a new account and then create a Personal Access Token.
If you don't want to create a new account, replace any references to the variable BOT_PAT with the GITHUB_TOKEN and replace the comment-author option of the "Find previous comment on pull request" step in reports.yml with github-actions[bot].
Secrets you should set on your repository:
BOT_PAT: Create a Personal Access Token with the scopepublic_repo(orrepoif your repository is private)
- Any files that are Git ignored should not be modified manually. Regenerate them as needed.
- You should probably also change the data in the LICENSE file.
You should also have Node.js and NPM installed for commitlint to work (any supported LTS version should be fine).
If you don't have Node.js installed, it is highly encouraged that you install it using a version manager:
- Linux/MacOS: use nvm
- Windows: use nvm-windows
After that, open the project on your preferred IDE from the list above.
Your IDE should automatically restore all the tools needed (Husky.Net, dotnet-ef and npm dependencies) during project restore. If this doesn't happen run dotnet restore in the terminal.
JetBrains Rider might prompt you to install EF Core tools automatically with a pop-up when you open the project. You can safely ignore this prompt, as the tool is already included in the projects manifest and should be installed during project restore. To verify, run the following command:
# The output should be the one below the command
$ dotnet ef
_/\__
---==/ \\
___ ___ |. \|\
| __|| __| | ) \\\
| _| | _| \_/ | //|\\
|___||_| / \\\/\\
Entity Framework Core .NET Command-line Tools 6.0.5
<Usage documentation follows, not shown.>This project is configured to use MySQL as the database, using Pomelo's MySQL connector. The connection string will be read from the Secret Manager tool. You can read more about it here.
To allow the app to connect to the database, set the connection string as a secret using the .NET CLI:
# Don't forget to replace {YOUR_CONNECTION_STRING} with the appropriate value
$ dotnet user-secrets set "DbConnectionString" "{YOUR_CONNECTION_STRING}" --project WAW.API
Successfully saved DbConnectionString = {YOUR_CONNECTION_STRING} to the secret store.
# Alternatively, move to project directory to avoid having to use `--project`
$ cd WAW.API/
$ dotnet user-secrets set "DbConnectionString" "{YOUR_CONNECTION_STRING}"
Successfully saved DbConnectionString = {YOUR_CONNECTION_STRING} to the secret store.
# Check that your value has been saved correctly
$ dotnet user-secrets list
DbConnectionString = {YOUR_CONNECTION_STRING}This app is configured to use database migrations. You can read more about them here.
If this is the first time you're running the app, you probably won't have the database created. You can have EF create your database and create your schema from the migration files. This can be done via the following:
dotnet ef database updateIf you make any changes to the database models, don't forget to update the migration scripts and re-sync your local database schema with the new schema:
# Don't forget to replace {YOUR_CHANGE_NAME} with a description of the changes you did to the model
# Note that we give migrations a descriptive name, to make it easier to understand the project history later
# You can use this like if it was a commit for your version control system
$ dotnet ef migrations add {YOUR_CHANGE_NAME}
# Check the migration files before applying any migrations, as they could cause data loss
# You can now apply your migration as before
$ dotnet ef database updateWhenever you create a new migration, EF Core will create the files needed to describe the migration. This files must be added to version control.
If you named your migration SomeChanges, three files will be added to your project under the Migrations directory:
XXXXXXXXXXXXXX_SomeChanges.cs-- The main migrations file. Contains the operations necessary to apply the migration (in Up) and to revert it (in Down).XXXXXXXXXXXXXX_SomeChanges.Designer.cs-- The migrations metadata file. Contains information used by EF.AppDbContextModelSnapshot.cs-- A snapshot of your current model. Used to determine what changed when adding the next migration.
The timestamp in the filename helps keep them ordered chronologically so you can see the progression of changes.
It's super important that you always check the migration file (XXXXXXXXXXXXXX_SomeChanges.cs), since EF Core might drop columns that were just renamed and you'll lose all the data in them if you apply the migration. For more information on how to customize the migration code generated by EF Core, read here.
For more advanced usage of migrations, check the documentation here.
Start a development server by running the ISS Express configuration from your IDE. Don't forget to trust the generated SSL certificate.
If you want to customize the SSL certificate used for IIS, check the following Stack Overflow answer.
Run dotnet build to build the project. The build artifacts will be stored in the bin/ directory.