Aracılığıyla paylaş

gRPC hizmetlerinin sürümünü oluşturma

  • Makale

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Yayınlayan James Newton-King

Bir uygulamaya eklenen yeni özellikler, istemcilere sağlanan gRPC hizmetlerinin bazen beklenmedik ve hataya neden olan yollarla değişmesini gerektirebilir. gRPC hizmetleri değiştiğinde:

  • Değişikliklerin istemcileri nasıl etkilediğini göz önünde bulundurmak gerekir.
  • Değişiklikleri desteklemek için bir sürüm oluşturma stratejisi uygulanmalıdır.

Geriye dönük uyumluluk

gRPC protokolü, zaman içinde değişen hizmetleri destekleyecek şekilde tasarlanmıştır. Genel olarak, gRPC hizmetlerine ve yöntemlerine yapılan eklemeler hataya neden değildir. Hataya neden olmayan değişiklikler, mevcut istemcilerin değişiklik yapmadan çalışmaya devam etmelerini sağlar. gRPC hizmetlerinin değiştirilmesi veya silinmesi değişiklikleri bozuyor. gRPC hizmetlerinde hataya neden olan değişiklikler olduğunda, bu hizmeti kullanan istemcilerin güncelleştirilmesi ve yeniden dağıtılması gerekir.

Bir hizmette hataya neden olmayan değişiklikler yapmanın çeşitli avantajları vardır:

  • Mevcut istemciler çalışmaya devam ediyor.
  • İstemcilere hataya neden olan değişiklikleri bildirme ve güncelleştirme ile ilgili çalışmalardan kaçınıyor.
  • Hizmetin yalnızca bir sürümünün belgelenmesi ve korunması gerekir.

Hataya neden olmayan değişiklikler

Bu değişiklikler gRPC protokolü düzeyinde ve .NET ikili düzeyinde bozulmaz.

  • Yeni hizmet ekleme
  • Hizmete yeni yöntem ekleme
  • İstek iletisine alan ekleme - İstek iletisine eklenen alanlar ayarlanmadığında sunucudaki varsayılan değerle seri durumdan çıkarılır. Hataya neden olmayan bir değişiklik olması için, yeni alan eski istemciler tarafından ayarlanmamışsa hizmetin başarılı olması gerekir.
  • Yanıt iletisine alan ekleme - Eski bir istemci yeni alanla güncelleştirilmezse, değer yanıt iletisinin bilinmeyen alanlar koleksiyonunda seri durumdan çıkarılır.
  • Numaralandırmaya değer ekleme - Sabit listeleri sayısal değer olarak serileştirilir. Yeni numaralandırma değerleri, sabit listesi adı olmadan istemcide sabit listesi değerine seri durumdan çıkarılır. Hataya neden olmayan bir değişiklik olması için, eski istemcilerin yeni sabit listesi değerini alırken doğru şekilde çalışması gerekir.

İkili hataya neden olan değişiklikler

Aşağıdaki değişiklikler gRPC protokolü düzeyinde bozulmaz, ancak en son .proto sözleşmeye veya istemci .NET derlemesine yükseltilirse istemcinin güncelleştirilmesi gerekir. NuGet'e gRPC kitaplığı yayımlamayı planlıyorsanız ikili uyumluluk önemlidir.

  • Alan kaldırılıyor - Kaldırılan alandaki değerler, iletinin bilinmeyen alanlarına seri durumdan çıkarılır. Bu gRPC protokolünde hataya neden olan bir değişiklik değildir, ancak istemcinin en son sözleşmeye yükseltilmesi durumunda güncelleştirilmesi gerekir. Kaldırılan bir alan numarasının gelecekte yanlışlıkla yeniden kullanılamamış olması önemlidir. Bunun gerçekleşmediğinden emin olmak için, Protobuf'un ayrılmış anahtar sözcüğünü kullanarak iletide silinen alan numaralarını ve adları belirtin.
  • İletiyi yeniden adlandırma - İleti adları genellikle ağda gönderilmez, bu nedenle bu gRPC protokolünde hataya neden olan bir değişiklik değildir. İstemcinin en son sözleşmeye yükseltilmesi durumunda güncelleştirilmiş olması gerekir. İleti adlarının ağda gönderildiği durumlardan biri, ileti türünü tanımlamak için ileti adı kullanıldığında Any alanlarıdır.
  • İletiyi iç içe yerleştirme veya ayıklama - İleti türleri iç içe yerleştirilebilir. İletinin iç içe yerleştirilmesi veya iletinin işaretinin kaldırılması, iletinin adını değiştirir. bir ileti türünün iç içe nasıl yerleştirıldığını değiştirmek, uyumluluk üzerinde yeniden adlandırmayla aynı etkiye sahiptir.
  • csharp_namespace değiştirme - Değiştirme csharp_namespace , oluşturulan .NET türlerinin ad alanını değiştirir. Bu gRPC protokolünde hataya neden olan bir değişiklik değildir, ancak istemcinin en son sözleşmeye yükseltilmesi durumunda güncelleştirilmesi gerekir.

Protokolde hataya neden olan değişiklikler

