SignalR API tasarımında dikkat edilmesi gerekenler

Tarafından Andrew Stanton-Nurse

Bu makalede, tabanlı API'ler oluşturmaya SignalRyönelik yönergeler sağlanır.

Geriye dönük uyumluluk sağlamak için özel nesne parametrelerini kullanma

Hub SignalR yöntemine parametre eklemek (istemcide veya sunucuda) yıkıcı bir değişikliktir. Bu, eski istemcilerin/sunucuların uygun sayıda parametre olmadan yöntemini çağırmaya çalıştıklarında hatalarla karşılanacağı anlamına gelir. Ancak, özel nesne parametresine özellik eklemek, geri dönülemez bir değişikliğe yol açmaz. Bu, istemci veya sunucudaki değişikliklere dayanıklı uyumlu API'ler tasarlamak için kullanılabilir.

Örneğin, aşağıdaki gibi bir sunucu tarafı API'sini göz önünde bulundurun:

public int GetTotalLength(string param1)
{
    return param1.Length;
}

JavaScript istemcisi aşağıdaki gibi kullanarak invoke bu yöntemi çağırır:

connection.invoke("GetTotalLength", "value1");

Daha sonra sunucu yöntemine ikinci bir parametre eklerseniz, eski istemciler bu parametre değerini sağlamaz. Örneğin:

public int GetTotalLength(string param1, string param2)
{
    return param1.Length + param2.Length;
}

Eski istemci bu yöntemi çağırmaya çalıştığında aşağıdaki gibi bir hata alır:

Microsoft.AspNetCore.SignalR.HubException: Failed to invoke 'GetTotalLength' due to an error on the server.

Sunucuda şuna benzer bir günlük iletisi görürsünüz:

System.IO.InvalidDataException: Invocation provides 1 argument(s) but target expects 2.

Eski istemci yalnızca bir parametre gönderdi, ancak daha yeni sunucu API'sinde iki parametre gerekiyordu. Özel nesneleri parametre olarak kullanmak size daha fazla esneklik sağlar. Şimdi özgün API'yi özel bir nesne kullanacak şekilde yeniden tasarlayalım:

public class TotalLengthRequest
{
    public string Param1 { get; set; }
}

public int GetTotalLength(TotalLengthRequest req)
{
    return req.Param1.Length;
}

Şimdi istemci yöntemini çağırmak için bir nesnesi kullanıyor:

connection.invoke("GetTotalLength", { param1: "value1" });

Parametre eklemek yerine nesnesine TotalLengthRequest bir özellik ekleyin:

public class TotalLengthRequest
{
    public string Param1 { get; set; }
    public string Param2 { get; set; }
}

public int GetTotalLength(TotalLengthRequest req)
{
    var length = req.Param1.Length;
    if (req.Param2 != null)
    {
        length += req.Param2.Length;
    }
    return length;
}

Eski istemci tek bir parametre gönderdiğinde, ek Param2 özellik null kalır. Param2 ve null denetleyerek, eski bir istemci tarafından gönderilen bir iletiyi algılayabilir ve varsayılan bir değer uygulayabilirsiniz. Yeni bir istemci her iki parametreyi de gönderebilir.

connection.invoke("GetTotalLength", { param1: "value1", param2: "value2" });

Aynı teknik, istemcide tanımlanan yöntemler için de çalışır. Sunucu tarafından özel bir nesne gönderebilirsiniz:

public async Task Broadcast(string message)
{
    await Clients.All.SendAsync("ReceiveMessage", new
    {
        Message = message
    });
}

İstemci tarafında, bir parametre kullanmak yerine Message özelliğine erişin:

connection.on("ReceiveMessage", (req) => {
    appendMessageToChatWindow(req.message);
});

Daha sonra iletinin gönderenini yüke eklemeye karar verirseniz nesneye bir özellik ekleyin:

public async Task Broadcast(string message)
{
    await Clients.All.SendAsync("ReceiveMessage", new
    {
        Sender = Context.User.Identity.Name,
        Message = message
    });
}

Eski istemciler Sender değerini beklemez, bu nedenle bunu yoksayarlar. Yeni bir istemci, yeni özelliği okuyacak şekilde güncelleştirerek bunu kabul edebilir:

connection.on("ReceiveMessage", (req) => {
    let message = req.message;
    if (req.sender) {
        message = req.sender + ": " + message;
    }
    appendMessageToChatWindow(message);
});

Bu durumda, yeni istemci, Sender değerini sağlamayan eski bir sunucuya karşı da hoş görülüdür. Eski sunucu Sender değerini sağlamayacağından, istemci erişmeden önce onun var olup olmadığını kontrol eder.

Ek kaynaklar

• SignalR paylaşılan çerçevedeki derlemeler