Skip to content

Commit c8e19ca

Browse files
markhazletonmarkhazleton
committed
Update README.md to enhance project description, add theme switcher details, and improve deployment instructions
1 parent c61f49d commit c8e19ca

File tree

1 file changed

+142
-29
lines changed

1 file changed

+142
-29
lines changed

‎README.md‎

Lines changed: 142 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,160 @@
11
# SampleMvcCRUD
2-
An Asp.Net MVC Application to demonstrate multiple ways of implementing a simple maintenance (CRUD) user interface
32

4-
[![.NET](https://github.com/markhazleton/samplemvccrud/actions/workflows/main_mwhsampleweb.yml/badge.svg)]([main_mwhsampleweb.yml](https://github.com/markhazleton/SampleMvcCRUD/blob/main/.github/workflows/main_mwhsampleweb.yml))
3+
An ASP.NET Core MVC application demonstrating multiple approaches to implementing a modern, maintainable CRUD (Create, Read, Update, Delete) user interface. This repository is designed as a reference and educational resource for developers interested in best practices for web application architecture, theming, API design, and deployment.
54

6-
[![.NET](https://github.com/markhazleton/samplemvccrud/actions/workflows/docker-image.yml/badge.svg)]([docker-image.yml](https://github.com/markhazleton/SampleMvcCRUD/blob/main/.github/workflows/docker-image.yml))
5+
[![.NET](https://github.com/markhazleton/SampleMvcCRUD/actions/workflows/main_mwhsampleweb.yml/badge.svg)](https://github.com/markhazleton/SampleMvcCRUD/actions/workflows/main_mwhsampleweb.yml)
6+
[![Docker Image](https://github.com/markhazleton/SampleMvcCRUD/actions/workflows/docker-image.yml/badge.svg)](https://github.com/markhazleton/SampleMvcCRUD/actions/workflows/docker-image.yml)
77

8-
https://github.com/markhazleton/SampleMvcCRUD/blob/main/.github/workflows/docker-image.yml
8+
---
99

10+
## 🌐 Live Demo & Deployments
1011

11-
For deployments there are multiple approaches:
12+
- **Windows IIS VM (.NET 9):** [samplecrud.markhazleton.com](https://samplecrud.markhazleton.com/)
13+
- **Azure App Service (.NET 9, Linux, GitHub Actions):** [mwhsampleweb.azurewebsites.net](https://mwhsampleweb.azurewebsites.net/)
14+
- **Azure App Service (Docker Image):** [samplecrud.azurewebsites.net](https://samplecrud.azurewebsites.net/)
15+
- **Docker Hub Image:** [markhazleton/mwhsampleweb](https://hub.docker.com/r/markhazleton/mwhsampleweb)
1216

13-
1) *current* [GitHub Action](https://github.com/markhazleton/SampleMvcCRUD/actions/workflows/main_mwhsampleweb.yml) with Continuous Integration/Continuous Deployment (CI/CD) to Docker Hub and Azure App Services
14-
1) *current* [GitHub Action](https://github.com/markhazleton/SampleMvcCRUD/actions/workflows/docker-image.yml) to push Docker Image to Docker Hub, then have Azure App Service configured to pull latest version from Docker Hub.
15-
1) [Azure DevOps project](https://dev.azure.com/markhazleton/SampleMvcCRUD) with Continuous Integration/Continuous Deployment (CI/CD) pipelines to Azure App Services
17+
---
1618

17-
Web application is hosted:
18-
- Microsoft Azure Virtual Machine - Windows 2022 IIS - Net 8 [samplecrud.markhazleton.com](https://samplecrud.markhazleton.com/)
19-
- Microsoft Azure AppService .Net 8 Linux Deployed via GitHub Actions [mwhsampleweb.azurewebsites.net](https://mwhsampleweb.azurewebsites.net/)
20-
- Microsoft Azure AppService .Net 8 Linux Image from docker hub [samplecrud.azurewebsites.net](https://samplecrud.azurewebsites.net/)
21-
- Docker Hub Image [markhazleton/mwhsampleweb](https://hub.docker.com/r/markhazleton/mwhsampleweb)
19+
## 🚀 Project Goals
2220

23-
## Customization
21+
- Demonstrate multiple ways to build CRUD UIs in ASP.NET Core MVC
22+
- Showcase best practices for architecture, testing, and deployment
23+
- Provide a reference for theming, API design, and modern web techniques
24+
- Enable easy customization and extension for your own projects
2425

25-
SampleMvcCrud is open source and you’re encouraged to contribute.
26+
---
2627

27-
## Contributing
28+
## 🏗️ Features & Architecture
2829

29-
You can contribute in several ways.
30-
- **Issues:** Provide a detailed report of any bugs you encounter and open an issue on [GitHub](https://github.com/markhazleton/SampleMvcCrud/issues).
31-
- **Documentation:** If you'd like to fix a typo or beef up the docs, you can fork the project, make your changes, and submit a pull request.
32-
- **Code:** Make a fix and submit it as a pull request.
33-
- **Platform:** Right now this has a MVC Web solution, I would love a React/Vue or Mobile version, but my skills are not there yet.
30+
- **Multiple CRUD Implementations:**
31+
- Classic MVC Controllers & Views
32+
- Razor Pages
33+
- Single Page (JavaScript-driven) UI
34+
- Pivot Table integration (PivotTable.js)
35+
- **API-First Design:**
36+
- RESTful endpoints for Employees and Departments
37+
- Swagger/OpenAPI documentation ([API Docs](/swagger/))
38+
- **Modern UI/UX:**
39+
- Responsive Bootstrap 5 layout
40+
- [WebSpark.Bootswatch](https://www.nuget.org/packages/WebSpark.Bootswatch/) theme switcher (light/dark, instant theme change)
41+
- Bootstrap Icons
42+
- DataTables integration for advanced tables
43+
- **Security & Configuration:**
44+
- Azure Key Vault integration for secrets
45+
- App Insights telemetry
46+
- Health checks endpoint (`/health`)
47+
- **DevOps & CI/CD:**
48+
- GitHub Actions for build, test, Docker, and Azure deployment
49+
- Azure DevOps pipeline example
50+
- Dockerfile for containerized builds
51+
- **Testing:**
52+
- Unit tests for domain and repository layers
53+
- **Extensible Architecture:**
54+
- Clean separation of Domain, Repository, and Web projects
55+
- Dependency Injection throughout
56+
- Example HttpClientFactory usage
3457

35-
## Author
58+
---
3659

37-
Mark Hazleton
38-
+ https://markhazleton.com
60+
## 🖌️ Theme Switcher (WebSpark.Bootswatch)
3961

40-
## Thanks
41-
To the many teachers and developers that post sample code under open source license.
62+
This app features a dynamic theme switcher using [WebSpark.Bootswatch](https://www.nuget.org/packages/WebSpark.Bootswatch/):
4263

43-
## Copyright and License
44-
Copyright 2018-2024 Mark Hazleton
45-
Code released under the MIT License.
64+
- Instantly change the site's look with any [Bootswatch](https://bootswatch.com/) theme
65+
- Light/dark mode support
66+
- User preferences are saved in the browser
67+
- Implemented via `<bootswatch-theme-switcher />` tag helper and JavaScript
4668

69+
---
4770

71+
## 🏁 Getting Started
72+
73+
### Prerequisites
74+
75+
- [.NET 9 SDK](https://dotnet.microsoft.com/download)
76+
- (Optional) [Docker](https://www.docker.com/)
77+
78+
### Run Locally
79+
80+
```pwsh
81+
# Clone the repository
82+
git clone https://github.com/markhazleton/SampleMvcCRUD.git
83+
cd SampleMvcCRUD
84+
85+
# Restore and run the web app
86+
dotnet restore
87+
cd Mwh.Sample.Web
88+
dotnet run
89+
```
90+
91+
Visit [https://localhost:5001](https://localhost:5001) in your browser.
92+
93+
### Run with Docker
94+
95+
```pwsh
96+
docker build -t mwhsampleweb ./Mwh.Sample.Web
97+
docker run -p 8080:80 mwhsampleweb
98+
```
99+
100+
---
101+
102+
## 🧩 Project Structure
103+
104+
- `Mwh.Sample.Web/` - Main ASP.NET Core MVC web app
105+
- `Mwh.Sample.Domain/` - Domain models and interfaces
106+
- `Mwh.Sample.Repository/` - Data access and repository pattern
107+
- `Mwh.Sample.HttpClientFactory/` - HttpClient usage examples
108+
- `SampleMinimalApi/` - Minimal API example
109+
- `Mwh.Sample.Domain.Tests/`, `Mwh.Sample.Repository.Tests/` - Unit tests
110+
111+
---
112+
113+
## 📚 Key Techniques Demonstrated
114+
115+
- **MVC, Razor Pages, and SPA patterns in one solution**
116+
- **API-first development with Swagger/OpenAPI**
117+
- **Modern Bootstrap theming and instant theme switching**
118+
- **Azure Key Vault for secure configuration**
119+
- **Health checks and Application Insights**
120+
- **CI/CD with GitHub Actions and Azure DevOps**
121+
- **Docker containerization**
122+
- **Extensible, testable architecture**
123+
124+
---
125+
126+
## 📝 Customization & Contribution
127+
128+
SampleMvcCRUD is open source and welcomes contributions!
129+
130+
- **Issues:** [File an issue](https://github.com/markhazleton/SampleMvcCRUD/issues)
131+
- **Pull Requests:** Fork, branch, and submit your improvements
132+
- **Documentation:** Help improve this README or add more docs
133+
- **Feature Ideas:** React/Vue/Mobile UI contributions are welcome
134+
135+
See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
136+
137+
---
138+
139+
## 👤 About the Author
140+
141+
**Mark Hazleton** is a solutions architect and lifelong learner with a passion for building technology that delivers real business value. With extensive experience in both on-premises and cloud-based solutions, Mark has worked with organizations of all sizes—from small business websites to large enterprise projects. He is dedicated to pragmatic, outcome-focused software development, and is an advocate for clear communication, agile practices, and continuous learning.
142+
143+
- [GitHub Profile](https://github.com/markhazleton)
144+
- [LinkedIn](https://www.linkedin.com/in/markhazleton)
145+
- [Personal Website](https://markhazleton.com)
146+
147+
*For all questions, contributions, and support, please use the [GitHub repository issues](https://github.com/markhazleton/SampleMvcCRUD/issues) and pull requests. Community participation is welcome and encouraged!*
148+
149+
---
150+
151+
## 🙏 Acknowledgements
152+
153+
Thanks to the open source community, teachers, and developers who share their knowledge and code.
154+
155+
---
156+
157+
## ⚖️ License
158+
159+
Copyright 2018-2025 Mark Hazleton
160+
Code released under the MIT License. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)