ASP.NET Core Web API: come consumarla da Unity3D

Programmare una ASP.NET Core Web API in c# e consumarla da Unity3D

Ti starai chiedendo cosa diamine c’entra Unity3D, che e’ principalmente un game engine, con una ASP.Net Core WEB API, vero?

Bravo, infatti non c’entra nulla in linea teorica tuttavia se dovessi decidere di sviluppare una app o un game con Unity3D sappi che, se vuoi, potresti progettarli a n-tier e quindi utilizzare le WEB API per crearti un RESTful service e “consumarlo” (termine che mi ha sempre fatto impazzire) dalla tua app o dal tuo videogame.

In questo articolo ti illustro i passaggi per programmare una WEB API in c# che restituisce il total score di un (ipotetico) game richiesto tra quelli presenti in un (finto) database, il tutto viene consumato da Unity3D.

Perfetto, dando per scontato che tu abbia un minimo di conoscenza di Unity3D e di WEB API ti chiedo di metterti comodo davanti al tuo pc e di leggere questo post.

Cosa ti serve

Per realizzare quanto descritto in questo post ti servira’ Visual Studio 2017 e Unity3D 2017/2018, niente altro.

La prima cosa che dobbiamo fare e’ implementare la WEB API; ossia scrivere la logica di ciò che dovrà fare il servizio ogni volta che il client chiederà di consumarlo; quindi procediamo a creare il progetto in Visual Studio.

ASP.Net Core WEB API

Esegui Visual Studio con i privilegi di administrator (fai clic col tasto destro del mouse sull’icona Visual Studio e seleziona Run as Admin) perche’ in seguito dovrai eseguire il web service nell’IIS della tua macchina e non potrai farlo se Visual Studio non ha i privilegi necessari; ovviamente questo step non serve se tu utilizzi già un account con privilegi alti.

Crea il progetto utilizzando il template apposito, come in Fig.1:

In caso non lo sapessi, questo template crea un progetto completo che a te fa comodo soltanto per la struttura già pronta ma non per quello che mostra se lo avviassi allo stato attuale in cui lo trovi ora.

Pertanto aggiungi ora la classe Game nel folder Models del tuo progetto, contenente la piccola struttura dati che utilizzerai in seguito per inviarla al client:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
namespace WebAPIConsumerUnity3D.Models
{
   public class Game
   {
      public int GameId
      {
         get;
         set;
      }
      public string GameName
      {
         get;
         set;
      }
      public int TotalScore
      {
         get;
         set;
      }
   }
}

Ora apri il folder Controllers e clicca su ValuesController.cs , elimina il codice al suo interno e incolla il seguente:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using WebAPIConsumerUnity3D.Models;
namespace WebAPIConsumerUnity3D.Controllers
{
   public class GameController : ApiController
   {
      IList<Game> games = new List<Game>()
      {
        new Game()
        {
           GameId = 1, GameName = "Game ONE", TotalScore = 1500000
        },
        new Game()
        {
           GameId = 2, GameName = "Game TWO", TotalScore = 1200000
        },
        new Game()
        {
           GameId = 3, GameName = "Game THREE", TotalScore = 15000
        },
        new Game()
        {
           GameId = 4, GameName = "Game FOUR", TotalScore = 7645000
        },
        new Game()
        {
           GameId = 5, GameName = "Game FIVE", TotalScore = 524872200
        },
     };
     public Game GetGameDetails(int id)
     {
        var game = games.FirstOrDefault(e => e.GameId == id);
        if (game == null)
        {
           throw new HttpResponseException(Request.CreateResponse(HttpStatusCode.NotFound));
        }
        return game;
     }
   }
}

Bene. In IList<Game> games = new List<Game>() hai inserito cinque giochi con relativo id, nome e punteggio totale (inutile dire che nella realtà al posto di questo codice si inseriscono le istruzioni per leggere dati da un database), il metodo GetGameDetails(int id) restituisce le informazioni di un singolo gioco.

Per quanto riguarda l’ASP.Net Core WEB API non devi fare altro se non avviare il progetto, attendere l’apertura del browser predefinito e digitare ad esempio:

http://localhost:xxxx/api/game/3

se appare come risultato una cosa di questotiposignifica che la WEB API sta girando correttamente:

{“GameId”:3,”GameName”:”Game THREE”,”TotalScore”:15000}

scommetto che a te il risultato è in formato XML, se è così e non sai come ottenere lo stesso risultato in formato JSON è un gioco da ragazzi; vai nel tuo progetto, apri il folder App_Start e clicca sul file WebApiConfig.cs e aggiungi le due righe di codice che seguono il commento // per output in JSON format:

public static void Register(HttpConfiguration config)
{
   // per output in JSON format
   config.Formatters.Clear();
   config.Formatters.Add(new JsonMediaTypeFormatter());
   // Servizi e configurazione dell'API Web
   // Route dell'API Web
   config.MapHttpAttributeRoutes();
   config.Routes.MapHttpRoute(
      name: "DefaultApi",
      routeTemplate: "api/{controller}/{id}",
      defaults: new { id = RouteParameter.Optional }
   );
}

Perfetto! Ora puoi passare all’obiettivo dell’articolo, ossia implementare un progetto in Unity3D che consuma la WEB API.

Consumare ASP.Net Core WEB API da Unity3D framework

Avvia Unity3D, crea un nuovo progetto chiamandolo come preferisci, crea uno script e al suo interno incolla il seguente codice:

using System;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
[Serializable]
public class Game
{
   public int Id;
   public string GameName;
   public int TotalScore;
}

come puoi notare non è altro che la struttura dati simile a quella definita nella WEB API.framework

Ora crea un gameobject in Hierarchy, associagli uno script chiamandolo WEBAPIConsumer e incolla al suo interno il seguente codice:

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Net;
using UnityEngine;
using UnityEngine.Networking;
public class GameController : MonoBehaviour
{
   public int gameId;
   void Start()
   {
      StartCoroutine(GetGame());
   }
   IEnumerator GetGame()
   {
      using (UnityWebRequest req = UnityWebRequest.Get(String.Format("http://localhost:6520/api/game/{0}", gameId)))
      {
         yield return req.SendWebRequest();
         while (!req.isDone)
            yield return null;
         byte[] result = req.downloadHandler.data;
         string gameJSON = System.Text.Encoding.Default.GetString(result);
         Game game = JsonUtility.FromJson<Game>(gameJSON);
         Debug.Log("Il game " + game.GameName + " ha totalizzato " + game.TotalScore + " punti");
         yield return game;
      }
  }
}

In questa classe, come puoi vedere, invochi il metodo GetGame() come coroutine anzichè come semplice metodo per evitare che l’invocazione della richiesta blocchi l’esecuzione del codice in attesa della risposta da parte della WEB API. framework

La riga di codice:

Game game = JsonUtility.FromJson<Game>(gameJSON);

effettua il parsing del formato JSON e riporta i dati nella struttura creata nella classe Game.

Questo esempio non è fornito con una GUI per brevità, quindi il risultato puoi vederlo nella finestra Console di Unity3D grazie alla seguente riga:

Debug.Log(“Il game ” + game.GameName + ” ha totalizzato ” + game.TotalScore + ” punti”);

Bene, arrivato a questo punto puoi mandare in esecuzione il progetto in Visual Studio della WEB API in modo tale da avere quest’ultima in ascolto, selezionare in Unity3D il gameobject a cui hai associato lo script GameController illustrato poc’anzi e nella finestra Inspector inserire un valore (ad esempio 4) al membro gameId, come in Fig.2:

Avvia ora il progetto in Unity3D e osserva la finestra Console, dovrebbe apparire il risultato in Fig.3:

Conclusioni

Benissimo, hai ottenuto l’obiettivo desiderato; ora sai come fare per consumare da Unity3D una ASP.Net Core WEB API.

Se ti è piaciuto questo articolo ti invito a votarlo nell’apposita sezione più in basso; inoltre, come prossime letture, ti suggerisco come programmare un bot chat con Microsoft Bot Framework.

Infine ti consiglio di leggere questo libro sull’argomento, puoi acquistarlo cliccando sulla copertina in basso o sul link. Grazie per la tua attenzione!

Acquista ora ASP.NET Core 2 Guida completa per lo sviluppatore