{"id":29572654,"url":"https://github.com/accelbyte/accelbyte-csharp-modular-sdk","last_synced_at":"2026-05-25T02:12:34.945Z","repository":{"id":208352561,"uuid":"721423389","full_name":"AccelByte/accelbyte-csharp-modular-sdk","owner":"AccelByte","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-02T04:21:52.000Z","size":26386,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-08T14:14:13.795Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AccelByte.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-11-21T03:01:21.000Z","updated_at":"2025-12-02T04:21:06.000Z","dependencies_parsed_at":"2023-12-19T07:17:23.485Z","dependency_job_id":"c5d383bf-b4a0-4903-90c6-462f46a766d3","html_url":"https://github.com/AccelByte/accelbyte-csharp-modular-sdk","commit_stats":null,"previous_names":["accelbyte/accelbyte-csharp-modular-sdk"],"tags_count":430,"template":false,"template_full_name":null,"purl":"pkg:github/AccelByte/accelbyte-csharp-modular-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-csharp-modular-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-csharp-modular-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-csharp-modular-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-csharp-modular-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AccelByte","download_url":"https://codeload.github.com/AccelByte/accelbyte-csharp-modular-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Faccelbyte-csharp-modular-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28608053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-19T05:10:45.145Z","updated_at":"2026-05-25T02:12:34.938Z","avatar_url":"https://github.com/AccelByte.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AccelByte Modular .NET (C#) SDK\n\nA software development kit (SDK) for interacting with AccelByte Gaming Services (AGS) written in C#.\n\nThis is the **modular** AccelByte .NET SDK ([accelbyte-csharp-modular-sdk](https://github.com/AccelByte/accelbyte-csharp-modular-sdk)), the successor to the legacy [accelbyte-csharp-sdk](https://github.com/AccelByte/accelbyte-csharp-sdk) (monolithic SDK).\n\nKey advantages over the monolithic SDK:\n\n- **Selective dependencies** — include only the API packages your project needs, reducing bloat and build times.\n- **Compatibility layer** — migrate from the monolithic SDK incrementally via `AccelByte.Sdk.Api.Compat` without rewriting everything at once.\n\n\u003e **Migrating from the monolithic SDK?** See [MIGRATION.md](MIGRATION.md) for a step-by-step guide.\n\nThis SDK was generated from AGS OpenAPI spec files included in the [spec](spec) directory.\n\n## Setup\n\nThis SDK requires .NET 8.0 SDK to be installed.\n\n## Usage\n\n```bash\n# always include these package to use AccelByte .NET SDK\n$ dotnet add package AccelByte.Sdk.Abstractions\n$ dotnet add package AccelByte.Sdk.Core\n\n# include this package to do authentication to AGS or token validation\n$ dotnet add package AccelByte.Sdk.Authentication\n\n# feature packages, these are optional\n$ dotnet add package AccelByte.Sdk.Feature.AutoRefreshToken\n$ dotnet add package AccelByte.Sdk.Feature.LocalTokenValidation\n\n# Api packages. You can include only one or more packages depending on your need.\n$ dotnet add package AccelByte.Sdk.Api.\u003cApiName\u003e\n\n# Compatibility layer. Use this package to enable compatibility layer with monolithic sdk version.\n$ dotnet add package AccelByte.Sdk.Api.Compat\n```\n\nSee the list of api packages [here](apis/).\n\n### Environment Variables\n\nThe following environment variables need to be set when using `DefaultConfigRepository`.\n\n| Name               | Required                                         | Example                          |\n|--------------------|--------------------------------------------------|----------------------------------|\n| `AB_BASE_URL`      | Yes                                              | https://test.accelbyte.io        |\n| `AB_CLIENT_ID`     | Yes                                              | abcdef0123456789abcdef0123456789 |\n| `AB_CLIENT_SECRET` | Yes, but only if you use a private `AB_CLIENT_ID`| ab#c,d)ef(ab#c,d)ef(ab#c,d)ef(ab |\n| `AB_NAMESPACE`     | Yes                                              | accelbyte                        |\n\n### Instantiation\n    \n```csharp\n//Add core namespace\nusing AccelByte.Sdk.Core;\nusing AccelByte.Sdk.Core.Net.Http;\nusing AccelByte.Sdk.Core.Repository;\n\nIAccelByteSdk sdk = AccelByteSdk.Builder\n    .UseDefaultHttpClient()\n    .UseDefaultConfigRepository() // Using DefaultConfigRepository, make sure the required environment variables are set\n    .UseDefaultTokenRepository()\n    .UseDefaultCredentialRepository() // Required if you want to load user's credential via environment variables.\n    .UseDefaultTokenValidator() // Required if you want to use ValidateToken method.\n    .Build();\n```\n\n## Login\n\n### Login Using Username and Password\n\n```csharp\nbool login = sdk.LoginUser(\"myUsername\", \"myPassword\");\nif (!login)\n{\n    // Login failed  \n}\n```\n\n### Login Using Username and Password with Defined Scopes\n\n```csharp\nbool login = sdk.LoginUser(\"myUsername\", \"myPassword\", \"\u003cselected scopes\u003e\", null);\nif (!login)\n{\n    // Login failed  \n}\n```\n\n### Login Using Username and Password without Scopes\n\n```csharp\nbool login = sdk.LoginUser(\"myUsername\", \"myPassword\", null, null);\nif (!login)\n{\n    // Login failed  \n}\n```\n\n\n### Login Using OAuth Client\n\n```csharp\nbool login = sdk.LoginClient();\nif (!login)\n{\n    // Login failed  \n}\n```\n\u003e :warning: **Please use LoginClient() function with confidential OAuth client:** Using LoginClient() function with public OAuth client is not supported.\n\n## Interacting with a Service Endpoint\n\nAs an example, we will get current user profile info using [getMyProfileInfo](https://docs.accelbyte.io/api-explorer/#Basic/getMyProfileInfo) endpoint available in [basic](https://docs.accelbyte.io/api-explorer/#Basic) service.\n\n```csharp\n//Add api namespace\nusing AccelByte.Sdk.Api;\n\n//Add basic service model namespace\nusing AccelByte.Sdk.Api.Basic.Model;\n\n// Login using username and password\n\nbool login = sdk.LoginUser(\"myUsername\", \"myPassword\");\nif (!login)\n{\n    Console.WriteLine(\"Login failed\");\n}\n\n\n// Make a call to getMyProfileInfo endpoint\nvar response = sdk.GetBasicApi().UserProfile.GetMyProfileInfoOp.Execute(sdk.Namespace);\nif (response.IsSuccess \u0026\u0026 response.Data != null)\n{\n    UserProfilePrivateInfo profileData = response.Data;\n        \n    // do something with user profile data\n    Console.WriteLine(response.UserId);\n}\nelse\n{\n    //if call failed, get the error\n    var error = response.Error;\n    // do someting with call error.\n}\n\n/*\ntry\n{\n    // Or, use Ok() method to do use default error checking and get the response data directly\n    // Ok() method will throw an exception if there is any error or if the data is null.\n    UserProfilePrivateInfo profileData = sdk.GetBasicApi().UserProfile.GetMyProfileInfoOp.Execute(sdk.Namespace).EnsureSuccess();\n    \n    // do something with user profile data\n    Console.WriteLine(response.UserId);\n}\ncatch (HttpResponseException e)\n{\n    Console.WriteLine(e.Message);\n}\n*/\n```\n\n## Logout\n```csharp\nbool logout = sdk.Logout();\nif (!logout)\n{\n    // Logout failed\n}\n```\n\n## Working with Call Response\nEvery operation in C# Modular SDK will returns a response object. Use this object to do check whether the call is success or not, get the response data or error object.\n\n- `IsSuccess` property will be `true` if the call is success, otherwise `false`.\n- `Data` property contains response data from service. This property is **optional** depending whether the endpoint has response or not.\n- `Error` property contains error object if call failed, otherwise null.\n\nKnown errors are available in `\u003cServiceName\u003eErrors` static class. E.g `BasicErrors`, `IamErrors`, and so on.\n```csharp\nvar response = sdk.GetBasicApi().UserProfile.GetMyProfileInfoOp.Execute(sdk.Namespace);\nif (response.IsSuccess)\n{\n    // do something with response.Data\n}\nelse\n{\n    // do something with response.Error\n\n    // get error code\n    string errorCode = response.Error.Code;\n\n    // get error message\n    string errorMessage = response.Error.Message;\n\n    // or throw an exception\n    response.Error.ThrowException();\n\n    // compare to known error to handle more specific error\n    if (response.Error == BasicErrors.Error11440)\n    {\n        //do something if user profile not found.\n    }\n}\n```\n\nUse `EnsureSuccess()` method as a shorthand to do default error and null checking in response object. This method will return response data directly if the endpoint has response.\n```csharp\nUserProfilePrivateInfo profileData = sdk.GetBasicApi().UserProfile.GetMyProfileInfoOp\n    .Execute(sdk.Namespace)\n    .EnsureSuccess();\n```\n\n\n## Enable HTTP Logging\nTo enable http logging feature, build the sdk with `EnableLog()`.\n```csharp\nusing AccelByte.Sdk.Core;\n\nIAccelByteSdk sdk = AccelByteSdk.Builder\n    .UseDefaultHttpClient()\n    .UseDefaultConfigRepository()\n    .UseDefaultTokenRepository()\n    .EnableLog()\n    .Build();\n```\n\n## HTTP Retry Example\nIf retry feature is required, instantiate the sdk with `ReliableHttpClient` object.\n```csharp\n//Add core namespace\nusing AccelByte.Sdk.Core;\nusing AccelByte.Sdk.Core.Net.Http;\n\n//Using default retry policy \nHttpClientPolicy policy = HttpClientPolicy.Default;\n\nIAccelByteSdk sdk = AccelByteSdk.Builder\n    .SetHttpClient(ReliableHttpClient.Builder\n        .SetDefaultPolicy(policy)                    \n        .Build())    \n    .UseDefaultConfigRepository()\n    .UseDefaultTokenRepository()\n    .Build();\n```\n\nFor `HttpClientPolicy` properties, refer to [this code](AccelByte.Sdk.Core/Net/Http/HttpClientPolicy.cs).\n\n## Automatically Refresh Access Token\n\nTo enable automatic access token refresh, add the `AccelByte.Sdk.Feature.AutoRefreshToken package` and include the corresponding namespace. Then, instantiate the SDK using the following code.\n\n```csharp\n//Add core namespace\nusing AccelByte.Sdk.Core;\n\n//Add feature namespace\nusing AccelByte.Sdk.Feature.AutoRefreshToken;\n\nIAccelByteSdk sdk = AccelByteSdk.Builder\n    .UseDefaultHttpClient()\n    // Use DefaultConfigRepository: ensure the required environment variables are set\n    .UseDefaultConfigRepository()    \n    // Call this to enable background token refresh\n    .UseBackgroundTokenRefresh()\n    .Build();\n```\n\nTo configure background token refresh, set following environment variables.\n\n| Name                             | Required | Description                                                                                    |\n|----------------------------------|--------- |------------------------------------------------------------------------------------------------|\n| `AB_REFRESH_RATE`                | No       | Fraction of token lifetime before it is refreshed. Value between`0.0` to `1.0`. Default: `0.8` |\n| `AB_REFRESH_MAX_RETRY`           | No       | Maximum number of retries for refresh token requests before failing. Default: `2`              |\n| `AB_REFRESH_BACKGROUND_INTERVAL` | No       | Timer interval (in seconds) to check token expiry. Default: `10`                               |\n| `AB_REFRESH_BACKGROUND_ENABLED`  | No       | Enables background token refresh. Default: `true`                                              |\n\nNOTE: The `AB_REFRESH_RATE` uses a float value between `0` and `1` representing the fraction of the token's lifetime. For example, if a token is valid for 1 hour (3600 seconds), and `AB_REFRESH_RATE` is set to `0.5`, the SDK will attempt to refresh the token after it has less than 1800 seconds remaining (3600 x 0.5).\n\nBackground token refresh runs on a timer at a specified interval to check for token expiry. If the token is nearing its expiration time (as determined by the `AB_REFRESH_RATE` value), it will be refreshed automatically.\n\nIf a periodic background process is not preferred, use `.UseOnDemandTokenRefresh()` instead. This method triggers automatic token refresh whenever the SDK calls any AGS endpoint.\nPlease note that this type of token refresh is recommended only for OAuth client logins (using the LoginClient method), as it relies solely on the configured client ID and client secret values. It can be used for other login types, but once the refresh token expires, any subsequent calls will be unauthorized.\n\n```csharp\n//Add core namespace\nusing AccelByte.Sdk.Core;\n\n//Add feature namespace\nusing AccelByte.Sdk.Feature.AutoRefreshToken;\n\nIAccelByteSdk sdk = AccelByteSdk.Builder\n    .UseDefaultHttpClient()\n    // Use DefaultConfigRepository: ensure the required environment variables are set\n    .UseDefaultConfigRepository()\n    // call this to enable the feature\n    .UseOnDemandTokenRefresh()\n    .Build();\n```\n\nTo configure on-demand token refresh, set the following environment variables.\n\n| Name                          | Required | Description                                                                                    |\n|-------------------------------|--------- |------------------------------------------------------------------------------------------------|\n| `AB_REFRESH_RATE`             | No       | Fraction of token lifetime before it is refreshed. Value between`0.0` to `1.0`. Default: `0.8` |\n| `AB_REFRESH_MAX_RETRY`        | No       | Maximum number of retries for refresh token requests before failing. Default: `2`              |\n| `AB_REFRESH_ONDEMAND_ENABLED` | No       | Enables token refresh. Default: `true`                                                         |\n\nNOTE: Avoid using both `.UseOnDemandTokenRefresh()` and `.UseBackgroundTokenRefresh()` together, as it introduces unnecessary overhead and may lead to unexpected behavior.\n\n## Token Validation\nTo use token validation, add `AccelByte.Sdk.Authentication` package and instantiate the sdk with following code.\n```csharp\n//Add core namespace\nusing AccelByte.Sdk.Core;\n\nIAccelByteSdk sdk = AccelByteSdk.Builder\n    .UseDefaultHttpClient()\n    // Using DefaultConfigRepository, make sure the required environment variables are set\n    .UseDefaultConfigRepository()\n    // Credential repository is required for auto refresh token to works\n    .UseDefaultCredentialRepository()\n    // call this to enable the feature\n    .UseDefaultTokenValidator()    \n    .Build();\n```\n\nUse following method to validate access token.\n```csharp\nbool isValid = sdk.ValidateToken(accessTokenStr);\n```\n\nTo validate permission and action, use following method.\n```csharp\nbool isValid = sdk.ValidateToken(accessTokenStr, permissionStr, actionInt);\n```\n\nTo validate permission and action with specified namespace and/or userid, use following method.\n```csharp\nbool isValid = sdk.ValidateToken(accessTokenStr, permissionStr, actionInt, namespaceId, userId);\n```\n\nNote: To validate permission from user token, you need to instantiate the SDK with OAuth Client that has `ADMIN:ROLE [READ]` permission assigned to it.\n\n## Local Token Validation\nEnable this feature to use local token validation instead of default token validation.\nTo enable it, add `AccelByte.Sdk.Feature.LocalTokenValidation` package, include `AccelByte.Sdk.Feature.LocalTokenValidation` namespace and then instantiate the sdk with following code.\n```csharp\n//Add core namespace\nusing AccelByte.Sdk.Core;\n\n//Add feature namespace\nusing AccelByte.Sdk.Feature.LocalTokenValidation;\n\nIAccelByteSdk sdk = AccelByteSdk.Builder\n    .UseDefaultHttpClient()\n    // Using DefaultConfigRepository, make sure the required environment variables are set\n    .UseDefaultConfigRepository()\n    // Credential repository is required for auto refresh token to works\n    .UseDefaultCredentialRepository()\n    // call this to enable the feature\n    .UseLocalTokenValidator()\n    // call this to enable auto refresh for token revocation list\n    .UseAutoRefreshForTokenRevocationList()\n    // call this to enable auto cache clear for token validator\n    .UseTokenValidatorAutoClearCache()\n    .Build();\n```\n\nThen use the usual `ValidateToken` methods.\n\nIf you only want to parse the access token.\n```csharp\nvar payload = sdk.ParseAccessToken(accessTokenStr, false);\n```\nOr, you want to validate the token first before parse it.\n```csharp\nvar payload = sdk.ParseAccessToken('\u003caccess token\u003e', true);\n//payload will be null if the access token is invalid.\n```\n\nPermission and namespace context cache can be cleared manually or automatically with set interval.\n- To use it manually, call `sdk.Configuration.TokenValidator.InvalidateCache()`.\n- to enable auto clear, instantiate the sdk with `UseTokenValidatorAutoClearCache(\u003cinterval in seconds\u003e)` method.\n\n## Operation with Generic Response\nC# Extend SDK enable overloaded `ParseOperation` method with generic data type that applies to almost all operations with response model which has one or more object data type in it.\nFor example:\n```csharp\nusing AccelByte.Sdk.Api.Cloudsave.Model;\nusing AccelByte.Sdk.Api.Cloudsave.Operation;\n\nGameRecordExample myGameRecord = new GameRecordExample()\n{\n    MyStatus = \"ALIVE\",\n    Location = \"MOUNTAIN\",\n    Character = new GameRecordExample.CharacterClass()\n    {\n        Name = \"Character\",\n        Strength = 10,\n        Agility = 15,\n        Intelligence = 20\n    }\n};\n\nModelsGameRecordResponse\u003cGameRecordExample\u003e response = sdk.GetCloudsaveApi().PublicGameRecord.PostGameRecordHandlerV1Op\n    .Execute\u003cGameRecordExample\u003e(myGameRecord, \"test_record\", sdk.Namespace)\n    .EnsureSuccess();\n```\nThe list of which endpoints that support it can be found in [here](docs/operations/)\n\n## FlightID\nC# Extend SDK enable support for FlightID transmission during Http request. By default, new flight id will be generated when the sdk is loaded. There will be some case that this default value need to be updated with new value.\n-   To update default flight id globally, use following code:\n    ```csharp\n    AccelByteConfig.UpdateDefaultFlightId(\"\u003cnew flight id value\u003e\");\n    ```\n    This will update the default flight id, and will be used by newly created sdk object (won't affect existing sdk object created before this code get executed).\n\n-   To update flight id value in sdk object, use following code:\n    ```csharp\n    sdk.UpdateFlightId(\"\u003cnew flight id value\u003e\");\n    ```\n    This will update the flight id value stored inside the sdk object. Will be used for all operations executed by the sdk object.\n\n-   To update flight id value for specific operation, use `UpdateFlightId` method when building the operation object.\n    ```csharp\n    // Make a call to getMyProfileInfo endpoint\n    UserProfilePrivateInfo response = sdk.Basic.UserProfile.GetMyProfileInfoOp\n        .UpdateFlightId(\"\u003cnew flight id value\u003e\")\n        .Execute(sdk.Namespace)\n        .EnsureSuccess()\n    ```\n\n## Web Socket Service\n\nC# Extend SDK is able to connect to Lobby Web Socket Service. Following code demonstrate on how to use it.\n```csharp\n\nusing AccelByte.Sdk.Core;\nusing AccelByte.Sdk.Api.Lobby;\n\nvar sdk = AccelByteSdk.Builder\n    .UseDefaultHttpClient()\n    .UseDefaultConfigRepository()\n    .Build();\n\n// do login first\n\nvar lobbyWs = new LobbyService(sdk.Configuration);\n\n//start connect\nawait lobbyWs.Connect(false);\n\n//listen to message, this will block the execution\nawait lobbyWs.Listen();\n\n//disconnect\nawait lobbyWs.Disconnect();\n```\n\nBy default, web socket service is allowed to reconnect when not normal closure is received. To disable it, set `AllowReconnect` to false.\n```csharp\nlobbyWs.AllowReconnect = false;\n```\n\nTo handle message, register the event on which message type. For example:\n```csharp\nlobbyWs.OnFriendsStatusResponse = (data) =\u003e\n{\n\n};\n```\n\nIn some cases, it is probably desired to handle all incoming message in single handler. To do this, set `RedirectAllReceivedMessagesToMessageReceivedEvent` to true and register an action to `OnMessageReceived`.\n```csharp\nlobbyWs.RedirectAllReceivedMessagesToMessageReceivedEvent = true;\nlobbyWs.OnMessageReceived = (message) =\u003e\n{\n    \n};\n```\n\n## Migrate from Monolithic Version\nSee this [migration info](MIGRATION.md).\n\n## Documentation\nFor documentation about AccelByte Gaming Services and SDK, see [docs.accelbyte.io](https://docs.accelbyte.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Faccelbyte-csharp-modular-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faccelbyte%2Faccelbyte-csharp-modular-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Faccelbyte-csharp-modular-sdk/lists"}