Developing OpenSim Addins/de
From OpenSimulator
Contents
|
Developing OpenSim Addins
Diese Seite erklärt, wie man OpenSimulator Region Module Addins entwickelt, paketiert und verteilt. Sie richtet sich an Entwickler, die zusätzliche Funktionalität bereitstellen möchten, die über die Kernverteilung von OpenSim hinausgeht, und die diese in binärer Form an andere weitergeben möchten. Diese Anleitung bezieht sich auf Region Module, die auf den Simulatoren laufen. Es wird vorausgesetzt, dass Sie bereits mit den Grundlagen der Entwicklung von Region Modulen vertraut sind.
Hinweis: Diese Dokumentation wurde für OpenSimulator Version 0.9.3.x mit .NET 8.0 Runtime aktualisiert.
Wenn Sie nach der Installation von Drittanbieter-Addins suchen, lesen Sie bitte diese andere Seite.
Voraussetzungen
Bevor Sie OpenSim Addins entwickeln, stellen Sie sicher, dass Sie Folgendes haben:
- .NET 8.0 SDK installiert (https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
- OpenSimulator 0.9.3.x Quellcode oder Entwicklungsumgebung
- Grundlegendes Verständnis von C# und OpenSim Region Module Entwicklung
Das finale Paket
OpenSim enthält mehrere eingebaute Addins, die als Beispiele dienen. Zwei gute Referenzen sind:
- OpenSim.Addons.OfflineIM - Verarbeitet Offline-Sofortnachrichten
- OpenSim.Addons.Groups - Stellt Gruppenfunktionalität bereit
Ein typisches Addin-Paket enthält:
- Die Region Module DLL
- Alle externen Abhängigkeiten (zusätzliche DLLs)
- Konfigurationsdateien (.ini)
- Zusätzliche Ressourcen (HTML-Dateien, Bilder, etc.)
Dies sind alle Dateien, die OpenSim-Benutzer benötigen, um das Addin in ihren Installationen auszuführen.
Addin-Direktiven
Wie üblich sollte das Region Module mit dem Extension-Attribut als OpenSim Region Module annotiert werden:
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "IhrModulId")]
public class IhrModul : ISharedRegionModule
{
...
}
Für nicht-geteilte Region Module verwenden Sie stattdessen INonSharedRegionModule.
Zusätzlich sollte das Assembly, das das Region Module enthält, die folgenden Direktiven in Properties/AssemblyInfo.cs enthalten:
// Diese Zeilen sind für die Addin-Paketierung erforderlich
[assembly: Addin("IhrAddin.Name", OpenSim.VersionInfo.VersionNumber + ".1")]
[assembly: AddinDependency("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)]
[assembly: AddinDescription("Beschreibung Ihres Addins")]
[assembly: AddinAuthor("Ihr Name")]
// Die nächsten Zeilen sind optional - externe Abhängigkeiten einbinden
[assembly: ImportAddinAssembly("ExterneBibliothek.dll")]
[assembly: ImportAddinFile("IhreKonfig.ini")]
[assembly: ImportAddinFile("ressource.html")]
Addin-Direktiven verstehen
Die erste Direktive [assembly: Addin("IhrAddin.Name", OpenSim.VersionInfo.VersionNumber + ".1")] legt den öffentlichen Namen Ihres Addins fest: Dies ist, was die Benutzer sehen werden. Achten Sie besonders auf die Versionsnummer. Während Sie jede beliebige Versionsnummer verwenden können, wird dringend empfohlen, die Versionsnummer Ihres Addins mit der OpenSim-Version zu verknüpfen, gegen die Sie Ihren Code kompilieren.
Mit .NET 8.0 ist die Binärkompatibilität weiterhin wichtig, daher sollten Sie Ihre Benutzer darüber informieren, mit welcher OpenSim-Version dieses Addin kompatibel ist. Der direkteste Weg, diese Information weiterzugeben, besteht darin, sie zur Versionsnummer Ihres Addins hinzuzufügen. In diesem Fall verwenden wir die ersten Ziffern, um die OpenSim-Versionsnummer (z.B. 0.9.3.1) anzugeben, und die letzte Ziffer, um die eigene Version dieses Addins anzugeben. Wenn wir dieses Addin zwischen OpenSim-Releases weiterentwickeln würden, würde diese letzte Ziffer auf 2 erhöht, während die ersten Ziffern gleich blieben.
Die zweite Direktive [assembly: AddinDependency("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)] legt die Abhängigkeit mit der konkreten OpenSim-DLL fest, die dieses Addin erweitert. Alle Region Module Addins erweitern OpenSim.Region.Framework. Auch hier sollte die Versionsnummer die aktuelle OpenSim-Versionsnummer sein, da dies die DLL ist, gegen die Sie Ihren Code kompilieren. Für eine Erklärung, wie die Versionierung funktioniert, siehe Installing_3rd_party_addins#Versioning
Die dritte und vierte Direktive geben eine Beschreibung und Autorenschaft-Informationen für Ihr Addin.
Die letzten Direktiven (ImportAddinAssembly, ImportAddinFile) binden zusätzliche Dateien in das Paket ein, die notwendig sind, damit die Addins in den Umgebungen Ihrer Benutzer funktionieren. Die Direktive [assembly: ImportAddinAssembly("ExterneBibliothek.dll")] hat zwei Zwecke: (1) sie bindet diese DLL in das Paket ein und (2) sie informiert die Laufzeitumgebung des Benutzers, dass diese DLL ebenfalls geladen werden sollte, wenn unser Addin in den Speicher geladen wird.
Beispiel: OfflineIM Addon
Das OfflineIM-Addon, das mit OpenSim ausgeliefert wird, demonstriert Best Practices:
Modul-Deklaration:
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "OfflineIMConnectorModule")]
public class OfflineIMRegionModule : ISharedRegionModule, IOfflineIMService
{
public void Initialise(IConfigSource config)
{
IConfig cnf = config.Configs["Messaging"];
if (cnf == null)
return;
if (cnf != null && cnf.GetString("OfflineMessageModule", string.Empty) != Name)
return;
m_Enabled = true;
// ... Initialisierungscode
}
public void AddRegion(Scene scene)
{
if (!m_Enabled)
return;
scene.RegisterModuleInterface<IOfflineIMService>(this);
// ... Region-Setup
}
// ... andere Interface-Methoden
}
AssemblyInfo.cs:
[assembly: Addin("OpenSim.OfflineIM", OpenSim.VersionInfo.VersionNumber)]
[assembly: AddinDependency("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)]
Konfiguration
Ein sehr wichtiger Teil des Prozesses hat mit der Konfiguration Ihres Addins zu tun. Anstatt Benutzer zu zwingen, ihre OpenSim.ini-Dateien manuell zu bearbeiten und den zu Ihrem Addin gehörenden Konfigurationsabschnitt hinzuzufügen, empfehlen wir die Verwendung modularer Konfigurationen. In modularen Konfigurationen sind Ihre Komponenten dafür verantwortlich, ihre eigenen Konfigurationsdateien zu lesen.
Hier ist das empfohlene Muster zum Laden der Konfiguration:
public void Initialise(IConfigSource config)
{
// Wir laden die Konfigurationsdatei nur, wenn die Hauptkonfiguration noch nichts über dieses Modul weiß
IConfig cnf = config.Configs["IhrModulName"];
if (cnf == null)
{
LoadConfiguration(config);
cnf = config.Configs["IhrModulName"];
if (cnf == null)
{
m_log.WarnFormat("[IHR MODUL]: Konfigurationsabschnitt nicht gefunden. Kann nicht fortfahren.");
return;
}
}
// Konfigurationswerte lesen
m_Enabled = cnf.GetBoolean("Enabled", false);
// ... weitere Konfiguration
}
LoadConfiguration sollte wie folgt deklariert werden:
private void LoadConfiguration(IConfigSource config)
{
string configPath = string.Empty;
bool created;
if (!Util.MergeConfigurationFile(config, "IhrModul.ini",
Path.Combine(AssemblyDirectory, "IhrModul.ini"),
out configPath, out created))
{
m_log.WarnFormat("[IHR MODUL]: Konfigurationsdatei nicht zusammengeführt");
return;
}
if (created)
{
m_log.ErrorFormat("[IHR MODUL]: BITTE BEARBEITEN SIE {0} VOR DEM AUSFÜHREN DIESES ADDINS", configPath);
throw new Exception("Addin muss vor dem Ausführen konfiguriert werden");
}
}
private static string AssemblyDirectory
{
get
{
string location = Assembly.GetExecutingAssembly().Location;
return Path.GetDirectoryName(location);
}
}
Diese Methode verwendet OpenSim.Framework.Util.MergeConfigurationFile, die die ConfigDirectory-Variable aus der OpenSim-Konfiguration liest und prüft, ob die Konfigurationsdatei dieses Moduls bereits vorhanden ist. Wenn ja, wird sie einfach mit den OpenSim-Konfigurationen zusammengeführt. Wenn nicht, kopiert sie die Konfigurationsdatei, die sie im Paket mitgebracht hat, in das ConfigDirectory und warnt den Operator, dass er sie nach seinen Bedürfnissen bearbeiten sollte.
Projektstruktur
OpenSim 0.9.3.x verwendet entweder traditionelle prebuild.xml oder moderne .NET SDK-Style .csproj-Dateien.
Verwendung von Prebuild (Traditionell)
Wenn Sie prebuild.xml verwenden, stellen Sie sicher, dass alle notwendigen Dateien in das Ausgabeverzeichnis kopiert werden:
<Project name="OpenSim.Addon.IhrModul" path="addon-modules/IhrModul" type="Library">
<Configuration name="Debug">
<Options>
<OutputPath>../../bin/</OutputPath>
<AllowUnsafe>true</AllowUnsafe>
</Options>
</Configuration>
<Configuration name="Release">
<Options>
<OutputPath>../../bin/</OutputPath>
<AllowUnsafe>true</AllowUnsafe>
</Options>
</Configuration>
<ReferencePath>../../bin/</ReferencePath>
<Reference name="Nini" path="../../bin/"/>
<Reference name="log4net" path="../../bin/"/>
<Reference name="Mono.Addins" path="../../bin/"/>
<Reference name="OpenSim.Region.Framework"/>
<Reference name="OpenSim.Framework"/>
<Files>
<Match pattern="*.cs" recurse="true">
<Exclude name="obj" pattern="obj"/>
<Exclude name="Tests" pattern="Tests"/>
</Match>
<Match pattern="*.ini" buildAction="Copy" destination="../../bin/" />
<Match pattern="*.html" buildAction="Copy" destination="../../bin/" />
</Files>
</Project>
Nach dem Erstellen/Ändern von prebuild.xml ausführen:
$ runprebuild.bat (Windows) $ ./runprebuild.sh (Linux/Mac)
Verwendung von .NET SDK-Style Projekten (Modern)
Moderne .NET 8.0-Projekte können SDK-Style .csproj-Dateien direkt verwenden:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<OutputPath>../../bin/</OutputPath>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
</PropertyGroup>
<ItemGroup>
<Reference Include="Mono.Addins" HintPath="../../bin/Mono.Addins.dll" Private="False" />
<ProjectReference Include="../../OpenSim/Region/Framework/OpenSim.Region.Framework.csproj" />
<ProjectReference Include="../../OpenSim/Framework/OpenSim.Framework.csproj" />
</ItemGroup>
<ItemGroup>
<None Update="*.ini" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
</Project>
Ihr Addon bauen
Mit Prebuild
1. Führen Sie Prebuild aus, um Projektdateien zu generieren
2. Bauen Sie mit dotnet oder Visual Studio:
$ dotnet build IhrAddon.csproj -c Release
Mit direkter .csproj
$ dotnet build IhrAddon.csproj -c Release
Alle Ausgabedateien sollten im bin/-Verzeichnis neben anderen OpenSim-Assemblies landen.
Das Addin paketieren
Um die Dateien für die Verteilung zu paketieren, verwenden Sie das mautil Kommandozeilen-Tool, das im OpenSim bin-Verzeichnis enthalten ist.
$ /pfad/zu/mautil.exe pack bin/IhrAddon.dll
Dies erstellt eine Datei namens IhrAddon_0.9.3.1.1.mpack (Version kann variieren). Dies ist das Addin-Paket, das an den Standorten der Benutzer verteilt und installiert wird.
Beachten Sie, dass .mpack-Dateien komprimierte (zip) Archive sind. Sie können sie öffnen und ihren Inhalt mit Tools zur Inspektion von Zip-Dateien überprüfen.
mautil-Befehle
Das mautil-Tool (Mono.Addins Manager) unterstützt mehrere Befehle:
- pack - Erstellt ein .mpack-Paket aus einer DLL
- rep-build - Baut ein Addin-Repository
- install - Installiert ein Addin aus einem Repository
- uninstall - Deinstalliert ein Addin
- list - Listet installierte Addins auf
Für weitere Informationen:
$ /pfad/zu/mautil.exe --help
Ihre Addins verteilen
Um Ihre Addins anderen zur Verfügung zu stellen, müssen Sie Ihr eigenes Addin-Repository erstellen und es auf einem Webserver hosten.
Um das Repository zu erstellen, erstellen Sie irgendwo einen Ordner und platzieren Sie alle Ihre Addin-Pakete (.mpack) darin. Dann:
$ /pfad/zu/mautil.exe rep-build /pfad/zu/repo/ordner
Dies erstellt zusätzliche Indexdateien (main.mrep, root.mrep) mit den richtigen Einträgen. Alles, was Sie als Nächstes tun müssen, ist den gesamten Inhalt dieses Ordners auf einen Webserver hochzuladen.
Schließlich müssen Sie Ihre Benutzer über die URL Ihres Repositorys informieren, damit sie es zu ihren Registern hinzufügen und Addins aus Ihrem Repository installieren können. Sie können Ihr Repo hier hinzufügen.
Best Practices
- Versionskompatibilität: Kompilieren Sie immer gegen die spezifische OpenSim-Version, die Ihr Addon anvisiert
- Konfiguration: Verwenden Sie modulare Konfigurationsdateien, anstatt manuelle OpenSim.ini-Bearbeitungen zu erfordern
- Abhängigkeiten: Dokumentieren Sie alle externen Abhängigkeiten klar
- Testen: Testen Sie Ihr Addon sowohl mit Standalone- als auch mit Grid-Konfigurationen
- Dokumentation: Stellen Sie klare Installations- und Konfigurationsanweisungen bereit
- Protokollierung: Verwenden Sie geeignete Log-Level (Debug, Info, Warn, Error)
- .NET 8.0: Stellen Sie Kompatibilität mit .NET 8.0 Runtime sicher
- Fehlerbehandlung: Implementieren Sie ordnungsgemäße Fehlerbehandlung und geben Sie aussagekräftige Fehlermeldungen
Fehlerbehebung
Häufige Probleme
- Assembly nicht gefunden: Stellen Sie sicher, dass alle referenzierten Assemblies im bin-Verzeichnis sind
- Versions-Missmatch: Überprüfen Sie, dass OpenSim.VersionInfo.VersionNumber mit Ihrer OpenSim-Installation übereinstimmt
- Modul lädt nicht: Prüfen Sie, dass das Extension-Attribut korrekt ist und das Modul das richtige Interface implementiert
- Konfiguration nicht gefunden: Überprüfen Sie, dass die .ini-Datei ins bin-Verzeichnis kopiert wurde und MergeConfigurationFile aufgerufen wird
- .NET Runtime-Probleme: Stellen Sie sicher, dass .NET 8.0 Runtime installiert ist
Siehe auch
- New Region Modules - Dokumentation zur Region Module Entwicklung
- Installing 3rd party addins - Anleitung für Benutzer zur Installation von Addins
- List of 3rd Party Addin Repositories - Community-Addon-Repositories
