References, Using & NuGet-DLLs einbinden

~6 Min

Was du lernst

• Den References-Tab der C#-Action und seine Default-DLLs verstehen
• Default-Using-Direktiven kennen und eigene ergänzen
• Eine externe DLL oder ein NuGet-Paket einbinden und nutzen
• Compile-Fehler durch Target-Mismatch und fehlende Abhängigkeiten vermeiden

Voraussetzungen

• C#-Grundgerüst

Solange du nur mit dem CPH-Objekt und den eingebauten Klassen arbeitest, musst du dich um Referenzen nie kümmern. Sobald du aber eine Bibliothek von außen brauchst, also ein NuGet-Paket als DLL oder eine eigene fertig kompilierte Assembly, kommt der References-Tab der C#-Action ins Spiel. Hier sagst du dem Compiler, welche zusätzlichen DLLs er kennen soll und welche using-Direktiven standardmäßig gelten.

Core ›C# Code ›Execute C# Code

Doku: docs.streamer.bot · C# Guide

Der References-Tab

Im Editor der Execute C# Code Sub-Action gibt es neben dem Code-Feld einen Tab References. Er hat zwei Bereiche:

• References: die Liste der referenzierten DLLs. Hier hängen schon einige Standard-Assemblies drin, und hier fügst du eigene hinzu.
• Usings: die Liste der using-Direktiven, die vor jedem Kompilieren automatisch oben an deinen Code gesetzt werden. Das spart dir das wiederholte Tippen der immer gleichen Namespaces.

Der entscheidende Punkt: eine DLL zu referenzieren macht ihre Typen für den Compiler verfügbar. Damit du die Typen ohne vollen Namespace-Pfad ansprechen kannst, brauchst du zusätzlich das passende using. Das sind zwei getrennte Schritte. Beides fehlt am Anfang gern, siehe die Fallen unten.

Der Editor bietet dafür den Button Find Refs, der versucht, anhand deiner using-Direktiven passende Standard-Referenzen automatisch zu ergänzen. Mit Save and Compile stößt du danach den Build an und siehst Fehler direkt im Log.

Default-Referenzen und Default-Usings

Streamer.bot referenziert von Haus aus die gängigen .NET-Framework-Assemblies plus ein paar Bibliotheken, die intern ohnehin genutzt werden. Die wichtigste fürs tägliche Scripting:

• Newtonsoft.Json ist standardmäßig referenziert. JsonConvert, JObject und Co. stehen also ohne eigenes Zutun bereit. Wie du damit serialisierst und parst, zeigt JSON mit Newtonsoft.
• System.Net.Http ist verfügbar, du kannst HttpClient ohne extra Referenz nutzen, siehe HttpClient & APIs.
• Dazu kommen die üblichen Framework-Assemblies sowie die Streamer.bot-eigenen DLLs (Streamer.bot.Plugin.Interface, Streamer.bot.Common), über die CPH und CPHInlineBase kommen.

An Default-Usings sind unter anderem System, System.Collections.Generic und System.Linq gesetzt, dazu die Streamer.bot-Namespaces wie Streamer.bot.Plugin.Interface. Verlass dich aber nicht blind darauf: schau im Usings-Bereich nach, was bei deiner Version wirklich drinsteht. Brauchst du einen Namespace, der nicht gelistet ist, hast du zwei Wege. Entweder du schreibst das using selbst oben in deinen Code, oder du trägst es einmalig im Usings-Bereich ein, dann gilt es für jeden Compile dieser Action.

Welche DLLs sind wirklich drin?

Die Default-Liste kann sich zwischen Streamer.bot-Versionen ändern. Die verbindliche Quelle ist immer der References-Tab deiner Installation, nicht eine Tabelle aus dem Netz. Ein Blick dort kostet zwei Sekunden und erspart dir Raten.

Target: .NET Framework 4.8

Streamer.bot kompiliert deinen C#-Code gegen das .NET Framework 4.8.1 (net481). Das ist kein Detail am Rande, sondern die zentrale Vorgabe beim Einbinden fremder DLLs: Eine Assembly, die für .NET 6/7/8 oder .NET Standard 2.1 gebaut wurde, lädt hier nicht sauber. Du brauchst Builds für .NET Framework 4.x oder .NET Standard 2.0 (das ist abwärtskompatibel zum Framework).

Genau dieser Target-Wert taucht auch im externen Editor wieder auf. Wenn du in VS Code arbeitest, steht in der .csproj ein TargetFramework von net481. Details dazu in C# in VS Code.

Eine eigene DLL einbinden

Angenommen, du hast eine DLL MyHelper.dll mit einem Namespace MyHelper und darin eine Klasse Greeter mit einer statischen Methode Hello(string name). So bindest du sie ein:

