[skip-ci] Example and readme

README.md

@@ -1,4 +1,83 @@
-# TwitchLib.Client
+# TwitchLib.Client
 Client component of TwitchLib.
 
-For a general overview and example, refer to https://github.com/TwitchLib/TwitchLib/blob/master/README.md
+> [!TIP]
+> With the introduction of Chat on EventSub, it is recommended to upgrade your chatbots that are using Twitch IRC to use EventSub (for reading chat messages and roomstates) and Twitch API (for sending chat messages).
+
+## Installation
+
+| NuGet            |       | [![TwitchLib.Client][1]][2]                                       |
+| :--------------- | ----: | :---------------------------------------------------------------- |
+| Package Manager  | `PM>` | `Install-Package TwitchLib.Client -Version 4.0.1`                 |
+| .NET CLI         | `>`   | `dotnet add package TwitchLib.Client --version 4.0.1`             |
+| PackageReference |       | `<PackageReference Include="TwitchLib.Client" Version="4.0.1" />` |
+| Paket CLI        | `>`   | `paket add TwitchLib.Client --version 4.0.1`                      |
+
+[1]: https://img.shields.io/nuget/v/TwitchLib.Client.svg?label=TwitchLib.Client
+[2]: https://www.nuget.org/packages/TwitchLib.Client
+
+## ⚠ Breaking Changes in Version 4.0.1 ⚠
+
+Version 4.0.1 contains breaking changes.
+- Removed obsolete methods.
+- Methods are now asynchronous. (The return value changed from `void` to `Task` and gains `Async` suffix)
+- Events are now asynchronous (return value changed from `void` to `Task`)
+- `Add/RemoveChatCommandIdentifier` methods were removed, use `ChatCommandIdentifiers` property instead (same applies to whisper);
+- `OnLog` event was removed (you can still use `ILoggerFactory` to get logs)
+- removed builders classes (removed `TwitchLib.Client.Models.Builders namespace`)
+- changed public fields to properties
+- rewritten all models in `TwitchLib.Client.Models`
+    - some props/classes can be slightly renamed
+    - some properties (`IsModerator`, `IsSubscriber`, `HasTurbo`, `IsVip`, `IsPartner`, `IsStaff`) moved to the `UserDetails` property
+
+## Minimal Setup
+Step 1: Create a new Console project
+
+Step 2: Install the `TwitchLib.Client` NuGet package. (See above on how to do that)
+
+Step 2.5: (Optional) Install the [`Microsoft.Extensions.Logging.Console`](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Console) NuGet package (or some other compatible logging provider) to see logs.
+
+Step 3: Add the following code to your `Program.cs` file:
+```cs
+using Microsoft.Extensions.Logging;
+using TwitchLib.Client;
+using TwitchLib.Client.Events;
+using TwitchLib.Client.Models;
+
+// Optional logger
+var loggerFactory = LoggerFactory.Create(c => c
+    .AddConsole()
+//    .SetMinimumLevel(LogLevel.Trace) // uncomment to view raw messages received from twitch
+);
+
+var credentials = new ConnectionCredentials(); // anonymous user, add Username and OAuth token to get the ability to send messages
+var client = new TwitchClient(loggerFactory: loggerFactory);
+
+client.Initialize(credentials);
+client.OnConnected += Client_OnConnected;
+client.OnJoinedChannel += Client_OnJoinedChannel;
+client.OnMessageReceived += Client_OnMessageReceived;
+
+await client.ConnectAsync();
+await Task.Delay(Timeout.Infinite);
+
+
+async Task Client_OnConnected(object? sender, OnConnectedEventArgs e)
+{
+    await client.JoinChannelAsync("channel_name"); // replace with the channel you want to join
+}
+
+async Task Client_OnJoinedChannel(object? sender, OnJoinedChannelArgs e)
+{
+    Console.WriteLine($"Connected to {e.Channel}");
+    await client.SendMessageAsync(e.Channel, "Hey guys! I am a bot connected via TwitchLib!");
+}
+
+async Task Client_OnMessageReceived(object? sender, OnMessageReceivedArgs e)
+{
+    Console.WriteLine($"{e.ChatMessage.Username}#{e.ChatMessage.Channel}: {e.ChatMessage.Message}");
+}
+```
+Step 4: Change the `channel_name` in the `Client_OnConnected` method to the name of the channel you want to join and run the application.
+
+More complete examples can be found in the [TwitchLib.Client.Example](/TwitchLib.Client.Example/)

TwitchLib.Client.Example/Program.cs

@@ -0,0 +1,101 @@
+using Microsoft.Extensions.Logging;
+using TwitchLib.Client;
+using TwitchLib.Client.Events;
+using TwitchLib.Client.Models;
+
+var loggerFactory = LoggerFactory.Create(c => c
+    .AddConsole()
+    //.SetMinimumLevel(LogLevel.Trace) // uncomment to view raw messages received from twitch
+);
+
+var credentials = new ConnectionCredentials(); // anonymous user, add Username and OAuth token to get the ability to send messages
+var client = new TwitchClient(loggerFactory: loggerFactory)
+{
+    ChatCommandIdentifiers = { '!', '?' }, // you can customize the command identifiers, if not set, defaults to '!'
+};
+
+client.Initialize(credentials);
+client.OnConnected += Client_OnConnected;
+client.OnJoinedChannel += Client_OnJoinedChannel;
+client.OnMessageReceived += Client_OnMessageReceived;
+
+client.OnChatCommandReceived += Client_OnChatCommandReceived;
+
+await client.ConnectAsync();
+await Task.Delay(Timeout.Infinite);
+
+
+async Task Client_OnConnected(object? sender, OnConnectedEventArgs e)
+{
+    await client.JoinChannelAsync("piratesoftware"); // replace with the channel you want to join
+}
+
+async Task Client_OnJoinedChannel(object? sender, OnJoinedChannelArgs e)
+{
+    Console.WriteLine($"Connected to {e.Channel}");
+    await client.SendMessageAsync(e.Channel, "Hey guys! I am a bot connected via TwitchLib!");
+}
+
+async Task Client_OnMessageReceived(object? sender, OnMessageReceivedArgs e)
+{
+    Console.WriteLine($"{e.ChatMessage.Username}#{e.ChatMessage.Channel}: {e.ChatMessage.Message}");
+}
+
+async Task Client_OnChatCommandReceived(object? sender, OnChatCommandReceivedArgs e)
+{
+    var channel = e.ChatMessage.Channel;
+    var command = e.Command;
+
+    switch (command.Name.ToLower())
+    {
+        case "info":
+            await client.SendMessageAsync(channel, "Hi, I am a bot created using TwitchLib.Client.");
+            break;
+        case "repeat":
+            if (string.IsNullOrWhiteSpace(command.ArgumentsAsString))
+                return;
+            await client.SendMessageAsync(channel, command.ArgumentsAsString);
+            break;
+        case "leave":
+            if (!e.ChatMessage.IsBroadcaster)
+                return;
+            await client.SendMessageAsync(channel, "Goodbye! I am leaving the channel.");
+            await client.LeaveChannelAsync(channel);
+            break;
+        case "help":
+            if (command.ArgumentsAsList.Count is 0)
+            {
+                var helpText = "Available commands: !info, !repeat <message>, !help [command]";
+                if (e.ChatMessage.IsBroadcaster)
+                    helpText += ", !leave";
+
+                await client.SendMessageAsync(channel, helpText);
+                return;
+            }
+            switch (command.ArgumentsAsList[0])
+            {
+                case "info":
+                    await client.SendMessageAsync(channel, "The !info command provides information about the bot.");
+                    break;
+                case "repeat":
+                    await client.SendMessageAsync(channel, "The !repeat command repeats the message you provide.");
+                    break;
+                case "help":
+                    await client.SendMessageAsync(channel, "The !help command provides information about available commands.");
+                    break;
+                case "leave":
+                    if (!e.ChatMessage.IsBroadcaster)
+                        return;
+
+                    await client.SendMessageAsync(channel, "The !leave command makes the bot leave the channel.");
+                    break;
+                default:
+                    await client.SendMessageAsync(channel, $"No help available for command: {command.ArgumentsAsList[0]}");
+                    break;
+            }
+            break;
+        default:
+            Console.WriteLine($"Unknown command: {command.Name}");
+            break;
+    }
+}

TwitchLib.Client.Example/TwitchLib.Client.Example.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="8.0.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\TwitchLib.Client\TwitchLib.Client.csproj" />
+  </ItemGroup>
+
+</Project>

TwitchLib.Client.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio 15
-VisualStudioVersion = 15.0.27130.2027
+# Visual Studio Version 17
+VisualStudioVersion = 17.14.36310.24
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TwitchLib.Client", "TwitchLib.Client\TwitchLib.Client.csproj", "{44B88EFA-1500-4005-AF27-A9BCB9DD79C1}"
 EndProject
@@ -17,6 +17,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tests", "Tests", "{8C69E628
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TwitchLib.Client.Benchmark", "TwitchLib.Client.Benchmark\TwitchLib.Client.Benchmark.csproj", "{7E666AC9-B717-4E00-A3CB-16950275D3FD}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TwitchLib.Client.Example", "TwitchLib.Client.Example\TwitchLib.Client.Example.csproj", "{0C5D0C17-346C-6CE8-EC3E-4DCAC37152FC}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -43,6 +45,10 @@ Global
 		{7E666AC9-B717-4E00-A3CB-16950275D3FD}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{7E666AC9-B717-4E00-A3CB-16950275D3FD}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{7E666AC9-B717-4E00-A3CB-16950275D3FD}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0C5D0C17-346C-6CE8-EC3E-4DCAC37152FC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0C5D0C17-346C-6CE8-EC3E-4DCAC37152FC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0C5D0C17-346C-6CE8-EC3E-4DCAC37152FC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0C5D0C17-346C-6CE8-EC3E-4DCAC37152FC}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE