Skip to content

Commit 1e5a39d

Browse files
CopilotReubenBond
Copilot
and
ReubenBond
committed
Add READMEs for remaining AdoNet packages
Co-authored-by: ReubenBond <[email protected]>
1 parent 394ed43 commit 1e5a39d

File tree

4 files changed

+233
-0
lines changed

4 files changed

+233
-0
lines changed

‎src/AdoNet/Orleans.Reminders.AdoNet/Orleans.Reminders.AdoNet.csproj‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
<Project Sdk="Microsoft.NET.Sdk">
22
<PropertyGroup>
3+
<PackageReadmeFile>README.md</PackageReadmeFile>
34
<PackageId>Microsoft.Orleans.Reminders.AdoNet</PackageId>
45
<Title>Microsoft Orleans ADO.NET Reminders Provider</Title>
56
<Description>Microsoft Orleans reminders provider backed by ADO.NET</Description>
@@ -8,6 +9,7 @@
89
</PropertyGroup>
910

1011
<PropertyGroup>
12+
<PackageReadmeFile>README.md</PackageReadmeFile>
1113
<AssemblyName>Orleans.Reminders.AdoNet</AssemblyName>
1214
<RootNamespace>Orleans.Reminders.AdoNet</RootNamespace>
1315
<DefineConstants>$(DefineConstants);REMINDERS_ADONET</DefineConstants>
@@ -22,3 +24,7 @@
2224
<ProjectReference Include="$(SourceRoot)src\Orleans.Reminders\Orleans.Reminders.csproj" />
2325
</ItemGroup>
2426
</Project>
27+
28+
<ItemGroup>
29+
<None Include="README.md" Pack="true" PackagePath="\" />
30+
</ItemGroup>

