Welcome to the complete technical documentation for the Package Script Writer project. This documentation provides comprehensive coverage of all aspects of the application, from architecture to deployment.
Package Script Writer is a web-based utility that generates installation scripts for Umbraco CMS projects. Built with ASP.NET Core 10.0, it provides a streamlined interface for developers to create customized Umbraco project setup scripts.
- 🎯 Template Selection - Choose from Umbraco official & community templates
- 📦 Package Management - Browse and select from 150+ NuGet packages
- ⚙️ Project Configuration - Configure solutions, databases, and credentials
- 🐳 Docker Support - Optional Dockerfile and Docker Compose generation
- 🔗 Shareable URLs - All configuration encoded in shareable URLs
- 💾 Persistent State - Save/restore configurations via localStorage
- 🎨 Syntax Highlighting - Clean, readable script output
Production: https://psw.codeshare.co.uk
The project also includes a powerful command-line interface available as a .NET Global Tool:
📦 NuGet Package: PackageScriptWriter.Cli
📖 Complete CLI Documentation: CLI Documentation
The documentation is organized into the following sections:
Learn about the application's structure, layers, and design patterns.
Topics:
- High-level architecture diagram
- Application layers (Presentation, Service, Infrastructure)
- Project structure and file organization
- Technology stack
- Component interaction
- Design patterns and scalability
➡️ Read Architecture Documentation
Visual diagrams showing how data and processes flow through the system.
Topics:
- User interaction flow
- Script generation flow
- Package version retrieval
- URL synchronization
- Application startup
- Event handling
- External API integration
Includes: 10+ Mermaid.js diagrams
➡️ Read Process Flows Documentation
Detailed documentation of the business logic layer.
Topics:
- ScriptGeneratorService (327 lines of core logic)
- MarketplacePackageService (API integration)
- QueryStringService (URL handling)
- UmbracoVersionService (version management)
- Service interfaces and dependency injection
- Caching strategies
➡️ Read Services Documentation
Complete REST API documentation with examples.
Topics:
- Generate Script endpoint
- Get Package Versions endpoint
- Clear Cache endpoint
- Request/response formats
- Error handling
- Rate limiting
- Testing with cURL, Postman, REST Client
Client-side architecture including JavaScript and UI components.
Topics:
- JavaScript architecture (740+ lines)
- View Components
- Event handling
- State management
- URL synchronization
- Syntax highlighting
- Bootstrap UI framework
- Performance optimizations
➡️ Read Frontend Documentation
All data structures and models used in the application.
Topics:
- PackagesViewModel (main view model)
- PagedPackages (Marketplace response)
- NuGet API models
- Configuration models
- API request/response DTOs
- Model relationships and validation
➡️ Read Data Models Documentation
Application settings and configuration guide.
Topics:
- appsettings.json structure
- Dependency injection setup
- Middleware configuration
- Caching configuration
- Environment-specific settings
- Logging configuration
- MVC and routing setup
➡️ Read Configuration Documentation
Security measures and best practices.
Topics:
- Security headers middleware
- HTTPS and HSTS
- Input validation
- No database = reduced attack surface
- OWASP Top 10 mitigation
- Dependency security
- Security checklist
➡️ Read Security Documentation
Complete guide for developers to get started.
Topics:
- Prerequisites and installation
- Getting started (clone, build, run)
- Development workflow
- Testing (integration, API, manual)
- Building and deployment
- Code style guidelines
- Contributing process
- Troubleshooting
Comprehensive testing documentation for all testing approaches.
Topics:
- Integration tests with xUnit
- API testing with Swagger UI
- Continuous integration with GitHub Actions
- Writing new tests
- FluentAssertions usage
- Testing best practices
- Troubleshooting test failures
Complete documentation for the Package Script Writer CLI tool (psw).
Topics:
- Installation and setup (global tool)
- Interactive mode workflow
- Command-line flags and options
- Template system for reusable configurations
- History tracking and re-running scripts
- Code architecture and structure
- Troubleshooting and logging
Additional CLI Resources:
- CLI Interactive Mode Flow - Visual diagrams of interactive mode workflow
- Template System - Template save/load documentation
- History System - History tracking documentation
- CLI Release Process - Publishing to NuGet
➡️ Read CLI Tool Documentation
- Visit https://psw.codeshare.co.uk
- Select your Umbraco template and version
- Choose packages to include
- Configure project settings
- Generate and copy your script!
# Clone repository
git clone https://github.com/prjseal/Package-Script-Writer.git
cd Package-Script-Writer
# Run application
dotnet watch run --project ./src/PSW/
# Access at https://localhost:5001See the Development Guide for detailed setup instructions.
| Category | Technology | Version |
|---|---|---|
| Framework | ASP.NET Core | 10.0 |
| Language | C# | 13 |
| Frontend | Razor Pages | - |
| JavaScript | Vanilla JS | ES6+ |
| UI Framework | Bootstrap | 5.x |
| Caching | IMemoryCache | Built-in |
| HTTP Client | HttpClientFactory | Built-in |
Generate a script to set up a new Umbraco 14 project with SQLite database:
dotnet new install Umbraco.Templates::14.3.0 --force
dotnet new umbraco --force -n "MyProject" --development-database-type SQLite
dotnet run --project "MyProject"Create a complete solution with multiple packages, Docker support, and unattended install.
Share configuration URLs with team members for consistent project setups.
Generate consistent scripts for training materials and tutorials.
| Metric | Count |
|---|---|
| C# Files | 49 |
| Razor Views | 21 |
| View Components | 10+ |
| JavaScript LOC | 740+ |
| Service Layer LOC | 327 (ScriptGeneratorService) |
| Total Project Lines | 4,000+ |
| Supported Umbraco Versions | 7-21+ |
| Package Marketplace | 150+ packages |
graph TB
A[User Browser] --> B[Razor Views + JavaScript]
B --> C[MVC Controllers]
C --> D[Service Layer]
D --> E[External APIs]
D --> F[In-Memory Cache]
E --> G[NuGet.org]
E --> H[Umbraco Marketplace]
style A fill:#e1f5ff
style D fill:#fff4e1
style F fill:#e8f5e9
Key Components:
- Presentation Layer: Controllers and View Components
- Service Layer: Business logic (4 main services)
- Infrastructure: Caching and HTTP clients
- External APIs: NuGet.org and Umbraco Marketplace
See Architecture Documentation for detailed diagrams.
We welcome contributions! Please see the Development Guide for detailed instructions.
- Raise an issue (bug or feature)
- Discuss approach in the issue
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
- Follow existing code style
- Test your changes thoroughly
- Update documentation if needed
- Write clear commit messages
- Reference related issues in PR
License: MIT License (2022)
Author: Paul Seal
- Website: https://psw.codeshare.co.uk
- GitHub: @prjseal
Technologies:
- ASP.NET Core (Microsoft)
- Bootstrap (Twitter)
- PrettyPrint.js (Google)
Data Sources:
- Umbraco Marketplace API
- NuGet.org API
Browse the documentation sections listed above for detailed information on specific topics.
- Bug Reports: Create an issue with reproduction steps
- Feature Requests: Create an issue describing the feature and use case
- Questions: Check existing issues or create a new one
- Umbraco Community: https://community.umbraco.com/
- Umbraco Discord: https://discord.umbraco.com/
- Live Site: https://psw.codeshare.co.uk
- GitHub Repository: https://github.com/prjseal/Package-Script-Writer
- Issues: https://github.com/prjseal/Package-Script-Writer/issues
- Umbraco Documentation: https://docs.umbraco.com
- Umbraco Marketplace: https://marketplace.umbraco.com
- NuGet Gallery: https://www.nuget.org
- ASP.NET Core Docs: https://docs.microsoft.com/aspnet/core
| Version | Date | Changes |
|---|---|---|
| 3.0 | 2024 | Upgraded to .NET 10.0, added version lifecycle display |
| 2.0 | 2023 | Added Docker support, one-liner output, starter kits |
| 1.0 | 2022 | Initial release with basic script generation |
Use the links above to navigate to specific documentation sections, or browse the files in the .github/ directory:
- architecture.md - System architecture and design
- process-flows.md - Process flow diagrams
- services.md - Service layer documentation
- api-reference.md - REST API reference
- frontend.md - Frontend architecture
- data-models.md - Data structures
- configuration.md - Configuration guide
- security.md - Security documentation
- development-guide.md - Development setup
- testing.md - Testing guide and best practices
- ../src/PackageCliTool/README.md - CLI tool documentation
- CLI-Interactive-Mode-Flow.md - CLI interactive mode flow diagrams
Document Version: 2.0 Last Updated: 2025-12-04 Maintained By: Package Script Writer Team
Ready to dive in? Start with the Development Guide if you're a developer, or explore the Architecture to understand how everything works!