Getting started and Using the library

This page contains brief information on how to setup and start using this library. If you want to get more information about certain method, class or enum, please refer to XML documentation

Installation

• Install package using IDE NuGet Package Manager by searching SteamGridDB.NET

  or

• Use this NuGet command Install-Package craftersmine.SteamGridDB.Net

Using the API

First, add using craftersmine.SteamGridDbNet namespace where you want to use class and instantiate a new instance of SteamGridDb class with your API key. You can get API key here

SteamGridDb sgdb = new SteamGridDb("your_api_key");

From now you can call any methods

SteamGridDB Games

To get SteamGridDB game info use GetGameByIdAsync() method. It will return SteamGridDbGame object that will contain game info. You can get SteamGridDB game ID by performing search.

SteamGridDbGame? game = await sgdb.GetGameByIdAsync(int gameId);

Also you can get SteamGridDbGame by Steam AppID using GetGameBySteamIdAsync() method.

SteamGridDbGame? game = await sgdb.GetGameBySteamIdAsync(int steamAppId);

Getting SteamGridDB Items

To get SteamGridDB items (like grids, heroes, icons and logos) for specific game, you can use two methods, by SteamGridDB Game ID, or by Platform specific AppID (like Steam AppID, or GOG AppID). These methods will return similar results.

To get Grids by SteamGridDB Game ID, use GetGridsByGameIdAsync() method

SteamGridDbGrid[]? grids = await sgdb.GetGridsByGameIdAsync(int gameId);

To get Grids by Platform specific AppID, use GetGridsByPlatformGameIdAsync() method

SteamGridDbGrid[]? grids = await sgdb.GetGridsByPlatformGameIdAsync(SteamGridDbGamePlatform platform, int plaformGameId);

If you want to get something else, instead of Grids, use

GetHeroesByGameIdAsync(int gameId);  // same as GetGridsByGameIdAsync(), but for Heroes
GetLogosByGameIdAsync(int gameId);   // same as above, but for Logos
GetIconsByGameIdAsync(int gameId);   // same as above, but for Icons

GetHeroesByPlatformGameIdAsync(SteamGridDbGamePlatform platform, int platformGameId); // same as GetGridsByPlatformGameIdAsync(), but for Heroes
GetLogosByPlatformGameIdAsync(...);  // same as above, but for Logos
GetIconsByPlatformGameIdAsync(...);  // same as above, but for Icons

All of these methods have optional parameters for applying filters. For additional information, please refer XML documentation of methods.

Uploading SteamGridDB items

While SteamGridDB API support uploading items, to upload items with your name, you should use your account API key.

To upload items to SteamGridDB, use UploadGridAsync() or UploadGridFromFileAsync() methods. If you want to upload something else, instead of Grids, refer to method naming here

UploadGridAsync() method expects two required parameters, integer for SteamGridDB game ID, and Stream of image data. It also have optional parameter that specifies style of the uploading item.

These methods return true if item was uploaded and false or throws an exception when failed.

These methods also only accept SteamGridDB Game ID's

UploadGridFromFileAsync() method works just as methods above, but instead of Stream, it requires string with full path to image file

bool success = await sgdb.UploadGridAsync(int gameId, Stream data, SteamGridDbStyle style);
bool success = await sgdb.UploadGridFromFileAsync(int gameId, string filePath, SteamGridDbStyle style);

To see what filetypes certain method accept, please refer to XML documentation

Removing items from SteamGridDB

You can only remove items that owned by the user whos API key used due to SteamGridDB API implementation

To remove items from SteamGridDB, use DeleteGridsAsync() or DeleteGridAsync() methods, the difference between these two is only that first accepts multiple item ID's, when second only accepts one item ID. You can get item ID by requesting specific items using get methods. To remove something else, instead of Grids, please refer to method naming here.

These methods return true if item was deleted and false or throws an exception when failed.

bool success = await sgdb.DeleteGridsAsync(params int[] itemIds);
bool success = await sgdb.DeleteGridAsync(int itemId);

SteamGridDB Search

You can perform search using SearchForGamesAsync() method. This method accept one string with search term and returns SteamGridDbGame array. SteamGridDB API automatically resolve any games that contains substrings in names from search term.

SteamGridDbGame[]? games = await sgdb.SearchForGamesAsync(string searchTerm);

Handling exceptions

Every SteamGridDB.NET method can throw an exception that inherited from SteamGridDbException. SteamGridDbException is a base exception type that represents a generic error while accessing SteamGridDB API.

There is also several exception that occur when specific error occurs:

• SteamGridDbBadRequestException - This occurs when request to server is generated incorrectly, most of the time it says about issue with API or library bug.
• SteamGridDbUnauthorizedException - This occurs when API key is missing, invalid or expired.
• SteamGridDbNotFoundException - This occurs when object is not found with specified parameters.
• SteamGridDbForbiddenException - This occurs most of the time when trying to delete object that doesn't owned by user of which API key is provided.
• SteamGridDbImageException - This occurs when something went wrong when accessing image data stream.

These exceptions can be used to correctly implement logic for errors when accessing API.