1. Referenz hinzufügen: Im References-Tab die MyHelper.dll zur Liste der Referenzen hinzufügen. Lege die DLL an einen festen Ort, idealerweise in deinen Streamer.bot-Ordner oder ein Unterverzeichnis davon, damit der Pfad stabil bleibt.
2. Using ergänzen: Den Namespace bekanntmachen, entweder im Usings-Bereich oder direkt im Code.
3. Typen nutzen: Im Execute() ganz normal verwenden.

using MyHelper;

public class CPHInline
{
    public bool Execute()
    {
        string text = Greeter.Hello("Streamer");
        CPH.SendMessage(text);
        return true;
    }
}

Save and Compile löst den Build aus. Geht er durch, ist die DLL korrekt referenziert und das using greift. Schlägt er fehl, sagt dir das Log meist sehr genau, woran es liegt (siehe Fallen).

NuGet-Pakete als DLL

Streamer.bot installiert keine NuGet-Pakete direkt. Du nutzt ein NuGet-Paket, indem du seine DLL einbindest. Der praktikable Weg:

1. Das Paket in einem normalen Projekt (oder via nuget.exe bzw. dem NuGet-Package-Explorer) auf .NET Framework 4.8 oder .NET Standard 2.0 ziehen.
2. Aus dem Paket die DLL herausholen. Achtung: Pakete bestehen oft aus mehreren DLLs, eine Hauptassembly plus Abhängigkeiten.
3. Alle benötigten DLLs an deinen festen Ort legen und jede einzeln im References-Tab referenzieren.
4. Pro Namespace, den du im Code ansprichst, das passende using setzen.

Der häufigste Fehler hier: nur die Haupt-DLL einbinden und die Abhängigkeiten vergessen. Zur Laufzeit fliegt dann eine FileNotFoundException oder TypeLoadException, obwohl der Compile noch durchlief. Nimm die transitiven Abhängigkeiten von Anfang an mit.

Newtonsoft nicht doppelt einbinden

Newtonsoft.Json ist bereits referenziert. Bringst du über ein NuGet-Paket eine andere Version derselben DLL mit, gibt es einen Versionskonflikt. Nutze die bereits vorhandene Referenz, statt eine zweite hinzuzufügen.

Referenzen im externen Editor

Arbeitest du im externen Editor (VS Code), referenzierst du dieselben DLLs in deiner .csproj, damit IntelliSense funktioniert. Damit derselbe Code in beiden Welten kompiliert, leiten viele Projekte die Klasse hinter einem Präprozessor-Guard ab:

#if EXTERNAL_EDITOR
public class MyAction : CPHInlineBase
#else
public class CPHInline
#endif
{
    public bool Execute()
    {
        return true;
    }
}

Lokal erbt die Klasse von CPHInlineBase und trägt einen eindeutigen Namen, damit mehrere Dateien im Projekt nicht kollidieren. Beim Zurückkopieren nach Streamer.bot greift der #else-Zweig, also die fixe Klasse CPHInline, die intern automatisch von CPHInlineBase erbt. So bekommst du im Editor CPH-IntelliSense, ohne in Streamer.bot etwas anpassen zu müssen.

Häufige Fallen

• Target-Mismatch: Die DLL ist für .NET 6/7/8 oder .NET Standard 2.1 gebaut, Streamer.bot kompiliert aber gegen .NET Framework 4.8.1. Resultat: Lade- oder Compile-Fehler. Immer Builds für net4.x oder netstandard2.0 verwenden.
• Referenz fehlt, Compile-Fehler im Log: Du nutzt einen Typ, dessen DLL nicht referenziert ist. Der Compiler meldet The type or namespace name '...' could not be found. Die Meldung landet im Streamer.bot-Log mit Zeilennummer. Fehlende DLL im References-Tab nachtragen.
• NuGet liefert mehrere DLLs: Nur die Haupt-DLL eingebunden, Abhängigkeiten vergessen. Compile geht durch, zur Laufzeit kommt FileNotFoundException oder TypeLoadException. Alle DLLs aus dem Paket referenzieren.
• using vergessen: Die DLL ist referenziert, aber der Namespace nicht per using bekannt. Dann musst du jeden Typ voll qualifizieren (MyHelper.Greeter.Hello(...)) oder eben das using setzen. Sauberer ist das using.
• DLL verschoben oder gelöscht: Du hast die DLL aus einem temporären Ordner referenziert und später aufgeräumt. Beim nächsten Compile findet Streamer.bot sie nicht mehr. DLLs an einen festen Ort legen und dort lassen.
• Version doppelt: Eine zweite Version einer bereits referenzierten Assembly (typisch Newtonsoft.Json) eingebunden. Versionskonflikt. Die vorhandene Default-Referenz nutzen.

Verwandt

• JSON mit NewtonsoftNutzt eine Default-Referenz.
• C# in VS CodeReferenzen im externen Editor.