Zebra Puma Framework

Services & Plugins pour Windows et .NET

---

📚 Vue d'ensemble

ZebraPuma est un framework d'entreprise conçu pour faciliter le développement d'applications modulaires, de services Windows et d'outils d'analyse de données. Le framework offre une architecture extensible basée sur des plugins, permettant une grande flexibilité et une maintenance simplifiée.

Auteur

Régis SCYEUR - Zebra Puma Services

Copyright

© 2025-2026 Régis SCYEUR - Zebra Puma Services - Tous droits réservés

Licence

Licence Propriétaire - Voir le fichier LICENSE

---

🏗️ Architecture de la Solution

La solution ZebraPuma est organisée en plusieurs bibliothèques réutilisables et applications :

📦 Composants Principaux

Composant	Type	Description	Cibles
ZebraPuma.Plugins	Bibliothèque	Système de plugins modulaire avec chargement dynamique	.NET 4.8, .NET 10.0
ZebraPuma.System.ServiceProcess	Bibliothèque	Gestion avancée des services Windows avec support plugins	.NET 4.8, .NET 10.0-windows

---

📖 Documentation Détaillée

Bibliothèques Core

• ZebraPuma.Plugins - Système de plugins avec chargement dynamique

  • Architecture plugin/host
  • Chargement automatique et manuel
  • Gestion du cycle de vie
  • Résolution des dépendances

• ZebraPuma.System.ServiceProcess - Services Windows extensibles

  • Services basés sur plugins
  • Interface de contrôle WinForms
  • Gestion centralisée multi-services
  • Support .NET Framework et .NET moderne

🚀 Démarrage Rapide

Prérequis

• Windows 10 ou supérieur
• .NET Framework 4.8 pour les applications .NET Framework
• .NET 10.0 SDK pour les applications .NET modernes
• Visual Studio 2022 (recommandé) ou Visual Studio Code

Installation via NuGet

# 1. Ajouter le source GitHub Packages
dotnet nuget add source https://nuget.pkg.github.com/ZebraPumaOrg/index.json \
  --name ZebraPuma \
  --username VOTRE_USERNAME \
  --password VOTRE_GITHUB_PAT

# 2. Installer les packages
dotnet add package ZebraPuma.Plugins --version 2.0.6
dotnet add package ZebraPuma.System.ServiceProcess --version 2.0.6

Authentification GitHub Packages :

1. Créez un Personal Access Token (PAT) avec le scope read:packages
2. Utilisez votre username GitHub et le PAT comme mot de passe

Configuration nuget.config (Optionnel)

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="ZebraPuma" value="https://nuget.pkg.github.com/ZebraPumaOrg/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <ZebraPuma>
      <add key="Username" value="VOTRE_USERNAME" />
      <add key="ClearTextPassword" value="VOTRE_PAT" />
    </ZebraPuma>
  </packageSourceCredentials>
</configuration>

Utilisation de Base

Créer un Plugin Simple

using ZebraPuma.Plugins;

public class MonPlugin : PluginBase
{
    public override string Name => "MonPlugin";
    public override string Description => "Un exemple de plugin";

    public override void Initialize(IPluginContext context)
    {
        base.Initialize(context);
        // Logique d'initialisation
    }
}

Charger des Plugins

var plugins = PluginLoader.LoadPlugins<IPlugin>();
foreach (var plugin in plugins)
{
    Console.WriteLine($"Plugin chargé: {plugin.Name} v{plugin.Version}");
}

Créer un Service Windows

using ZebraPuma.System.ServiceProcess;

public class MonService : ServiceBaseExtended
{
    public override string Name => "MonService";
    
    protected override void OnStartCore(string[] args)
    {
        // Logique de démarrage
    }
    
    protected override void OnStopCore()
    {
        // Logique d'arrêt
    }
}

---

📁 Structure du Projet

ZebraPuma/
├── docs/                                    # Documentation complète
│   ├── README.md                           # Ce fichier
│   ├── plugins.md                          # Doc ZebraPuma.Plugins
│   ├── serviceprocess.md                   # Doc ZebraPuma.System.ServiceProcess
│   └── examples/                           # Exemples de code
├── src/
│   └── dotnet/
│       ├── ZebraPuma.sln                   # Solution Visual Studio
│       ├── Directory.Build.props            # Configuration partagée
│       ├── ZebraPuma.Plugins/              # Bibliothèque de plugins
│       ├── ZebraPuma.System.ServiceProcess/ # Bibliothèque de services
│       └── (autres projets internes)
├── LICENSE                                  # Licence propriétaire
└── README.md                               # README principal

---

🔧 Configuration

Configuration des Plugins (plugins.json)

{
  "AutoDiscover": true,
  "Plugins": [
    {
      "Folder": "MonPlugin",
      "Assembly": "MonPlugin.dll",
      "Type": "MonNamespace.MonPlugin"
    }
  ]
}

Configuration NLog

Chaque bibliothèque inclut une configuration NLog pour le logging :

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target name="file" xsi:type="File" 
            fileName="${basedir}/logs/${shortdate}.log" />
  </targets>
  <rules>
    <logger name="*" minlevel="Info" writeTo="file" />
  </rules>
