Beyhan Oğur
15 KiB
Deployment and Distribution
**Referenced Files in This Document** - [ClassicAssist.sln](file://ClassicAssist.sln) - [appveyor.yml](file://appveyor.yml) - [azure-pipelines.yml](file://azure-pipelines.yml) - [ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj) - [ClassicAssist.csproj](file://ClassicAssist/ClassicAssist.csproj) - [ClassicAssist.Shared.csproj](file://ClassicAssist.Shared/ClassicAssist.Shared.csproj) - [ClassicAssist.Launcher.csproj](file://ClassicAssist.Launcher/ClassicAssist.Launcher.csproj) - [ClassicAssist.Updater.csproj](file://ClassicAssist.Updater/ClassicAssist.Updater.csproj) - [Program.cs](file://ClassicAssist.Avalonia/Program.cs) - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document provides comprehensive deployment and distribution guidance for ClassicAssist.Avalonia, a cross-platform Ultima Online assistant application built with Avalonia UI framework. The system supports multiple platforms including Windows, macOS, and Linux, with automated build pipelines and update mechanisms.
The application follows a modular architecture with separate components for the main application, launcher, updater, and shared functionality. This structure enables flexible deployment strategies and platform-specific optimizations.
Project Structure
The ClassicAssist.Avalonia solution consists of multiple projects organized by functionality:
graph TB
subgraph "Solution Structure"
SLN[ClassicAssist.sln]
subgraph "Main Applications"
AVA[ClassicAssist.Avalonia]
LAUNCHER[ClassicAssist.Launcher]
UPDATER[ClassicAssist.Updater]
end
subgraph "Core Libraries"
SHARED[ClassicAssist.Shared]
CLASSIC[ClassicAssist]
end
subgraph "Testing"
TESTS[ClassicAssist.Tests]
UITEST[ClassicAssist.UITest]
end
subgraph "Tools"
EXPORT[ExportCommands]
end
end
SLN --> AVA
SLN --> LAUNCHER
SLN --> UPDATER
SLN --> SHARED
SLN --> CLASSIC
SLN --> TESTS
SLN --> UITEST
SLN --> EXPORT
AVA --> SHARED
AVA --> CLASSIC
LAUNCHER --> SHARED
UPDATER --> SHARED
Diagram sources
The solution is structured to support both WPF (legacy) and Avalonia (modern) UI frameworks, with the Avalonia version being the primary target for cross-platform deployment.
Section sources
Core Components
Build System Architecture
The build system leverages MSBuild with .NET SDK-style project files, supporting multi-targeting for different platforms and frameworks.
Key Build Configuration Points
- Multi-targeting Support: Projects target multiple .NET versions for compatibility
- Cross-platform Compilation: Avalonia framework enables Windows, macOS, and Linux builds
- Asset Management: Embedded resources and content files are handled through project configuration
- Platform-specific Optimizations: Conditional compilation for platform-specific features
Project Dependencies
graph LR
subgraph "Runtime Dependencies"
DOTNET[.NET Runtime]
AVALONIA[Avalonia Framework]
UO[UO Game Client]
end
subgraph "Build Dependencies"
MSBUILD[MSBuild]
NUGET[NuGet Packages]
GIT[Git Version Control]
end
subgraph "Deployment Artifacts"
WIN[Windows Installer]
MAC[macOS Package]
LINUX[Linux Package]
CONTAINER[Docker Image]
end
DOTNET --> WIN
DOTNET --> MAC
DOTNET --> LINUX
AVALONIA --> WIN
AVALONIA --> MAC
AVALONIA --> LINUX
UO --> WIN
UO --> MAC
UO --> LINUX
MSBUILD --> WIN
MSBUILD --> MAC
MSBUILD --> LINUX
NUGET --> WIN
NUGET --> MAC
NUGET --> LINUX
GIT --> WIN
GIT --> MAC
GIT --> LINUX
Diagram sources
Section sources
Architecture Overview
Application Architecture
The ClassicAssist.Avalonia application follows a layered architecture pattern with clear separation of concerns:
classDiagram
class Program {
+Main(args) void
+CreateBuilder() AppBuilder
}
class App {
+OnFrameworkInitializationCompleted() void
+ConfigureServices() void
+SetupApplication() void
}
class Engine {
+Initialize() void
+Start() void
+Stop() void
+UpdateCheck() bool
}
class MainWindow {
+DataContext MainWindowViewModel
+InitializeComponent() void
+OnLoaded() void
}
class SharedComponents {
<<library>>
+DataModels
+BusinessLogic
+Utilities
}
Program --> App : "initializes"
App --> Engine : "configures"
App --> MainWindow : "creates"
MainWindow --> SharedComponents : "uses"
Engine --> SharedComponents : "depends on"
Diagram sources
Update System Architecture
The auto-update system provides seamless version management with rollback capabilities:
sequenceDiagram
participant App as "Main Application"
participant Updater as "Updater Process"
participant Server as "Update Server"
participant FileSystem as "File System"
App->>Updater : CheckForUpdates()
Updater->>Server : GET /api/versions/latest
Server-->>Updater : LatestVersionInfo
Updater->>Updater : CompareVersions()
alt New Version Available
Updater->>Server : DownloadUpdate(version)
Server-->>Updater : UpdatePackage
Updater->>FileSystem : VerifySignature()
Updater->>FileSystem : BackupCurrentVersion()
Updater->>FileSystem : InstallNewVersion()
Updater->>App : RestartWithNewVersion()
else No Updates
Updater->>App : ContinueRunning()
end
Note over App,FileSystem : Rollback if update fails
Diagram sources
Detailed Component Analysis
Build Pipeline Configuration
Multi-Targeting Strategy
The project uses conditional compilation and platform-specific configurations to support multiple targets:
| Target Platform | Framework | Output Format | Special Requirements |
|---|---|---|---|
| Windows (.NET 8.0) | net8.0-windows | EXE/DLL | Windows SDK, Visual Studio |
| macOS (.NET 8.0) | net8.0-macos | APP Bundle | Xcode Command Line Tools |
| Linux (.NET 8.0) | net8.0 | Self-contained | Platform dependencies |
| Cross-platform | net8.0 | Portable | .NET Runtime only |
Build Stages
- Source Compilation: C# code compilation with Roslyn compiler
- Resource Processing: XAML/Axaml processing and asset embedding
- Native Dependencies: Platform-specific native library linking
- Packaging: Application bundling and artifact generation
- Signing: Code signing and integrity verification
- Distribution: Artifact publishing to release channels
Section sources
Auto-Update System Implementation
Version Management
The update system implements semantic versioning with automatic comparison logic:
flowchart TD
Start([Application Start]) --> CheckLocal["Read Local Version"]
CheckLocal --> FetchRemote["Fetch Remote Manifest"]
FetchRemote --> ParseRemote["Parse Remote Version"]
ParseRemote --> Compare{"Version > Local?"}
Compare --> |Yes| Download["Download Update Package"]
Compare --> |No| Skip["Skip Update"]
Download --> Verify["Verify Digital Signature"]
Verify --> ValidSig{"Signature Valid?"}
ValidSig --> |No| Error["Display Security Warning"]
ValidSig --> |Yes| Backup["Backup Current Installation"]
Backup --> Install["Install New Version"]
Install --> TestRun["Test Run New Version"]
TestRun --> Success{"Test Successful?"}
Success --> |Yes| Complete["Complete Update"]
Success --> |No| Rollback["Rollback to Previous Version"]
Skip --> End([Continue Running])
Error --> End
Complete --> End
Rollback --> End
Diagram sources
Update Server Configuration
The update server requires specific endpoints and response formats:
| Endpoint | Method | Purpose | Response Format |
|---|---|---|---|
/api/versions/latest |
GET | Get latest version info | JSON manifest |
/api/updates/{version} |
GET | Download update package | Binary stream |
/api/signatures/{version} |
GET | Get signature file | Cryptographic signature |
/api/changelog/{version} |
GET | Get version changelog | Markdown text |
Section sources
Distribution Channels
Windows Distribution
Windows deployments support multiple installation methods:
- MSI Installer: Traditional Windows installer with registry integration
- Portable Executable: Standalone executable without installation
- Microsoft Store: Modern app store distribution
- Chocolatey: Package manager distribution
macOS Distribution
macOS deployments utilize Apple's ecosystem:
- DMG Disk Image: Standard macOS disk image format
- PKG Installer: System-level installation with permissions
- Homebrew: Package manager distribution
- App Bundle: Self-contained application bundle
Linux Distribution
Linux deployments support various package formats:
- AppImage: Portable Linux application format
- Snap Package: Canonical's containerized packages
- Flatpak: Universal Linux package format
- DEB/RPM: Native package manager formats
Section sources
Dependency Analysis
External Dependencies
The application has several critical external dependencies that must be managed during deployment:
graph TB
subgraph "Critical Dependencies"
DOTNETCORE[.NET 8.0 Runtime]
AVALONIAUI[Avalonia UI Framework]
SERIALIZATION[System.Text.Json]
LOGGING[Serilog Logging]
CONFIGURATION[Configuration Management]
end
subgraph "Optional Dependencies"
PYTHON[Python Integration]
NATIVE[Native Libraries]
DATABASE[SQLite Database]
NETWORK[HTTP Client]
end
subgraph "Platform Specific"
WINSDK[Windows SDK]
XCODE[Xcode Tools]
LINUXDEPS[Linux Dependencies]
end
DOTNETCORE --> AVALONIAUI
AVALONIAUI --> SERIALIZATION
AVALONIAUI --> LOGGING
AVALONIAUI --> CONFIGURATION
SERIALIZATION --> PYTHON
LOGGING --> DATABASE
CONFIGURATION --> NETWORK
WINSDK --> DOTNETCORE
XCODE --> DOTNETCORE
LINUXDEPS --> DOTNETCORE
Diagram sources
Build-Time Dependencies
Build-time dependencies include development tools and packaging utilities:
| Tool | Purpose | Platform Support |
|---|---|---|
| MSBuild | Project compilation | All platforms |
| NuGet | Package management | All platforms |
| Signtool | Code signing | Windows only |
| codesign | Apple code signing | macOS only |
| fpm | Package creation | All platforms |
| docker | Containerization | All platforms |
Section sources
Performance Considerations
Build Optimization
Several strategies can optimize build performance:
- Incremental Builds: Leverage MSBuild incremental compilation
- Parallel Compilation: Enable parallel project building
- Artifact Caching: Cache NuGet packages and build artifacts
- Conditional Compilation: Use preprocessor directives for platform-specific code
- Trimming: Enable .NET trimming for reduced deployment size
Runtime Performance
Runtime performance considerations include:
- Memory Management: Efficient memory usage patterns
- I/O Operations: Asynchronous file operations for better responsiveness
- Network Requests: Connection pooling and caching strategies
- UI Rendering: Optimized Avalonia rendering pipeline usage
- Background Processing: Proper thread management for long-running tasks
Troubleshooting Guide
Common Build Issues
| Issue | Symptoms | Resolution |
|---|---|---|
| Missing .NET Runtime | Application fails to start | Install .NET 8.0 Runtime |
| Platform-specific errors | Crashes on specific OS | Verify platform dependencies |
| Permission denied | Cannot write to installation directory | Run with elevated privileges |
| Network timeout | Update check fails | Check firewall/proxy settings |
| Invalid signature | Update rejected | Verify certificate chain |
Deployment Validation
Post-deployment validation steps:
- Installation Verification: Confirm all files are present
- Permission Testing: Verify read/write access to required directories
- Network Connectivity: Test update server connectivity
- Signature Validation: Verify digital signatures
- Functionality Testing: Run core application features
Section sources
Conclusion
ClassicAssist.Avalonia provides a robust, cross-platform deployment architecture supporting multiple distribution channels and update mechanisms. The modular design enables flexible deployment strategies while maintaining security and reliability through digital signatures and rollback capabilities.
The CI/CD pipeline ensures consistent builds across platforms, while the update system provides seamless version management. Platform-specific optimizations ensure optimal performance on each target operating system.
Appendices
Quick Start Deployment Checklist
- Install required development tools
- Configure build environment variables
- Set up code signing certificates
- Configure update server endpoints
- Test builds on all target platforms
- Validate digital signatures
- Deploy to staging environment
- Perform smoke testing
- Release to production channels
Environment Variables
| Variable | Purpose | Default Value |
|---|---|---|
SIGNING_CERT_PATH |
Path to signing certificate | None |
UPDATE_SERVER_URL |
Update server endpoint | https://updates.classicassist.com |
BUILD_CONFIGURATION |
Build configuration | Release |
TARGET_PLATFORM |
Target platform | net8.0 |
OUTPUT_DIRECTORY |
Build output path | ./bin/Release |