Skip to content

Commit 4ea796e

Browse files
mapalanmapalan
authored
Increment to 0.3.x-preview and update readme (#71)
1 parent be2e0b0 commit 4ea796e

File tree

17 files changed

+421
-130
lines changed

17 files changed

+421
-130
lines changed

‎README.md

+56-79
Original file line numberDiff line numberDiff line change
@@ -3,72 +3,50 @@
33

44
## Introduction
55
This repository contains the triggers and bindings to use in your [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-get-started) and [WebJobs](https://learn.microsoft.com/azure/app-service/webjobs-sdk-how-to).
6-
There are three triggers in the Azure Functions Redis Extension:
7-
- `RedisPubSubTrigger` triggers on [Redis pubsub messages](https://redis.io/docs/manual/pubsub/)
8-
- `RedisListTrigger` triggers on [Redis lists](https://redis.io/docs/data-types/lists/)
9-
- `RedisStreamTrigger` triggers on [Redis streams](https://redis.io/docs/data-types/streams/)
6+
There are three triggers in this extension:
7+
- `RedisPubSubTrigger` triggers on [Redis pub/sub messages](https://redis.io/docs/manual/pubsub/)
8+
- `RedisListTrigger` triggers on [Redis list entries](https://redis.io/docs/data-types/lists/)
9+
- `RedisStreamTrigger` triggers on [Redis stream entries](https://redis.io/docs/data-types/streams/)
1010

1111
## Getting Started
12-
1. [Set up an Azure Cache for Redis instance](https://learn.microsoft.com/azure/azure-cache-for-redis/quickstart-create-redis) or [install Redis locally](https://redis.io/download/).
13-
1. Install the [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local).
14-
1. Create a function project for .NET:
15-
```cmd
16-
mkdir RedisFunctions
17-
cd RedisFunctions
18-
func init --worker-runtime dotnet
19-
```
20-
1. Install the Redis Extension using `dotnet add package Microsoft.Azure.WebJobs.Extensions.Redis --prerelease`.
21-
For private preview, these are the following steps to add the nuget package to your project:
22-
1. Create a `NuGet.Config` file in the project folder (`RedisFunctions` in the above step):
23-
```
24-
<?xml version="1.0" encoding="utf-8"?>
25-
<configuration>
26-
<packageSources>
27-
<add key="local-packages" value="./local-packages" />
28-
</packageSources>
29-
</configuration>
30-
```
31-
1. Add the following line to the `<PropertyGroup>` section of the csproj.
32-
```
33-
<RestoreSources>$(RestoreSources);./local-packages;https://api.nuget.org/v3/index.json</RestoreSources>
34-
```
35-
1. Create a folder `local-packages` within the project folder, and download the latest NuGet package from [GitHub Releases](https://github.com/Azure/azure-functions-redis-extension/releases) to this `local-packages` folder.
36-
1. Install the package:
37-
```
38-
dotnet add package Microsoft.Azure.WebJobs.Extensions.Redis --prerelease
39-
dotnet restore
40-
```
12+
See the following docs for details on setup and samples of the Redis triggers:
13+
- [C# (in-process)](docs/SetupGuide_Dotnet.md)
14+
- [C# (out-of-process)](docs/SetupGuide_DotnetIsolated.md)
15+
- [Java](docs/SetupGuide_Java.md)
16+
- [Python](docs/SetupGuide_Python.md)
17+
- [JavaScript](docs/SetupGuide_JavaScript.md)
18+
- [PowerShell](docs/SetupGuide_PowerShell.md)
4119

4220
## Usage
4321
### `RedisPubSubTrigger`
44-
The `RedisPubSubTrigger` subscribes to a specific channel or channel pattern and surfaces messages received on those channels to the function.
22+
The `RedisPubSubTrigger` subscribes to a Redis pub/sub channel and surfaces messages received to the function.
4523

46-
> **Warning**
47-
> This trigger is not fully supported on a [Consumption plan](https://learn.microsoft.com/azure/azure-functions/consumption-plan) because Redis PubSub requires clients to always be actively listening to receive all messages.
48-
> For consumption plans, there is a chance your function may miss certain messages published to the channel.
24+
> **Note**
25+
> This trigger is only available on the [Premium plan](https://learn.microsoft.com/azure/azure-functions/premium-plan) and [Dedicated plan](https://learn.microsoft.com/azure/azure-functions/dedicated-plan) because Redis pub/sub requires clients to always be actively listening to receive all messages.
26+
> There is a chance your function may miss messages on a consumption plan.
4927
5028
> **Note**
51-
> In general, functions with this the `RedisPubSubTrigger` should not be scaled out to multiple instances.
52-
> Each functions instance trigger on each message from the channel, resulting in duplicate processing.
29+
> Functions with this trigger should not be scaled out to multiple instances.
30+
> Each instance will trigger on each message from the channel, resulting in duplicate processing.
5331
5432
#### Inputs
55-
- `ConnectionStringSetting`: Name of the setting in the appsettings that holds the to the redis cache connection string (eg `<cacheName>.redis.cache.windows.net:6380,password=...`).
56-
- First attempts to resolve the connection string from the "ConnectionStrings" settings, and if not there, will look through the other appsettings for the string.
57-
- `Channel`: name of the pubsub channel that the trigger should listen to.
33+
- `ConnectionStringSetting`: Name of the setting in the appsettings that holds the to the Redis cache connection string (eg `<cacheName>.redis.cache.windows.net:6380,password=...`).
34+
- `Channel`: pubsub channel that the trigger should listen to.
5835
- Supports channel patterns.
5936
- This field can be resolved using `INameResolver`.
6037

6138
#### Avaiable Output Types
6239
- [`StackExchange.Redis.ChannelMessage`](https://github.com/StackExchange/StackExchange.Redis/blob/main/src/StackExchange.Redis/ChannelMessageQueue.cs): The value returned by `StackExchange.Redis`.
63-
- [`StackExchange.Redis.RedisValue`](https://github.com/StackExchange/StackExchange.Redis/blob/main/src/StackExchange.Redis/RedisValue.cs),`string`,`byte[]`,`ReadOnlyMemory<byte>`: The message from the channel.
40+
- [`StackExchange.Redis.RedisValue`](https://github.com/StackExchange/StackExchange.Redis/blob/main/src/StackExchange.Redis/RedisValue.cs), `string`, `byte[]`, `ReadOnlyMemory<byte>`: The message from the channel.
6441
- `Custom`: The trigger uses Json.NET serialization to map the message from the channel from a `string` into a custom type.
6542

6643
#### Sample
67-
The following sample listens to the channel `pubsubTest`. More samples can be found in the [samples](samples/RedisSamples.cs) or in the [integration tests](test/Integration/RedisPubSubTriggerTestFunctions.cs).
44+
The following sample listens to the channel `pubsubTest`.
45+
More samples can be found in the [samples](samples/dotnet/RedisSamples.cs) or in the [integration tests](test/dotnet/Integration//RedisPubSubTriggerTestFunctions.cs).
6846
```c#
6947
[FunctionName(nameof(PubSubTrigger))]
7048
public static void PubSubTrigger(
71-
[RedisPubSubTrigger("redisConnectionStringSetting", "pubsubTest")] string message,
49+
[RedisPubSubTrigger("Redis", "pubsubTest")] string message,
7250
ILogger logger)
7351
{
7452
logger.LogInformation($"The message broadcast to channel pubsubTest: '{message}'");
@@ -77,78 +55,77 @@ public static void PubSubTrigger(
7755

7856

7957
### `RedisListTrigger`
80-
The `RedisListTrigger` pops elements from a list and surfaces those elements to the function. The trigger polls Redis at a configurable fixed interval, and uses [`LPOP`](https://redis.io/commands/lpop/)/[`RPOP`](https://redis.io/commands/rpop/)/[`LMPOP`](https://redis.io/commands/lmpop/) to pop elements from the lists.
58+
The `RedisListTrigger` pops entries from a list and surfaces those entries to the function. The trigger polls Redis at a configurable fixed interval, and uses [`LPOP`](https://redis.io/commands/lpop/)/[`RPOP`](https://redis.io/commands/rpop/) to pop entries from the lists.
8159

8260
#### Inputs
83-
- `ConnectionStringSetting`: Name of the setting in the appsettings that holds the to the redis cache connection string (eg `<cacheName>.redis.cache.windows.net:6380,password=...`).
61+
- `ConnectionStringSetting`: Name of the setting in the appsettings that holds the to the Redis cache connection string (eg `<cacheName>.redis.cache.windows.net:6380,password=...`).
8462
- `Key`: Key to read from.
8563
- This field can be resolved using `INameResolver`.
86-
- (optional) `PollingIntervalInMs`: How often to poll Redis in milliseconds.
87-
- Default: 1000
88-
- (optional) `MessagesPerWorker`: How many messages each functions worker "should" process. Used to determine how many workers the function should scale to.
89-
- Default: 100
90-
- (optional) `Count`: Number of elements to pull from Redis at one time.
91-
- Default: 10
64+
- `PollingIntervalInMs`: How often to poll Redis in milliseconds.
65+
- Default: `1000`
66+
- `MessagesPerWorker`: How many messages each functions instance "should" process. Used to determine how many instances the function should scale to.
67+
- Default: `100`
68+
- `Count`: Number of entries to pop from Redis at one time. These are processed in parallel.
69+
- Default: `10`
9270
- Only supported on Redis 6.2+ using the `COUNT` argument in [`LPOP`](https://redis.io/commands/lpop/)/[`RPOP`](https://redis.io/commands/rpop/).
93-
- (optional) `ListPopFromBeginning`: determines whether to pop elements from the beginning using [`LPOP`](https://redis.io/commands/lpop/) or to pop elements from the end using [`RPOP`](https://redis.io/commands/rpop/).
94-
- Default: true
71+
- `ListPopFromBeginning`: determines whether to pop entries from the beginning using [`LPOP`](https://redis.io/commands/lpop/) or to pop entries from the end using [`RPOP`](https://redis.io/commands/rpop/).
72+
- Default: `true`
9573

9674
#### Avaiable Output Types
97-
- [`StackExchange.Redis.RedisValue`](https://github.com/StackExchange/StackExchange.Redis/blob/main/src/StackExchange.Redis/RedisValue.cs),`string`,`byte[]`,`ReadOnlyMemory<byte>`: The entry from the list.
75+
- [`StackExchange.Redis.RedisValue`](https://github.com/StackExchange/StackExchange.Redis/blob/main/src/StackExchange.Redis/RedisValue.cs), `string`, `byte[]`, `ReadOnlyMemory<byte>`: The entry from the list.
9876
- `Custom`: The trigger uses Json.NET serialization to map the entry from the list from a `string` into a custom type.
9977

10078
#### Sample
101-
The following sample polls the key `listTest` at a Redis instance defined in _local.settings.json_ at the key `redisConnectionStringSetting`.
79+
The following sample polls the key `listTest`.
80+
More samples can be found in the [samples](samples/dotnet/RedisSamples.cs) or in the [integration tests](test/dotnet/Integration/RedisListTriggerTestFunctions.cs.cs).
10281
```c#
10382
[FunctionName(nameof(ListsTrigger))]
10483
public static void ListsTrigger(
105-
[RedisListTrigger("redisConnectionStringSetting", "listTest")] string entry,
84+
[RedisListTrigger("Redis", "listTest")] string entry,
10685
ILogger logger)
10786
{
10887
logger.LogInformation($"The entry pushed to the list listTest: '{entry}'");
10988
}
11089
```
11190

11291
### `RedisStreamTrigger`
113-
The `RedisStreamTrigger` reads elements from a stream and surfaces those elements to the function.
114-
The trigger polls Redis at a configurable fixed interval, and uses [`XREADGROUP`](https://redis.io/commands/xreadgroup/) to read elements from the stream.
115-
The consumer group for all function workers will be the ID of the function (eg `Microsoft.Azure.WebJobs.Extensions.Redis.Samples.RedisSamples.StreamTrigger` for the [StreamTrigger sample](samples/RedisSamples.cs)).
116-
Each functions worker creates a new random GUID to use as its consumer name within the group to ensure that scaled out instances of the function will not read the same messages from the stream.
92+
The `RedisStreamTrigger` reads entries from a stream and surfaces those entries to the function.
93+
The trigger polls Redis at a configurable fixed interval, and uses [`XREADGROUP`](https://redis.io/commands/xreadgroup/) to read entries from the stream.
94+
The consumer group for all function instances will be the ID of the function (eg `Microsoft.Azure.WebJobs.Extensions.Redis.Samples.RedisSamples.StreamTrigger` for the [StreamTrigger sample](samples/dotnet/RedisSamples.cs)).
95+
Each functions instance creates a new random GUID to use as its consumer name within the group to ensure that scaled out instances of the function will not read the same messages from the stream.
11796

11897
#### Inputs
119-
- `ConnectionStringSetting`: Name of the setting in the appsettings that holds the to the redis cache connection string (eg `<cacheName>.redis.cache.windows.net:6380,password=...`).
98+
- `ConnectionStringSetting`: Name of the setting in the appsettings that holds the to the Redis cache connection string (eg `<cacheName>.redis.cache.windows.net:6380,password=...`).
12099
- `Key`: Key to read from.
121100
- This field can be resolved using `INameResolver`.
122-
- (optional) `PollingIntervalInMs`: How often to poll Redis in milliseconds.
123-
- Default: 1000
124-
- (optional) `MessagesPerWorker`: How many messages each functions worker "should" process. Used to determine how many workers the function should scale to.
125-
- Default: 100
126-
- (optional) `Count`: Number of elements to pull from Redis at one time.
127-
- Default: 10
128-
- (optional) `DeleteAfterProcess`: If the listener will delete the stream entries after the function runs.
129-
- Default: false
101+
- `PollingIntervalInMs`: How often to poll Redis in milliseconds.
102+
- Default: `1000`
103+
- `MessagesPerWorker`: How many messages each functions instance "should" process. Used to determine how many instances the function should scale to.
104+
- Default: `100`
105+
- `Count`: Number of entries to read from Redis at one time. These are processed in parallel.
106+
- Default: `10`
107+
- `DeleteAfterProcess`: Whether to delete the stream entries after the function has run.
108+
- Default: `false`
130109

131110
#### Avaiable Output Types
132111
- [`StackExchange.Redis.StreamEntry`](https://github.com/StackExchange/StackExchange.Redis/blob/main/src/StackExchange.Redis/APITypes/StreamEntry.cs): The value returned by `StackExchange.Redis`.
133-
- `NameValueEntry[]`: The values contained within the entry as the underlying `StackExchange.Redis` type.
134-
- `Dictionary<string, string>`: The values contained within the entry as a Dictionary.
112+
- `StackExchange.Redis.NameValueEntry[]`, `Dictionary<string, string>`: The values contained within the entry.
135113
- `string`, `byte[]`, `ReadOnlyMemory<byte>`: The stream entry serialized as JSON (UTF-8 encoded for byte types) in the following format:
136114
```
137115
{"Id":"1658354934941-0","Values":{"field1":"value1","field2":"value2","field3":"value3"}}
138116
```
139-
- `Custom`: The trigger uses Json.NET serialization to map the values contained within the entry into the custom type.
140-
This is done by first turning the values within the stream into a Dictionary, and then deserializing that Dictionary into the custom type.
117+
- `Custom`: The trigger uses Json.NET serialization to map the values contained within the entry from a `string` into a custom type.
141118
142119
#### Sample
143-
The following sample polls the key `streamTest` at a Redis instance defined in _local.settings.json_ at the key `redisConnectionStringSetting`.
144-
More samples can be found in the [samples](samples/RedisSamples.cs) or in the [integration tests](test/Integration/RedisStreamTriggerTestFunctions.cs).
120+
The following sample polls the key `streamTest`.
121+
More samples can be found in the [samples](samples/dotnet/RedisSamples.cs) or in the [integration tests](test/dotnet/Integration/RedisStreamTriggerTestFunctions.cs).
145122
```c#
146123
[FunctionName(nameof(StreamsTrigger))]
147124
public static void StreamsTrigger(
148-
[RedisStreamTrigger("redisConnectionStringSetting", "streamTest")] string entry,
125+
[RedisStreamTrigger("Redis", "streamTest")] string entry,
149126
ILogger logger)
150127
{
151-
logger.LogInformation(entry);
128+
logger.LogInformation($"The entry pushed to the list listTest: '{entry}'");
152129
}
153130
```
154131

‎SECURITY.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@
44

55
Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
66

7-
If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below.
7+
If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below.
88

99
## Reporting Security Issues
1010

1111
**Please do not report security vulnerabilities through public GitHub issues.**
1212

1313
Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).
1414

15-
If you prefer to submit without logging in, send email to [[email protected]](mailto:[email protected]). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
15+
If you prefer to submit without logging in, send email to [[email protected]](mailto:[email protected]). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/msrc/pgp-key-msrc).
1616

1717
You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
1818

@@ -36,6 +36,6 @@ We prefer all communications to be in English.
3636

3737
## Policy
3838

39-
Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd).
39+
Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/msrc/cvd).
4040

4141
<!-- END MICROSOFT SECURITY.MD BLOCK -->

0 commit comments

Comments
 (0)