</nlog>

---

🔌 Dépendances

Packages NuGet Communs

• Newtonsoft.Json 13.0.4 - Sérialisation JSON
• NLog 6.0.7 - Logging structuré

Packages Spécifiques

ZebraPuma.System.ServiceProcess

• System.ServiceProcess.ServiceController 9.0.0 (.NET 10.0 uniquement)

---

📊 Fonctionnalités Principales

ZebraPuma.Plugins

• ✅ Chargement dynamique de plugins depuis DLL
• ✅ Auto-découverte des plugins dans les dossiers
• ✅ Configuration JSON flexible
• ✅ Résolution automatique des dépendances d'assemblies
• ✅ Gestion du cycle de vie (Initialize, Dispose)
• ✅ Support multi-frameworks (.NET 4.8 et .NET 10.0)

ZebraPuma.System.ServiceProcess

• ✅ Services Windows étendus avec interface IServiceExtended
• ✅ Classe de base ServiceBaseExtended thread-safe
• ✅ ServiceManager pour gérer plusieurs services
• ✅ Interface WinForms de contrôle (ServiceControllerForm)
• ✅ Intégration avec le système de plugins
• ✅ Support multi-frameworks avec Windows Forms

---

🛠️ Compilation et Déploiement

Compilation en Ligne de Commande

# Compiler toute la solution
dotnet build src\dotnet\ZebraPuma.sln --configuration Release

# Compiler un projet spécifique
dotnet build src\dotnet\ZebraPuma.Plugins\ZebraPuma.Plugins.csproj

# Créer les packages NuGet
dotnet pack src\dotnet\ZebraPuma.Plugins\ZebraPuma.Plugins.csproj --configuration Release

Publication

# Publier pour .NET Framework 4.8
dotnet publish src\dotnet\ZebraPuma.System.ServiceProcess\ZebraPuma.System.ServiceProcess.csproj `
    --configuration Release `
    --framework net48 `
    --output publish\net48

---

📝 Bonnes Pratiques

Développement de Plugins

1. Héritage de PluginBase : Utiliser PluginBase pour bénéficier du pattern Dispose
2. Nom unique : Chaque plugin doit avoir un nom unique
3. Versioning : Suivre le versioning sémantique (SemVer)
4. Logging : Utiliser NLog pour tracer les opérations
5. Configuration : Utiliser PluginConfigLoader pour charger la configuration

Développement de Services

1. Thread Safety : Les services doivent être thread-safe
2. Gestion d'erreurs : Capturer et logger toutes les exceptions
3. Timeout : Implémenter des timeouts pour les opérations longues
4. État : Maintenir un état cohérent (IsRunning)
5. Cleanup : Libérer toutes les ressources dans OnStopCore

---

🔍 Debugging et Troubleshooting

Logs

Les logs sont générés dans le dossier logs/ de chaque application :

{Application}/logs/{date}.log

Problèmes Courants

Le plugin ne se charge pas

• Vérifier que le fichier plugins.json existe
• Vérifier que le chemin Assembly est correct
• Consulter les logs NLog

Service ne démarre pas

• Vérifier les permissions Windows
• Vérifier que OnStartCore ne lève pas d'exception
• Consulter l'Event Viewer Windows

Erreur de résolution d'assembly

• Vérifier que toutes les DLL dépendantes sont présentes
• Utiliser Fusion Log Viewer pour diagnostiquer

---

🧪 Tests

Tests Unitaires

# Exécuter tous les tests
dotnet test src\dotnet\ZebraPuma.sln

# Tests avec couverture
dotnet test --collect:"XPlat Code Coverage"

---

📈 Roadmap

Version 2.1 (Q1 2026)

• [ ] Support .NET 11.0
• [ ] Amélioration du hot-reload des plugins
• [ ] Interface de configuration web

Version 2.2 (Q2 2026)

• [ ] Support Linux pour les bibliothèques core
• [ ] Plugin manager GUI
• [ ] Métriques et monitoring intégrés

---

🤝 Contribution

Ce projet est sous licence propriétaire. Les contributions externes ne sont pas acceptées sans accord commercial préalable.

Pour toute question commerciale :

• Email : contact@zebrapuma.services
• GitHub : https://github.com/ZebraPumaOrg

---

📜 Historique des Versions

v2.0.x (Décembre 2025)

• Migration depuis EuroJapan vers ZebraPuma
• Support multi-frameworks (.NET 4.8 et .NET 10.0)
• Refactoring complet de l'architecture
• Documentation complète

v1.0.x (2024)

• Version initiale dans le projet EuroJapan
• Support .NET Framework uniquement

---

🔗 Liens Utiles

• 📦 Repository des Packages
• 📚 Documentation Complète
• 📀 Packages NuGet
• 📄 Référence API
• 📜 Licence

---

ℹ️ Note : Le code source de développement est dans un repository privé. Seuls les packages NuGet compilés et la documentation sont publics.

---

Made with ❤️ by Régis SCYEUR, Zebra Puma Services