Updating readme and adding EventsExample readme

soxtoby · Apr 20, 2021 · e25c944 · e25c944
1 parent b7903a8
commit e25c944
Show file tree

Hide file tree

Showing 6 changed files with 102 additions and 26 deletions.
diff --git a/SlackNet.EventsExample/HomeController.cs b/SlackNet.EventsExample/HomeController.cs
@@ -0,0 +1,9 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace SlackNet.EventsExample
+{
+    public class HomeController : Controller
+    {
+        public IActionResult Index() => View();
+    }
+}
diff --git a/SlackNet.EventsExample/Properties/launchSettings.json b/SlackNet.EventsExample/Properties/launchSettings.json
@@ -10,12 +10,14 @@
   "profiles": {
     "IIS Express": {
       "commandName": "IISExpress",
+      "launchBrowser": true,
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       }
     },
     "SlackNet.EventsExample": {
       "commandName": "Project",
+      "launchBrowser": true,
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       },

diff --git a/SlackNet.EventsExample/Startup.cs b/SlackNet.EventsExample/Startup.cs
@@ -62,7 +62,7 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env)
                 .UseSigningSecret(Configuration["Slack:SigningSecret"])
                 .UseSocketMode(false));
 
-            app.UseMvc();
+            app.UseMvcWithDefaultRoute();
         }
     }
 }
diff --git a/SlackNet.EventsExample/Views/Home/Index.cshtml b/SlackNet.EventsExample/Views/Home/Index.cshtml
@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+    <title>SlackNet Events API Example</title>
+    <style>
+    body {
+        display:  flex;
+        flex-direction: row;
+        justify-content: center;
+        font-family: sans-serif;
+        color: hsl(0deg 0% 25%);
+    }
+
+    code {
+        background: hsl(0deg 0% 95%);
+        padding: 2px;
+    }
+
+    li {
+        line-height: 2;
+    }
+    </style>
+</head>
+<body>
+<div>
+    <h1>SlackNet Events API Example</h1>
+
+    <h2>What can you do?</h2>
+    <ul>
+        <li>Invite your app to a channel and post a message containing <code>test interactivity</code>.</li>
+        <li>Try the <code>/echo</code> slash command.</li>
+        <li>Set up a workflow with a test step. Note that this requires a paid Slack workspace.</li>
+    </ul>
+</div>
+</body>
+</html>
diff --git a/SlackNet.EventsExample/readme.md b/SlackNet.EventsExample/readme.md
@@ -0,0 +1,27 @@
+# ASP.NET Core Events Example
+
+## Slack setup
+
+Start by creating a [Slack app](https://api.slack.com/apps). 
+
+Subscribe to the `message.*` bot events and the `app_home_opened` workspace event.  
+
+Add the following [bot token](https://api.slack.com/authentication/token-types#granular_bot) scopes: `chat:write`, `im:write`.
+
+Once the application is up and running, fill in the event and interactivity request URLs with https://your-app/slack/event and https://your-app/slack/action respectively.
+
+To use the slash command example, create a slash command called `/echo` and point it at https://your-app/slack/command.
+
+To use the workflow example, follow Slack's [Steps from apps](https://api.slack.com/workflows/steps) guide, using `test_step` as the Callback ID when you create the step for your Slack app.
+
+## Project setup
+
+Fill in the `ApiToken` and `SigningSecret` settings in `appsettings.json`.
+
+The application needs to be made publicly available for Slack to be able to interact with it. When running locally, you can use a tool like [ngrok](https://ngrok.com/) get a public URL.
+
+Alternatively, you can switch to socket mode by following the instructions in the [socket mode example](../SlackNet.SocketModeExample/readme.md), and passing `true` into `UseSocketMode` in `Startup.cs`.
+
+## Running the example
+
+Run the `SlackNet.EventsExample` project. It should open a web page with further instructions.
diff --git a/readme.md b/readme.md
@@ -2,29 +2,34 @@
 An easy-to-use and flexible API for writing Slack bots in .NET, built on top of a comprehensive Slack API client.
 
 ## Getting Started
-There are three NuGet packages available to install, depending on your use case.
+There are three main NuGet packages available to install, depending on your use case.
   - [SlackNet](https://www.nuget.org/packages/SlackNet/): A comprehensive Slack API client for .NET.
   - [SlackNet.Bot](https://www.nuget.org/packages/SlackNet.Bot/): Easy-to-use API for writing Slack bots.
   - [SlackNet.AspNetCore](https://www.nuget.org/packages/SlackNet.AspNetCore/): ASP.NET Core integration for receiving requests from Slack.
 
 ### SlackNet
 To use the Web API:
 ```c#
-var api = new SlackApiClient("<your OAuth access token here>");
+var api = new SlackServiceBuilder()
+    .UseApiToken("<your OAuth access token here>")
+    .GetApiClient();
 ```
 then start calling methods:
 ```c#
 var channels = await api.Conversations.List();
 ```
 
-To use the RTM API:
+To use the socket mode client:
 ```c#
-var rtm = new SlackRtmClient("<your OAuth access token here>");
-await rtm.Connect();
-rtm.Events.Subscribe(/* handle every event */);
-rtm.Messages.Subscribe(/* handle message events */);
+var client = new SlackServiceBuilder()
+    .UseAppLevelToken("<app-level OAuth token required for socket mode>")
+    /* Register handlers here */
+    .GetSocketModeClient();
+await client.Connect();
 ```
 
+A range of handler registration methods are available, but all require that you construct the handlers manually. You can simplify handler registration by integrating with a DI container. Integrations are provided for Autofac, Microsoft.Extensions.DependencyInjection, and SimpleInjector. See the [socket mode release notes](https://github.com/soxtoby/SlackNet/releases/tag/v0.9.0) for more information. 
+
 ### SlackNet.Bot
 ```c#
 var bot = new SlackBot("<your bot token here>");
@@ -83,6 +88,14 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env)
 
 Add event handler registrations inside the AddSlackNet callback. See the `SlackNet.EventsExample` project for more detail.
 
+#### Socket Mode
+
+While testing an ASP.NET application, you can use socket mode instead of needing to host the website publicly, by enabling socket mode with:
+
+```c#
+app.UseSlackNet(c => c.UseSocketMode());
+```
+
 #### Azure Functions
 SlackNet.AspNetCore can be used in Azure Functions as well, although it's a little more manual at the moment.
 
@@ -105,24 +118,12 @@ See the `SlackNet.AzureFunctionExample` and `SlackNet.EventsExample` projects fo
 
 SlackNet requires the Slack app endpoints to be named after the following convention:
 
-**Event subscriptions**
-
-`{route_prefix}/event`
-
-
-**Interactivity**
-
-`{route_prefix}/action`
-
-
-**Select menus**
-
-`{route_prefix}/options`
-
-
-**Slash commands**
-
-`{route_prefix}/command`
+| Endpoint            | Route                    |
+|---------------------|--------------------------|
+| Event subscriptions | `{route_prefix}/event`   |
+| Interactivity       | `{route_prefix}/action`  |
+| Select menus        | `{route_prefix}/options` |
+| Slash commands      | `{route_prefix}/command` |
 
 
 By default, the value of `{route_prefix}` is `slack`, but this can be configured like so: