Skip to content

Development Guide

Jump to bottom Edit New page
Tyler Morrow edited this page Sep 24, 2023 · 24 revisions

Contents

Key Technologies

  • EF Core for database design and migration
    • Defines the database schema and provides C# classes allowing other projects to perform queries and transactions
    • Applies to: Dsp.Data
  • ASP.NET Core for server-side development
    • Defines the project architecture (e.g., areas, views, controllers, etc.) and associated routing logic (i.e., what happens when a URL is accessed)
    • Applies to: Dsp.WebCore
  • Libman for client-side development
    • Used to add JavaScript dependencies for use in the front-end
    • Applies to: Dsp.WebCore
  • Razor Pages for client-side development
    • Used for server-side rendering of web pages delivered to the front-end
    • Applies to: Dsp.WebCore
  • ASP.NET Identity for authentication and authorization
    • Add-on that provides utilities (from database to web app) to handle things like signing in, registering, password reset, determining user roles, and more.
    • Applies to: everything
  • Service Layer for server-side development
    • Used to separate business logic from the web application logic
    • Applies to: Dsp.Services
  • API
    • URL endpoints for programmatically accessing data. Not majorly used but likely to be expanded in the future to support non-human access.
    • Applies to: Dsp.WebCore
  • Git
    • Git is the version control system used to track changes, and GitHub where the Git repository containing all code is hosted.
    • Applies to: everything

This guide assumes you will use the resources above to fill in knowledge gaps; that is why they are provided. Note that as time marches on, the versions in use by this project may get out of sync with the versions associated with the links above. Let Ty know if any links are broken.

Requirements

You will need the following before getting started with coding:

  • Visual Studio 2022
    • In the Visual Studio Installer, you should really only need "ASP.NET and web development" (at the time of writing, this includes IIS Express and SQL Server LocalDB). image
  • Git (it would be wise to set up an SSH key)
  • Create a GitHub account and request access to the GitHub group
    • This will let you clone and push branches to this this repo rather than from a fork, but either works - your preference.

Initial Setup

  1. Clone the repository
  2. Open the solution (Sphinx.sln) in Visual Studio
  3. Open the Developer PowerShell (View -> Terminal) and navigate into the src directory
  4. Run the following command 
    dotnet tool install --global dotnet-ef
  5. Run the update database command to create an empty, local database
    • If you have a database backup, you can restore it first before running this command
  6. Right-click Dsp.WebCore and select "Set as Startup Project"
  7. Hit the play button at the top to launch the site in debug mode

Workflow

Changes to the web app involve the following:

  • Add new feature
    • Make a new branch named feature/your-new-feature
    • Add migrations to database change(s)
    • Add new business logic to Dsp.Services
    • Add controllers and views to Dsp.WebCore
    • Test and iterate on changes yourself (involve other members; get their feedback)
    • Commit changes and push branch to GitHub
    • Open pull request and assign Ty
  • Modify existing feature
    • Make a new branch named enhancement/your-change
    • Add necessary changes where appropriate
    • Test and iterate on changes yourself (involve other members; get their feedback)
    • Commit changes and push branch to GitHub
    • Open pull request and assign Ty
  • Fix bug
    • Make a new branch named bug/the-problem
    • Add necessary changes where appropriate
    • Test and iterate on changes yourself (involve other members; get their feedback)
    • Commit changes and push branch to GitHub
    • Open pull request and assign Ty

Most bugs are display issues and limited to tweaking Views in Dsp.WebCore However, sometimes the issue is related to controller (Dsp.WebCore) or business (Dsp.Services) logic. Rarely is a bug related to the database.

Pull Requests

Contributions to this repository will require development on separate branches and a pull request to merge back in. This allows a review of changes to ensure the following is true:

  • Web app successfully builds and runs
  • Changes adhere to existing patterns, conventions, code style, and UI style
  • Database migrations avoid accidental data loss and follow basic relationship database principles (around 3NF is about where you should be)
  • No extraneous changes outside the scope of the pull request (i.e., changing other parts of the app should be in separate pull requests)
  • Your branch has been rebased with any changes to master that were added since you started your work (this can be a non-trivial task, but Ty may take care of this as part of the review process)

Work-in-progress (WIP) pull requests are totally fine, but be sure to check the above bullets yourself before marking a pull request ready for review.

Database Changes

Database changes are broadly made with the following steps:

  1. Modify the entities as you need to (Dsp.Data.Entities)
  2. Modify DspDbContext.OnModelCreating() accordingly
  3. Run the add migration command
  4. Run the update database command

This process only affects your local development environment. Updates to the production database are made separately when publishing to the actual web server- you will likely not need to concern yourself with this.

Note that the following commands are for PowerShell, and Visual Studio should have a built-in Developer PowerShell (Views -> Terminal).

Add migration command

dotnet ef migrations add --startup-project Dsp.WebCore --project Dsp.Data --context DspDbContext CamelCasedNameForYourMigration

Remove last migration command

Review your newly added migration to ensure it looks correct; if you're not sure, you should ask. If you know it isn't right, you should get remove it.

dotnet ef migrations remove --startup-project Dsp.WebCore --project Dsp.Data --context DspDbContext

Update database

Updating your local database actually changes your local database schema to be in line with what Dsp.Data expects. It does this by running the SQL associated with the content of the Up() method of your migration.

dotnet ef database update --startup-project Dsp.WebCore --project Dsp.Data --context DspDbContext

If you try to update the database and it fails, there is either something wrong about your change OR there is an esoteric issue (likely related to scaffolding) and you should ask Ty for help - this is not a trivial thing to debug. In either case, you will probably want to remove the migration (previous section).

Service Layer Changes

Adding business logic typically involves the following steps:

  1. Add interface
  2. Add implementation of interface

These changes typically go fast but you may find you want to iterate here to optimize how the methods will be used in the web app. 95% of the time, the method you're adding falls into one of four categories: creating, reading, updating, deleting (CRUD). The existing services are the best guide - please follow how they do things.

Web App Changes

Web changes are more time consuming as you have to deal with the models, views, and controllers (this is the MVC design pattern). To start, you will want to make sure you can inject any new service you added into your new controller by updating Program.cs. From there, you will do the following:

  1. Add a new area, controller(s), controller action(s), and/or models as appropriate
  • It is probably best to discuss things in an issue before-hand to figure out where things will go
  • Again, most of what you will likely being doing deals with CRUD and this pattern is pervasive throughout the existing web app code.
  1. Build and debug to test your changes

If you're adding a new JavaScript or CSS dependency, this is done through LibMan. With respect to custom CSS styling, stick to what Bootstrap has built-in rather than custom stuff, but there are exceptions (i.e., the house diagram).

Hosting

The website and database are currently hosted through AWS but this may be changing in the future.

TODO: documentation on how to do this from scratch, however we may be changing hosts soon.

Deployment

Deployment requires access to the hosting server. With that, the current workflow is to right-click on the web project and select Publish (having filled in the necessary information).

Long-term, I want to set up a GitHub Action to automatically publish.

Add a custom footer

Development Guide

FAQ

Active Members

Clone this wiki locally