Aşağıdaki öğeler protokol ve ikili hataya neden olan değişikliklerdir:

  • Alanı yeniden adlandırma - Protobuf içeriğiyle alan adları yalnızca oluşturulan kodda kullanılır. Alan numarası, ağdaki alanları tanımlamak için kullanılır. Bir alanı yeniden adlandırmak, Protobuf için protokole aykırı bir değişiklik değildir. Ancak, bir sunucu JSON içeriği kullanıyorsa bir alanı yeniden adlandırmak hataya neden olan bir değişikliktir.
  • Alan veri türünü değiştirme - Alanın veri türünün uyumsuz bir türle değiştirilmesi, iletinin seri durumdan çıkarılması sırasında hatalara neden olur. Yeni veri türü uyumlu olsa bile, en son sözleşmeye yükseltmesi durumunda istemcinin yeni türü destekleyecek şekilde güncelleştirilmesi gerekir.
  • Alan numarasını değiştirme - Protobuf yükleriyle, alan numarası ağdaki alanları tanımlamak için kullanılır.
  • Bir paketi, hizmeti veya yöntemi yeniden adlandırma - gRPC, URL'yi oluşturmak için paket adını, hizmet adını ve yöntem adını kullanır. İstemci sunucudan UNIMPLEMENTED durumunu alır.
  • Bir hizmet veya yöntem kaldırılıyor - İstemci, kaldırılan yöntemi çağırırken sunucudan UNIMPLEMENTED durumunu alır.

Davranış hataya neden olan değişiklikler

Hataya neden olmayan değişiklikler yaparken, eski istemcilerin yeni hizmet davranışıyla çalışmaya devam edip etmeyeceğini de göz önünde bulundurmanız gerekir. Örneğin, istek iletisine yeni alan ekleme:

  • Protokole aykırı bir değişiklik değil.
  • Yeni alan ayarlı değilse sunucuda hata durumunu döndürmek, eski istemciler için hataya neden olan bir değişiklik yapar.

Davranış uyumluluğu, uygulamaya özgü kodunuz tarafından belirlenir.

Sürüm numarası hizmetleri

Hizmetler eski istemcilerle geriye dönük olarak uyumlu kalmaya çaba göstermelidir. Sonunda uygulamanızda yapılan değişiklikler hataya neden olan değişiklikler gerektirebilir. Eski istemcileri bozmak ve bunları hizmetinizle birlikte güncelleştirilmeye zorlamak iyi bir kullanıcı deneyimi değildir. Hataya neden olan değişiklikler yaparken geriye dönük uyumluluğu korumanın bir yolu, hizmetin birden çok sürümünü yayımlamaktır.

gRPC, .NET ad alanı gibi çalışan isteğe bağlı bir paket tanımlayıcıyı destekler. Aslında, dosyasında ayarlanmadıysa option csharp_namespace .proto, package oluşturulan .NET türleri için .NET ad alanı olarak kullanılır. Paket, hizmetiniz ve iletileri için bir sürüm numarası belirtmek için kullanılabilir:

syntax = "proto3";

package greet.v1;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

Hizmet adresini tanımlamak için paket adı hizmet adıyla birleştirilir. Hizmet adresi, bir hizmetin birden çok sürümünün yan yana barındırılmasına izin verir:

  • greet.v1.Greeter
  • greet.v2.Greeter

Sürüme alınan hizmetin uygulamaları içinde Startup.cskaydedilir:

app.UseEndpoints(endpoints =>
{
    // Implements greet.v1.Greeter
    endpoints.MapGrpcService<GreeterServiceV1>();

    // Implements greet.v2.Greeter
    endpoints.MapGrpcService<GreeterServiceV2>();
});

Paket adına bir sürüm numarası eklemek, v1 sürümünü çağıran eski istemcileri desteklemeye devam ederken hataya neden olan değişikliklerle hizmetinizin v2 sürümünü yayımlama fırsatı sunar. İstemciler v2 hizmetini kullanacak şekilde güncelleştirdikten sonra eski sürümü kaldırmayı seçebilirsiniz. Bir hizmetin birden çok sürümünü yayımlamayı planlarken:

  • Makulse hataya neden olan değişikliklerden kaçının.
  • Hataya neden olan değişiklikler yapılmadığı sürece sürüm numarasını güncelleştirmayın.
  • Hataya neden olan değişiklikler yaptığınızda sürüm numarasını güncelleştirin.

Bir hizmetin birden çok sürümünü yayımlamak bunu yineler. Yinelemeyi azaltmak için iş mantığını hizmet uygulamalarından eski ve yeni uygulamalar tarafından yeniden kullanılabilecek merkezi bir konuma taşımayı göz önünde bulundurun:

using Greet.V1;
using Grpc.Core;
using System.Threading.Tasks;

namespace Services
{
    public class GreeterServiceV1 : Greeter.GreeterBase
    {
        private readonly IGreeter _greeter;
        public GreeterServiceV1(IGreeter greeter)
        {
            _greeter = greeter;
        }

        public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
        {
            return Task.FromResult(new HelloReply
            {
                Message = _greeter.GetHelloMessage(request.Name)
            });
        }
    }
}

Farklı paket adlarıyla oluşturulan hizmetler ve iletiler farklı .NET türleridir. İş mantığının merkezi bir konuma taşınması için iletilerin ortak türlerle eşleştirilmesi gerekir.

Ek kaynaklar