Skip to content

Commit

Permalink
Adds csharp client SDK documentation for counts and lists
Browse files Browse the repository at this point in the history
  • Loading branch information
@igooch
igooch committed Apr 1, 2024
1 parent 8751923 commit e70f45d
Showing 1 changed file with 182 additions and 33 deletions.
215 changes: 182 additions & 33 deletions site/content/en/docs/Guides/Client SDKs/csharp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,35 +14,35 @@ Check the [Client SDK Documentation]({{< relref "_index.md" >}}) for more detail

| Area | Action | Implemented |
|-----------------|---------------------|-------------|
| Lifecycle | Ready | ✔️ |
| Lifecycle | Health | ✔️ |
| Lifecycle | Reserve | ✔️ |
| Lifecycle | Allocate | ✔️ |
| Lifecycle | Shutdown | ✔️ |
| Configuration | GetGameServer | ✔️ |
| Configuration | WatchGameServer | ✔️ |
| Metadata | SetAnnotation | ✔️ |
| Metadata | SetLabel | ✔️ |
| Counters | GetCounterCount | ❌ |
| Counters | SetCounterCount | ❌ |
| Counters | IncrementCounter | ❌ |
| Counters | DecrementCounter | ❌ |
| Counters | SetCounterCapacity | ❌ |
| Counters | GetCounterCapacity | ❌ |
| Lists | AppendListValue | ❌ |
| Lists | DeleteListValue | ❌ |
| Lists | SetListCapacity | ❌ |
| Lists | GetListCapacity | ❌ |
| Lists | ListContains | ❌ |
| Lists | GetListLength | ❌ |
| Lists | GetListValues | ❌ |
| Player Tracking | GetConnectedPlayers | ✔️ |
| Player Tracking | GetPlayerCapacity | ✔️ |
| Player Tracking | GetPlayerCount | ✔️ |
| Player Tracking | IsPlayerConnected | ✔️ |
| Player Tracking | PlayerConnect | ✔️ |
| Player Tracking | PlayerDisconnect | ✔️ |
| Player Tracking | SetPlayerCapacity | ✔️ |
| Lifecycle | Ready | ✔️ |
| Lifecycle | Health | ✔️ |
| Lifecycle | Reserve | ✔️ |
| Lifecycle | Allocate | ✔️ |
| Lifecycle | Shutdown | ✔️ |
| Configuration | GetGameServer | ✔️ |
| Configuration | WatchGameServer | ✔️ |
| Metadata | SetAnnotation | ✔️ |
| Metadata | SetLabel | ✔️ |
| Counters | GetCounterCount | ✔️ |
| Counters | SetCounterCount | ✔️ |
| Counters | IncrementCounter | ✔️ |
| Counters | DecrementCounter | ✔️ |
| Counters | SetCounterCapacity | ✔️ |
| Counters | GetCounterCapacity | ✔️ |
| Lists | AppendListValue | ✔️ |
| Lists | DeleteListValue | ✔️ |
| Lists | SetListCapacity | ✔️ |
| Lists | GetListCapacity | ✔️ |
| Lists | ListContains | ✔️ |
| Lists | GetListLength | ✔️ |
| Lists | GetListValues | ✔️ |
| Player Tracking | GetConnectedPlayers | ✔️ |
| Player Tracking | GetPlayerCapacity | ✔️ |
| Player Tracking | GetPlayerCount | ✔️ |
| Player Tracking | IsPlayerConnected | ✔️ |
| Player Tracking | PlayerConnect | ✔️ |
| Player Tracking | PlayerDisconnect | ✔️ |
| Player Tracking | SetPlayerCapacity | ✔️ |

## Download

Expand Down Expand Up @@ -112,7 +112,7 @@ var gameserver = await agones.GetGameServerAsync();

### Reserve

To mark the GameServer as [Reserved]({{< relref "_index.md#reserveseconds" >}}) for a duration call
To mark the GameServer as [Reserved]({{< relref "_index.md#reserveseconds" >}}) for a duration call
`ReserveAsync(long duration)`.

