Template documentation updates (#115)

* Update Readme

* Update template insturctions

* Simplify API docs setup

* Update site map

* Run app asynchronously

* Rename local constants

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. <small>(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.)</small>
@@ -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`.)     <small>An alternative way to create admin users is to add them to the `SeedAdminUsers` setting as an array of email addresses.</small>
 - *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`

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 `<RootNamespace>` 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 `<RootNamespace>` 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.)*

docs/Menu bar.md → docs/Navigation menu.md

@@ -1,4 +1,4 @@
-# Menu Bar
+# Navigation Menu
 
 ## Public
 

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.

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\`

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,14 +130,14 @@
 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.
 app.MapRazorPages();
 app.MapControllers();
 
 // Make it so.
-app.Run();
+await app.RunAsync();