‎src/AdoNet/Orleans.Reminders.AdoNet/README.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Microsoft Orleans Reminders for ADO.NET
2+
3+
## Introduction
4+
Microsoft Orleans Reminders for ADO.NET provides persistence for Orleans reminders using ADO.NET-compatible databases (SQL Server, MySQL, PostgreSQL, etc.). This allows your Orleans applications to schedule persistent reminders that will be triggered even after silo restarts or grain deactivation.
5+
6+
## Getting Started
7+
To use this package, install it via NuGet:
8+
9+
```shell
10+
dotnet add package Microsoft.Orleans.Reminders.AdoNet
11+
```
12+
13+
You will also need to install the appropriate ADO.NET provider for your database:
14+
15+
```shell
16+
# For SQL Server
17+
dotnet add package System.Data.SqlClient
18+
19+
# For MySQL
20+
dotnet add package MySql.Data
21+
22+
# For PostgreSQL
23+
dotnet add package Npgsql
24+
```
25+
26+
## Example - Configuring ADO.NET Reminders
27+
```csharp
28+
using Microsoft.Extensions.Hosting;
29+
using Orleans.Configuration;
30+
using Orleans.Hosting;
31+
32+
var builder = new HostBuilder()
33+
.UseOrleans(siloBuilder =>
34+
{
35+
siloBuilder
36+
.UseLocalhostClustering()
37+
// Configure ADO.NET as reminder storage
38+
.UseAdoNetReminderService(options =>
39+
{
40+
options.Invariant = "System.Data.SqlClient"; // For SQL Server
41+
options.ConnectionString = "Server=localhost;Database=OrleansReminders;User ID=orleans;******;";
42+
});
43+
});
44+
45+
// Run the host
46+
await builder.RunConsoleAsync();
47+
```
48+
49+
## Example - Using Reminders in a Grain
50+
```csharp
51+
public class ReminderGrain : Grain, IReminderGrain, IRemindable
52+
{
53+
private IDisposable _timer;
54+
private string _reminderName = "MyReminder";
55+
56+
public async Task StartReminder(string reminderName)
57+
{
58+
_reminderName = reminderName;
59+
60+
// Register a persistent reminder
61+
await RegisterOrUpdateReminder(
62+
reminderName,
63+
TimeSpan.FromSeconds(5), // Time to delay before the first tick
64+
TimeSpan.FromSeconds(30)); // Period of the reminder
65+
}
66+
67+
public async Task StopReminder()
68+
{
69+
// Find and unregister the reminder
70+
var reminder = await GetReminder(_reminderName);
71+
if (reminder != null)
72+
{
73+
await UnregisterReminder(reminder);
74+
}
75+
}
76+
77+
public Task ReceiveReminder(string reminderName, TickStatus status)
78+
{
79+
// This method is called when the reminder ticks
80+
Console.WriteLine($"Reminder {reminderName} triggered at {DateTime.UtcNow}. Status: {status}");
81+
return Task.CompletedTask;
82+
}
83+
}
84+
```
85+
86+
## Documentation
87+
For more comprehensive documentation, please refer to:
88+
- [Microsoft Orleans Documentation](https://docs.microsoft.com/dotnet/orleans/)
89+
- [Reminders and Timers](https://learn.microsoft.com/en-us/dotnet/orleans/grains/timers-and-reminders)
90+
- [Reminder Services](https://learn.microsoft.com/en-us/dotnet/orleans/implementation/reminder-services)
91+
- [ADO.NET Database Setup](https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/adonet-configuration)
92+
93+
## Feedback & Contributing
94+
- If you have any issues or would like to provide feedback, please [open an issue on GitHub](https://github.com/dotnet/orleans/issues)
95+
- Join our community on [Discord](https://aka.ms/orleans-discord)
96+
- Follow the [@msftorleans](https://twitter.com/msftorleans) Twitter account for Orleans announcements
97+
- Contributions are welcome! Please review our [contribution guidelines](https://github.com/dotnet/orleans/blob/main/CONTRIBUTING.md)
98+
- This project is licensed under the [MIT license](https://github.com/dotnet/orleans/blob/main/LICENSE)

‎src/AdoNet/Orleans.Streaming.AdoNet/Orleans.Streaming.AdoNet.csproj‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
<Project Sdk="Microsoft.NET.Sdk">
22

33
<PropertyGroup>
4+
<PackageReadmeFile>README.md</PackageReadmeFile>
45
<PackageId>Microsoft.Orleans.Streaming.AdoNet</PackageId>
56
<Title>Microsoft Orleans ADO.NET Streaming Provider</Title>
67
<Description>Microsoft Orleans streaming provider backed by ADO.NET</Description>
@@ -11,6 +12,7 @@
1112
</PropertyGroup>
1213

1314
<PropertyGroup>
15+
<PackageReadmeFile>README.md</PackageReadmeFile>
1416
<AssemblyName>Orleans.Streaming.AdoNet</AssemblyName>
1517
<RootNamespace>Orleans.Streaming.AdoNet</RootNamespace>
1618
<DefineConstants>$(DefineConstants);STREAMING_ADONET</DefineConstants>
@@ -31,3 +33,7 @@
3133
</ItemGroup>
3234

3335
</Project>
36+
37+
<ItemGroup>
38+
<None Include="README.md" Pack="true" PackagePath="\" />
39+
</ItemGroup>

‎src/AdoNet/Orleans.Streaming.AdoNet/README.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Microsoft Orleans Streaming for ADO.NET
2+
3+
## Introduction
4+
Microsoft Orleans Streaming for ADO.NET provides a stream provider implementation for Orleans using ADO.NET-compatible databases (SQL Server, MySQL, PostgreSQL, etc.). This allows for publishing and subscribing to streams of events with relational databases as the underlying infrastructure.
5+
6+
## Getting Started
7+
To use this package, install it via NuGet:
8+
9+
```shell
10+
dotnet add package Microsoft.Orleans.Streaming.AdoNet
11+
```
12+
13+
You will also need to install the appropriate ADO.NET provider for your database:
14+
15+
```shell
16+
# For SQL Server
17+
dotnet add package System.Data.SqlClient
18+
19+
# For MySQL
20+
dotnet add package MySql.Data
21+
22+
# For PostgreSQL
23+
dotnet add package Npgsql
24+
```
25+
26+
## Example - Configuring ADO.NET Streaming
27+
```csharp
28+
using Microsoft.Extensions.Hosting;
29+
using Orleans.Hosting;
30+
using Orleans.Streams;
31+
32+
var builder = new HostBuilder()
33+
.UseOrleans(siloBuilder =>
34+
{
35+
siloBuilder
36+
.UseLocalhostClustering()
37+
// Configure ADO.NET as a stream provider
38+
.AddAdoNetStreams(
39+
name: "AdoNetStreamProvider",
40+
configureOptions: options =>
41+
{
42+
options.Invariant = "System.Data.SqlClient"; // For SQL Server
43+
options.ConnectionString = "Server=localhost;Database=OrleansStreaming;User ID=orleans;******;";
44+
});
45+
});
46+
47+
// Run the host
48+
await builder.RunConsoleAsync();
49+
```
50+
51+
## Example - Using ADO.NET Streams in a Grain
52+
```csharp
53+
// Producer grain
54+
public class ProducerGrain : Grain, IProducerGrain
55+
{
56+
private IAsyncStream<string> _stream;
57+
58+
public override Task OnActivateAsync(CancellationToken cancellationToken)
59+
{
60+
// Get a reference to a stream
61+
var streamProvider = GetStreamProvider("AdoNetStreamProvider");
62+
_stream = streamProvider.GetStream<string>(Guid.NewGuid(), "MyStreamNamespace");
63+
64+
return base.OnActivateAsync(cancellationToken);
65+
}
66+
67+
public async Task SendMessage(string message)
68+
{
69+
// Send a message to the stream
70+
await _stream.OnNextAsync(message);
71+
}
72+
}
73+
74+
// Consumer grain
75+
public class ConsumerGrain : Grain, IConsumerGrain, IAsyncObserver<string>
76+
{
77+
private StreamSubscriptionHandle<string> _subscription;
78+
79+
public override async Task OnActivateAsync(CancellationToken cancellationToken)
80+
{
81+
// Get a reference to a stream
82+
var streamProvider = GetStreamProvider("AdoNetStreamProvider");
83+
var stream = streamProvider.GetStream<string>(this.GetPrimaryKey(), "MyStreamNamespace");
84+
85+
// Subscribe to the stream
86+
_subscription = await stream.SubscribeAsync(this);
87+
88+
await base.OnActivateAsync(cancellationToken);
89+
}
90+
91+
public Task OnNextAsync(string item, StreamSequenceToken token = null)
92+
{
93+
Console.WriteLine($"Received message: {item}");
94+
return Task.CompletedTask;
95+
}
96+
97+
public Task OnCompletedAsync()
98+
{
99+
Console.WriteLine("Stream completed");
100+
return Task.CompletedTask;
101+
}
102+
103+
public Task OnErrorAsync(Exception ex)
104+
{
105+
Console.WriteLine($"Stream error: {ex.Message}");
106+
return Task.CompletedTask;
107+
}
108+
}
109+
```
110+
111+
## Documentation
112+
For more comprehensive documentation, please refer to:
113+
- [Microsoft Orleans Documentation](https://docs.microsoft.com/dotnet/orleans/)
114+
- [Orleans Streams](https://learn.microsoft.com/en-us/dotnet/orleans/streaming/index)
115+
- [Stream Providers](https://learn.microsoft.com/en-us/dotnet/orleans/streaming/stream-providers)
116+
- [ADO.NET Database Setup](https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/adonet-configuration)
117+
118+
## Feedback & Contributing
119+
- If you have any issues or would like to provide feedback, please [open an issue on GitHub](https://github.com/dotnet/orleans/issues)
120+
- Join our community on [Discord](https://aka.ms/orleans-discord)
121+
- Follow the [@msftorleans](https://twitter.com/msftorleans) Twitter account for Orleans announcements
122+
- Contributions are welcome! Please review our [contribution guidelines](https://github.com/dotnet/orleans/blob/main/CONTRIBUTING.md)
123+
- This project is licensed under the [MIT license](https://github.com/dotnet/orleans/blob/main/LICENSE)

0 commit comments

Comments
 (0)