```csharp
Expand All @@ -133,9 +133,9 @@ Similarly `SetAnnotation(string key, string value)` and `SetLabel(string key, st

### WatchGameServer

To watch when
To watch when
[the backing `GameServer` configuration changes]({{< relref "_index.md#watchgameserverfunctiongameserver" >}})
call `WatchGameServer(callback)`, where the delegate function `callback` of type `Action<GameServer>` will be executed every time the `GameServer`
call `WatchGameServer(callback)`, where the delegate function `callback` of type `Action<GameServer>` will be executed every time the `GameServer`
configuration changes.
This process is non-blocking internally.

Expand Down Expand Up @@ -176,7 +176,7 @@ var status = await agones.Alpha().SetPlayerCapacityAsync(capacity);

### Alpha: GetPlayerCapacity

This function retrieves the current player capacity `GameServer.Status.Players.Capacity`.
This function retrieves the current player capacity `GameServer.Status.Players.Capacity`.
This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.

```csharp
Expand All @@ -201,6 +201,155 @@ var playerId = "player1";
bool isConnected = await agones.Alpha().IsPlayerConnectedAsync(playerId);
```

## Counters

### Alpha: GetCounterCount

Returns the Count for a Counter, given the Counter's key (name). Will error if the key was not
predefined in the GameServer resource on creation.

```csharp
string key = "rooms";
long count = await agones.Alpha().GetCounterCountAsync(key);
```

### Alpha: SetCounterCount

Sets a count to the given value. Use with care, as this will overwrite any previous invocations’ value.
Cannot be greater than Capacity.

```csharp
string key = "rooms";
long amount = 0;
await agones.Alpha().SetCounterCountAsync(key, amount);
```

### Alpha: IncrementCounter

Increases a counter by the given nonnegative integer amount. Will execute the increment operation
against the current CRD value. Will max at max(int64). Will error if the key was not predefined in
the GameServer resource on creation. Errors if the count is at the current capacity (to the latest
knowledge of the SDK), and no increment will occur.

Note: A potential race condition here is that if count values are set from both the SDK and through
the K8s API (Allocation or otherwise), since the SDK append operation back to the CRD value is
batched asynchronous any value incremented past the capacity will be silently truncated.

```csharp
string key = "rooms";
long amount = 1;
await agones.Alpha().IncrementCounterAsync(key, amount);
```

### Alpha: DecrementCounter

Decreases the current count by the given nonnegative integer amount. The Counter Will not go below 0.
Will execute the decrement operation against the current CRD value. Errors if the count is at 0 (to
the latest knowledge of the SDK), and no decrement will occur.

```csharp
string key = "rooms";
long amount = 2;
await agones.Alpha().DecrementCounterAsync(key, amount);
```

### Alpha: SetCounterCapacity

Sets the capacity for the given Counter. A capacity of 0 is no capacity.

```csharp
string key = "rooms";
long amount = 0;
await agones.Alpha().SetCounterCapacityAsync(key, amount);
```

### Alpha: GetCounterCapacity

Returns the Capacity for a Counter, given the Counter's key (name). Will error if the key was not
predefined in the GameServer resource on creation.

```csharp
string key = "rooms";
long count = await agones.Alpha().GetCounterCapacityAsync(key);
```
## Lists

### Alpha: AppendListValue

Appends a string to a List's values list, given the List's key (name) and the string value. Will
error if the string already exists in the list. Will error if the key was not predefined in the
GameServer resource on creation.

```csharp
string key = "players";
string value = "player1";
await agones.Alpha().AppendListValueAsync(key, value);
```

### Alpha: DeleteListValue

DeleteListValue removes a string from a List's values list, given the List's key (name) and the
string value. Will error if the string does not exist in the list. Will error if the key was not
predefined in the GameServer resource on creation.

```csharp
string key = "players";
string value = "player2";
await agones.Alpha().DeleteListValueAsync(key, value);
```

### Alpha: SetListCapacity

Sets the capacity for a given list. Capacity must be between 0 and 1000. Will error if the key was
not predefined in the GameServer resource on creation.

```csharp
string key = "players";
long amount = 1000;
await agones.Alpha().SetListCapacityAsync(key, amount);
```

### Alpha: GetListCapacity

Returns the Capacity for a List, given the List's key (name). Will error if the key was not
predefined in the GameServer resource on creation.

```csharp
string key = "players";
long amount = await agones.Alpha().GetListCapacityAsync(key);
```

### Alpha: ListContains

Returns if a string exists in a List's values list, given the List's key (name) and the string value.
Search is case-sensitive. Will error if the key was not predefined in the GameServer resource on creation.

```csharp
string key = "players";
string value = "player3";
bool contains = await agones.Alpha().ListContainsAsync(key, value);
```

### Alpha: GetListLength

GetListLength returns the length of the Values list for a List, given the List's key (name). Will
error if the key was not predefined in the GameServer resource on creation.

```csharp
string key = "players";
int listLength = await agones.Alpha().GetListLengthAsync(key);
```

### Alpha: GetListValues

Returns the <IList<string>> Values for a List, given the List's key (name). Will error if the key
was not predefined in the GameServer resource on creation.

```csharp
string key = "players";
List<string> values = await agones.Alpha().GetListValuesAsync(key);
```

## Remarks
- All requests other than `ConnectAsync` will wait for up to 15 seconds before giving up, time to wait can also be set in the constructor.
- Default host & port are `localhost:9357`
Expand Down

0 comments on commit e70f45d

Please sign in to comment.