Skip to content

Commit 1dbb7ed

Browse files
CopilotReubenBond
Copilot
and
ReubenBond
committed
Add READMEs for all serialization packages
Co-authored-by: ReubenBond <[email protected]>
1 parent 1e5a39d commit 1dbb7ed

File tree

12 files changed

+628
-5
lines changed

12 files changed

+628
-5
lines changed

‎src/Orleans.Serialization.FSharp/Orleans.Serialization.FSharp.csproj

Lines changed: 5 additions & 1 deletion
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.Serialization.FSharp</PackageId>
56
<TargetFrameworks>$(DefaultTargetFrameworks);netstandard2.1</TargetFrameworks>
67
<PackageDescription>F# core type support for Orleans.Serialization</PackageDescription>
@@ -13,4 +14,7 @@
1314
<ProjectReference Include="..\Orleans.Serialization\Orleans.Serialization.csproj" />
1415
</ItemGroup>
1516

16-
</Project>
17+
</Project>
18+
<ItemGroup>
19+
<None Include="README.md" Pack="true" PackagePath="\" />
20+
</ItemGroup>

‎src/Orleans.Serialization.FSharp/README.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Microsoft Orleans Serialization for F#
2+
3+
## Introduction
4+
Microsoft Orleans Serialization for F# provides serialization support for F# specific types in Microsoft Orleans. This package enables seamless integration of F# types like discriminated unions, records, and other F# specific constructs with Orleans serialization system.
5+
6+
## Getting Started
7+
To use this package, install it via NuGet:
8+
9+
```shell
10+
dotnet add package Microsoft.Orleans.Serialization.FSharp
11+
```
12+
13+
## Example - Configuring F# Serialization
14+
```fsharp
15+
open Microsoft.Extensions.Hosting
16+
open Orleans.Hosting
17+
18+
let builder =
19+
HostBuilder()
20+
.UseOrleans(fun siloBuilder ->
21+
siloBuilder
22+
.UseLocalhostClustering()
23+
// F# serialization is automatically configured when the package is referenced
24+
|> ignore)
25+
26+
// Run the host
27+
builder.RunConsoleAsync() |> Async.AwaitTask |> ignore
28+
```
29+
30+
## Example - Using F# Types with Orleans
31+
```fsharp
32+
// Define F# discriminated union and record types
33+
type UserRole =
34+
| Admin
35+
| Moderator
36+
| User of level:int
37+
38+
type UserRecord = {
39+
Id: string
40+
Name: string
41+
Role: UserRole
42+
Tags: string list
43+
}
44+
45+
// Define a grain interface
46+
type IFSharpGrain =
47+
inherit Orleans.IGrainWithStringKey
48+
abstract member GetUser: unit -> Task<UserRecord>
49+
abstract member UpdateUser: UserRecord -> Task
50+
51+
// Grain implementation
52+
type FSharpGrain() =
53+
inherit Orleans.Grain()
54+
let mutable userData = Unchecked.defaultof<UserRecord>
55+
56+
interface IFSharpGrain with
57+
member this.GetUser() =
58+
Task.FromResult(userData)
59+
60+
member this.UpdateUser(user) =
61+
userData <- user
62+
Task.CompletedTask
63+
```
64+
65+
## Example - Client Code Using F# Grain
66+
```fsharp
67+
// Client-side code
68+
let client = clientBuilder.Build()
69+
let grain = client.GetGrain<IFSharpGrain>("user1")
70+
71+
// Create an F# record with discriminated union
72+
let user = {
73+
Id = "user1"
74+
Name = "F# User"
75+
Role = UserRole.Admin
76+
Tags = ["functional"; "programming"]
77+
}
78+
79+
// Call the grain with F# types
80+
grain.UpdateUser(user) |> Async.AwaitTask |> ignore
81+
let retrievedUser = grain.GetUser() |> Async.AwaitTask |> Async.RunSynchronously
82+
```
83+
84+
## Documentation
85+
For more comprehensive documentation, please refer to:
86+
- [Microsoft Orleans Documentation](https://docs.microsoft.com/dotnet/orleans/)
87+
- [Orleans Serialization](https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/serialization)
88+
- [F# Documentation](https://learn.microsoft.com/en-us/dotnet/fsharp/)
89+
90+
## Feedback & Contributing
91+
- If you have any issues or would like to provide feedback, please [open an issue on GitHub](https://github.com/dotnet/orleans/issues)
92+
- Join our community on [Discord](https://aka.ms/orleans-discord)
93+
- Follow the [@msftorleans](https://twitter.com/msftorleans) Twitter account for Orleans announcements
94+
- Contributions are welcome! Please review our [contribution guidelines](https://github.com/dotnet/orleans/blob/main/CONTRIBUTING.md)
95+
- This project is licensed under the [MIT license](https://github.com/dotnet/orleans/blob/main/LICENSE)

‎src/Orleans.Serialization.MessagePack/Orleans.Serialization.MessagePack.csproj

Lines changed: 5 additions & 1 deletion
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.Serialization.MessagePack</PackageId>
56
<TargetFrameworks>$(DefaultTargetFrameworks);netstandard2.1</TargetFrameworks>
67
<PackageDescription>MessagePack integration for Orleans.Serialization</PackageDescription>
@@ -15,4 +16,7 @@
1516
<ProjectReference Include="..\Orleans.Serialization\Orleans.Serialization.csproj" />
1617
</ItemGroup>
1718

18-
</Project>
19+
</Project>
20+
<ItemGroup>
21+
<None Include="README.md" Pack="true" PackagePath="\" />
22+
</ItemGroup>

‎src/Orleans.Serialization.MessagePack/README.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Microsoft Orleans Serialization for MessagePack
2+
3+
## Introduction
4+
Microsoft Orleans Serialization for MessagePack provides MessagePack serialization support for Microsoft Orleans using the MessagePack format. This high-performance binary serialization format is ideal for scenarios requiring efficient serialization and deserialization.
5+
6+
## Getting Started
7+
To use this package, install it via NuGet:
8+
9+
```shell
10+
dotnet add package Microsoft.Orleans.Serialization.MessagePack
11+
```
12+
13+
## Example - Configuring MessagePack Serialization
14+
```csharp
15+
using Microsoft.Extensions.DependencyInjection;
16+
using Microsoft.Extensions.Hosting;
17+
using Orleans.Hosting;
18+
using Orleans.Serialization;
19+
20+
var builder = new HostBuilder()
21+
.UseOrleans(siloBuilder =>
22+
{
23+
siloBuilder
24+
.UseLocalhostClustering()
25+
// Configure MessagePack as a serializer
26+
.AddMessagePackSerializer();
27+
});
28+
29+
// Run the host
30+
await builder.RunConsoleAsync();
31+
```
32+
33+
## Example - Using MessagePack with a Custom Type
34+
```csharp
35+
using Orleans;
36+
using Orleans.Serialization.Cloning;
37+
using Orleans.Serialization.Codecs;
38+
using Orleans.Serialization.Configuration;
39+
using Orleans.Serialization.Serializers;
40+
using MessagePack;
41+
42+
// Define a class with MessagePack attributes
43+
[MessagePackObject]
44+
public class MyMessagePackClass
45+
{
46+
[Key(0)]
47+
public string Name { get; set; }
48+
49+
[Key(1)]
50+
public int Age { get; set; }
51+
52+
[Key(2)]
53+
public List<string> Tags { get; set; }
54+
}
55+
56+
// You can use it directly in your grain interfaces and implementation
57+
public interface IMyGrain : IGrainWithStringKey
58+
{
59+
Task<MyMessagePackClass> GetData();
60+
Task SetData(MyMessagePackClass data);
61+
}
62+
63+
public class MyGrain : Grain, IMyGrain
64+
{
65+
private MyMessagePackClass _data;
66+
67+
public Task<MyMessagePackClass> GetData()
68+
{
69+
return Task.FromResult(_data);
70+
}
71+
72+
public Task SetData(MyMessagePackClass data)
73+
{
74+
_data = data;
75+
return Task.CompletedTask;
76+
}
77+
}
78+
```
79+
80+
## Documentation
81+
For more comprehensive documentation, please refer to:
82+
- [Microsoft Orleans Documentation](https://docs.microsoft.com/dotnet/orleans/)
83+
- [Orleans Serialization](https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/serialization)
84+
- [MessagePack for C#](https://github.com/neuecc/MessagePack-CSharp)
85+
86+
## Feedback & Contributing
87+
- If you have any issues or would like to provide feedback, please [open an issue on GitHub](https://github.com/dotnet/orleans/issues)
88+
- Join our community on [Discord](https://aka.ms/orleans-discord)
89+
- Follow the [@msftorleans](https://twitter.com/msftorleans) Twitter account for Orleans announcements
90+
- Contributions are welcome! Please review our [contribution guidelines](https://github.com/dotnet/orleans/blob/main/CONTRIBUTING.md)
91+
- This project is licensed under the [MIT license](https://github.com/dotnet/orleans/blob/main/LICENSE)

‎src/Orleans.Serialization.NewtonsoftJson/Orleans.Serialization.NewtonsoftJson.csproj

Lines changed: 5 additions & 1 deletion
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.Serialization.NewtonsoftJson</PackageId>
56
<TargetFrameworks>$(DefaultTargetFrameworks);netstandard2.1</TargetFrameworks>
67
<PackageDescription>Newtonsoft.Json integration for Orleans.Serialization</PackageDescription>
@@ -16,4 +17,7 @@
1617
<ProjectReference Include="..\Orleans.Serialization\Orleans.Serialization.csproj" />
1718
</ItemGroup>
1819

19-
</Project>
20+
</Project>
21+
<ItemGroup>
22+
<None Include="README.md" Pack="true" PackagePath="\" />
23+
</ItemGroup>

‎src/Orleans.Serialization.NewtonsoftJson/README.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Microsoft Orleans Serialization for Newtonsoft.Json
2+
3+
## Introduction
4+
Microsoft Orleans Serialization for Newtonsoft.Json provides JSON serialization support for Microsoft Orleans using the popular Newtonsoft.Json library. This allows you to use the comprehensive JSON features of Newtonsoft.Json within your Orleans application.
5+
6+
## Getting Started
7+
To use this package, install it via NuGet:
8+
9+
```shell
10+
dotnet add package Microsoft.Orleans.Serialization.NewtonsoftJson
11+
```
12+
13+
## Example - Configuring Newtonsoft.Json Serialization
14+
```csharp
15+
using Microsoft.Extensions.DependencyInjection;
16+
using Microsoft.Extensions.Hosting;
17+
using Orleans.Hosting;
18+
using Orleans.Serialization;
19+
20+
var builder = new HostBuilder()
21+
.UseOrleans(siloBuilder =>
22+
{
23+
siloBuilder
24+
.UseLocalhostClustering()
25+
// Configure Newtonsoft.Json as a serializer
26+
.AddNewtonsoftJsonSerializer();
27+
});
28+
29+
// Run the host
30+
await builder.RunConsoleAsync();
31+
```
32+
33+
## Example - Using Newtonsoft.Json with a Custom Type
34+
```csharp
35+
using Orleans;
36+
using Newtonsoft.Json;
37+
38+
// Define a class with Newtonsoft.Json attributes
39+
public class MyJsonClass
40+
{
41+
[JsonProperty("full_name")]
42+
public string Name { get; set; }
43+
44+
[JsonProperty("age")]
45+
public int Age { get; set; }
46+
47+
[JsonProperty("tags")]
48+
public List<string> Tags { get; set; }
49+
50+
[JsonIgnore]
51+
public string SecretData { get; set; }
52+
}
53+
54+
// You can use it directly in your grain interfaces and implementation
55+
public interface IMyGrain : IGrainWithStringKey
56+
{
57+
Task<MyJsonClass> GetData();
58+
Task SetData(MyJsonClass data);
59+
}
60+
61+
public class MyGrain : Grain, IMyGrain
62+
{
63+
private MyJsonClass _data;
64+
65+
public Task<MyJsonClass> GetData()
66+
{
67+
return Task.FromResult(_data);
68+
}
69+
70+
public Task SetData(MyJsonClass data)
71+
{
72+
_data = data;
73+
return Task.CompletedTask;
74+
}
75+
}
76+
```
77+
78+
## Documentation
79+
For more comprehensive documentation, please refer to:
80+
- [Microsoft Orleans Documentation](https://docs.microsoft.com/dotnet/orleans/)
81+
- [Orleans Serialization](https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/serialization)
82+
- [Newtonsoft.Json Documentation](https://www.newtonsoft.com/json/help/html/Introduction.htm)
83+
84+
## Feedback & Contributing
85+
- If you have any issues or would like to provide feedback, please [open an issue on GitHub](https://github.com/dotnet/orleans/issues)
86+
- Join our community on [Discord](https://aka.ms/orleans-discord)
87+
- Follow the [@msftorleans](https://twitter.com/msftorleans) Twitter account for Orleans announcements
88+
- Contributions are welcome! Please review our [contribution guidelines](https://github.com/dotnet/orleans/blob/main/CONTRIBUTING.md)
89+
- This project is licensed under the [MIT license](https://github.com/dotnet/orleans/blob/main/LICENSE)

‎src/Orleans.Serialization.SystemTextJson/Orleans.Serialization.SystemTextJson.csproj

Lines changed: 5 additions & 1 deletion
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.Serialization.SystemTextJson</PackageId>
56
<TargetFrameworks>$(DefaultTargetFrameworks);netstandard2.1</TargetFrameworks>
67
<PackageDescription>System.Text.Json integration for Orleans.Serialization</PackageDescription>
@@ -12,4 +13,7 @@
1213
<ProjectReference Include="..\Orleans.Serialization\Orleans.Serialization.csproj" />
1314
</ItemGroup>
1415

15-
</Project>
16+
</Project>
17+
<ItemGroup>
18+
<None Include="README.md" Pack="true" PackagePath="\" />
19+
</ItemGroup>

0 commit comments

Comments
 (0)