diff --git a/README.md b/README.md index 2309128..c2f6184 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ The following settings configure the data stores and authentication for developm } ``` -- *UseDevSettings* — Indicates whether the Dev settings should be applied. +- *UseDevSettings* — Indicates whether the following Dev settings should be applied. - *UseInMemoryData* - When `true`, the "LocalRepository" project is used for repositories and data stores. Data is initially seeded from the "TestData" project. - When `false`, the "EfRepository" project is used, and a SQL Server database (as specified by the connection string) is created. (If the connection string is missing, then a temporary EF Core in-memory database provider is used. This option is included for convenience and is not recommended.) @@ -86,6 +86,8 @@ The following settings configure the data stores and authentication for developm - *LocalUserIsAdmin* — Adds all App Roles to the logged in account when `true` or no roles when `false`. (Applies whether *UserAzureAd* is `true` or `false`.) An alternative way to create admin users is to add them to the `SeedAdminUsers` setting as an array of email addresses. - *UseSecurityHeadersLocally* — Sets whether to include HTTP security headers when running locally in the Development environment. +#### Production defaults + When `UseDevSettings` is missing or set to `false` or if the `DevSettings` section is missing, the settings are automatically set to production defaults as follows: ```csharp @@ -155,15 +157,3 @@ flowchart LR B --> D end ``` - -### Entity Framework database migrations - -Instructions for adding a new Entity Framework database migration: - -1. Build the solution. - -2. Open a command prompt to the "./src/EfRepository/" folder. - -3. Run the following command with an appropriate migration name: - - `dotnet ef migrations add NAME_OF_MIGRATION` diff --git a/TEMPLATE-HOW-TO.md b/TEMPLATE-HOW-TO.md index dd4215e..82f4cc3 100644 --- a/TEMPLATE-HOW-TO.md +++ b/TEMPLATE-HOW-TO.md @@ -4,41 +4,45 @@ The following steps describe how to use the template for a new application. ## Initialize the template files -* Run the "create-sln.ps1" file to create a new solution file. -* Rename or search and replace the following terms. *(Caution: not all of these will be visible in the Visual Studio solution view.)* - - "MY_APP_NAME" - Replace with the readable display name of the app. - - "MY_APP" - Replace with the short name or acronym of the app. - - `MyApp`: - - Rename the root namespace for the app. - - Update the `` element in each "csproj" file. - - Update the namespace in the "_ViewImports.cshtml" file. - - Update the exclusions in the coverlet commands in the "sonarcloud-scan.yml" file. - - Update the exclusions in the "finecodecoverage-settings.xml" file. - - "template-app" - Search and replace with the repository name. This will affect the following: - - The LocalDB database name in various connection strings. - - The project key in the "sonarcloud-scan.yml" workflow file. - - The comment URL path in the "lighthouse-analysis.yml" workflow file. - - The URLs in the GitHub and SonarCloud badges in the "README.md" file. - - The URL on the support page. +* [ ] Run the "create-sln.ps1" file to create a new solution file. +* [ ] Rename or search and replace the following terms. *(Caution: not all of these will be visible in the Visual Studio solution view.)* + - [ ] "MY_APP_NAME" - Replace with the readable display name of the app. + - [ ] "MY_APP" - Replace with the short name or acronym of the app. + - [ ] `MyApp`: + - [ ] Rename the root namespace for the app. + - [ ] Update the `` element in each "csproj" file. + - [ ] Update the namespace in the "_ViewImports.cshtml" file. + - [ ] Update the exclusions in the coverlet commands in the "sonarcloud-scan.yml" file. + - [ ] Update the exclusions in the "finecodecoverage-settings.xml" file. + - [ ] "template-app" - Search and replace with the repository name. This will affect the following: + - [ ] The LocalDB database name in various connection strings. + - [ ] The project key in the "sonarcloud-scan.yml" workflow file. + - [ ] The URLs in the GitHub and SonarCloud badges in the "README.md" file. + - [ ] The URL on the support page. +* [ ] Change the port numbers in the "launchSettings.json" file to be unique. ## Customize the application -* Update these files with information about the new application: - * README.md - * docs/Entity relationship diagram.md - * docs/Role capabilities.md - * docs/Site map.md -* Change the branding colors in "src\WebApp\wwwroot\css\site.css" by adjusting the `--base-hue` variable. +* [ ] Update these files with information about the new application: + * [ ] README.md + * [ ] docs/Entity relationship diagram.md + * [ ] docs/Role capabilities.md + * [ ] docs/Site map.md +* [ ] Change the branding colors in "src\WebApp\wwwroot\css\site.css" by adjusting the `--base-hue` variable. + +## Configure external services + +* [ ] Configure the following external services as needed: + - [ ] [SonarCloud](https://sonarcloud.io/projects) for code quality and security scanning. *(Update the project key in the "sonarcloud-scan.yml" workflow file and in the README file badges.)* ## Prepare for deployment Complete the following tasks when the application is ready for deployment. -* Create server-specific settings and config files and add copies to the "app-config" repository. -* Create Web Deploy Publish Profiles for each web server using the "Example-Server.pubxml" file as an example. -* Configure the following external services as needed: - - [Azure App registration](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) to manage employee authentication. *(Add configuration settings in the "AzureAd" section in a server settings file.)* +* [ ] Create server-specific settings and config files and add copies to the "app-config" repository. +* [ ] Create Web Deploy Publish Profiles for each web server using the "Example-Server.pubxml" file as an example. +* [ ] Configure the following external services as needed: + - [ ] [Azure App registration](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) to manage employee authentication. *(Add configuration settings in the "AzureAd" section in a server settings file.)* When configuring the app in the Azure Portal, add optional claims for "email", "family_name", and "given_name" under "Token configuration". - - [Raygun](https://app.raygun.com/) for crash reporting and performance monitoring. *(Add the API key to the "RaygunSettings" section in a server settings file.)* - - [SonarCloud](https://sonarcloud.io/projects) for code quality and security scanning. *(Update the project key in the "sonarcloud-scan.yml" workflow file and in the badges above.)* - - [Better Uptime](https://betterstack.com/better-uptime) for site uptime monitoring. *(No app configuration needed.)* + - [ ] [Raygun](https://app.raygun.com/) for crash reporting and performance monitoring. *(Add the API key to the "RaygunSettings" section in a server settings file.)* + - [ ] [Better Uptime](https://betterstack.com/better-uptime) for site uptime monitoring. *(No app configuration needed.)* diff --git a/docs/Menu bar.md b/docs/Navigation menu.md similarity index 96% rename from docs/Menu bar.md rename to docs/Navigation menu.md index 5a79f6a..0c922fe 100644 --- a/docs/Menu bar.md +++ b/docs/Navigation menu.md @@ -1,4 +1,4 @@ -# Menu Bar +# Navigation Menu ## Public diff --git a/docs/Site map.md b/docs/Site map.md index bb1b738..459437d 100644 --- a/docs/Site map.md +++ b/docs/Site map.md @@ -2,7 +2,7 @@ *Update this document with a site map for the site.* -* `/` Home page with welcome portal and [menu bar](Menu%20bar.md) allowing access to staff pages. +* `/` Home page with welcome portal and [menu bar](Navigation%20menu.md) allowing access to staff pages. * `/Support` (Help/support page) ## Public Pages @@ -15,37 +15,38 @@ These pages are available to the public. These pages are only available to logged-in staff. -* `/Staff` (Staff dashboard) +* `/Staff` Staff dashboard. * *Continue the list of protected application pages.* ## User Account -* `/Account` (View profile) -* `/Account/Login` (Work account login form) -* `/Account/Edit` (Edit contact info) +* `/Account` View profile. +* `/Account/Login` Work account login form. +* `/Account/Edit` Edit contact info. +* `/Account/Settings` Potential location for a personal settings page (not implemented). ## Admin pages ### Reports -(Pages must be named "Reporting" because "Reports" is reserved by the ArcGIS application.) +Pages must be named "Reporting" because "Reports" is reserved by the ArcGIS application. -* `/Admin/Reporting` (Management & error reports) -* `/Admin/Reporting/[report type]` (View report) +* `/Admin/Reporting` Management & error reports. +* `/Admin/Reporting/[report type]` View report. ### Site Maintenance Maintenance pages available to Site Admin personnel to modify lookup tables used for drop-down lists. -* `/Admin/Maintenance` (List of item types) -* `/Admin/Maintenance/[type]` (List of items of given type) -* `/Admin/Maintenance/[type]/Add` (Add new item) -* `/Admin/Maintenance/[type]/Edit/{id}` (Edit item) +* `/Admin/Maintenance` List of maintenance item types. +* `/Admin/Maintenance/[type]` List of items of given type. +* `/Admin/Maintenance/[type]/Add` Add new item. +* `/Admin/Maintenance/[type]/Edit/{id}` Edit item. ### User Management -* `/Admin/Users` (User search) -* `/Admin/Users/Details/{id}` (View user profile) -* `/Admin/Users/Edit/{id}` (Edit contact info) -* `/Admin/Users/EditRoles/{id}` (Edit roles) +* `/Admin/Users` User search. +* `/Admin/Users/Details/{id}` View user profile. +* `/Admin/Users/Edit/{id}` Edit contact info. +* `/Admin/Users/EditRoles/{id}` Edit roles. diff --git a/src/EfRepository/EF-README.md b/src/EfRepository/EF-README.md new file mode 100644 index 0000000..675e387 --- /dev/null +++ b/src/EfRepository/EF-README.md @@ -0,0 +1,11 @@ +### Entity Framework database migrations + +Instructions for adding a new Entity Framework database migration: + +1. Build the solution. + +2. Open a command prompt to the "./src/EfRepository/" folder. + +3. Run the following command with an appropriate migration name: + + `dotnet ef migrations add NAME_OF_MIGRATION --msbuildprojectextensionspath ..\..\.artifacts\EfRepository\obj\` diff --git a/src/WebApp/Program.cs b/src/WebApp/Program.cs index 79dbd64..f116b8f 100644 --- a/src/WebApp/Program.cs +++ b/src/WebApp/Program.cs @@ -78,15 +78,18 @@ // Add API documentation. builder.Services.AddMvcCore().AddApiExplorer(); + +const string apiVersion = "v1"; +const string apiTitle = "MY_APP_NAME API"; builder.Services.AddSwaggerGen(options => { - options.SwaggerDoc("v1", new OpenApiInfo + options.SwaggerDoc(apiVersion, new OpenApiInfo { - Version = "v1", - Title = "MY_APP API", + Version = apiVersion, + Title = apiTitle, Contact = new OpenApiContact { - Name = "MY_APP Support", + Name = $"{apiTitle} Support", Email = builder.Configuration["SupportEmail"], }, }); @@ -127,9 +130,9 @@ app.UseSwagger(options => { options.RouteTemplate = "api-docs/{documentName}/openapi.json"; }) .UseSwaggerUI(options => { - options.SwaggerEndpoint("v1/openapi.json", "MY_APP API v1"); + options.SwaggerEndpoint($"{apiVersion}/openapi.json", $"{apiTitle} {apiVersion}"); options.RoutePrefix = "api-docs"; - options.DocumentTitle = "MY_APP_NAME API"; + options.DocumentTitle = apiTitle; }); // Map endpoints. @@ -137,4 +140,4 @@ app.MapControllers(); // Make it so. -app.Run(); +await app.RunAsync();