Orleans geçiş kılavuzları

Bu makalede, ana Orleans sürümler arasında yükseltme için geçiş kılavuzu sağlanır. Yukarıdaki sürüm seçiciyi kullanarak hedef sürümünüzü seçin.

7.0'dan Orleans 10.0'a geçiş

Orleans 10.0, yerleşik Pano dahil olmak üzere çeşitli yeni özellikler sunar. Bu bölüm, ara adımlar ile 8.0 ve 9.0 arasında olmak üzere 7.0'dan Orleans 10.0'a geçiş için gereken değişiklikleri kapsar.

Önemli değişiklikler özeti

Uyum bozan değişiklik Etki Göç
AddGrainCallFilter Kaldırıldı Derleme hatası AddIncomingGrainCallFilter komutunu kullanma
LeaseAquisitionPeriod yazım hatası düzeltildi Derleme hatası LeaseAcquisitionPeriod komutunu kullanma
LoadSheddingLimit yeniden adlandırıldı Derleme hatası CpuThreshold komutunu kullanma
CancelRequestOnTimeout varsayılan değiştirildi Davranış Gerekirse açıkça olarak true olarak ayarlanır
ADO.NET sağlayıcısı için Microsoft.Data.SqlClient gerekir Derleme/Çalışma Zamanı hatası Paketi değiştir System.Data.SqlClient
[Unordered] özniteliği kullanım dışı bırakıldı Uyarı Özniteliği kaldır (hiçbir etkisi yoktur)
OrleansConstructorAttribute kullanım dışı Uyarı Yalnızca bağımlılık enjeksiyonu gerektiren oluşturucular için GeneratedActivatorConstructorAttribute veya ActivatorUtilitiesConstructorAttribute kullanın, serileştirilmiş veri özellikleri için değil.
RegisterTimer kullanım dışı Uyarı RegisterGrainTimer komutunu kullanma

Paket güncelleştirmeleri

NuGet paketi başvurularınızı 7.x'ten Orleans 10.0'a güncelleştirin:

Orleans 7.x Paketi Orleans 10.0 Paket
Microsoft.Orleans.Server 7.x Microsoft.Orleans.Server 10.0.0
Microsoft.Orleans.Client 7.x Microsoft.Orleans.Client 10.0.0
Microsoft.Orleans.Sdk 7.x Microsoft.Orleans.Sdk 10.0.0
Microsoft.Orleans.Streaming.EventHubs 7.x Microsoft.Orleans.Streaming.EventHubs 10.0.0
Microsoft.Orleans.Streaming.AzureStorage 7.x Microsoft.Orleans.Streaming.AzureStorage 10.0.0
Microsoft.Orleans.Persistence.AzureStorage 7.x Microsoft.Orleans.Persistence.AzureStorage 10.0.0
Microsoft.Orleans.Clustering.AzureStorage 7.x Microsoft.Orleans.Clustering.AzureStorage 10.0.0

Kritik değişiklik: AddGrainCallFilter ile değiştirildi AddIncomingGrainCallFilter

AddGrainCallFilter üzerindeki IServiceCollection uzantı yöntemi kaldırıldı. AddIncomingGrainCallFilter veya ISiloBuilder üzerinde IClientBuilder ile değiştirin.

// Orleans 7.x (no longer works)
services.AddGrainCallFilter(new MyFilter());
services.AddGrainCallFilter<MyFilter>();

// Orleans 10.0
siloBuilder.AddIncomingGrainCallFilter(new MyFilter());
siloBuilder.AddIncomingGrainCallFilter<MyFilter>();

// Or using a delegate
siloBuilder.AddIncomingGrainCallFilter(async context =>
{
    // Before grain call
    await context.Invoke();
    // After grain call
});

İstemcilerden giden çağrılar için AddOutgoingGrainCallFilter kullanın.

siloBuilder.AddOutgoingGrainCallFilter<MyOutgoingFilter>();
clientBuilder.AddOutgoingGrainCallFilter<MyOutgoingFilter>();

Hataya neden olan değişiklik: LeaseAquisitionPeriod yazım hatası düzeltildi

LeaseAquisitionPeriod içinde yanlış yazılmış özellik LeaseBasedQueueBalancerOptions olarak LeaseAcquisitionPeriod şeklinde düzeltildi.

// Orleans 7.x (typo)
options.LeaseAquisitionPeriod = TimeSpan.FromSeconds(30);

// Orleans 10.0 (corrected)
options.LeaseAcquisitionPeriod = TimeSpan.FromSeconds(30);

Kırıcı değişiklik: LoadSheddingLimit, CpuThreshold olarak yeniden adlandırıldı

LoadSheddingLimit içindeki LoadSheddingOptions özelliği amacını daha iyi yansıtacak şekilde CpuThreshold olarak yeniden adlandırıldı.

// Orleans 7.x
siloBuilder.Configure<LoadSheddingOptions>(options =>
{
    options.LoadSheddingEnabled = true;
    options.LoadSheddingLimit = 95; // No longer works
});

// Orleans 10.0
siloBuilder.Configure<LoadSheddingOptions>(options =>
{
    options.LoadSheddingEnabled = true;
    options.CpuThreshold = 95; // Use this instead
});

Hataya neden olan değişiklik: CancelRequestOnTimeout varsayılan değiştirildi

Varsayılan değer MessagingOptions.CancelRequestOnTimeout'den truefalse olarak değiştirildi. Bu, varsayılan olarak, Orleans bir tane çağrısı zaman aşımına uğradığında artık iptal iletisi göndermediği anlamına gelir.

Uygulamanız önceki davranışa bağlıysa bu seçeneği açıkça ayarlayın:

siloBuilder.Configure<SiloMessagingOptions>(options =>
{
    options.CancelRequestOnTimeout = true;
});

// For clients
clientBuilder.Configure<ClientMessagingOptions>(options =>
{
    options.CancelRequestOnTimeout = true;
});

Hataya neden olan değişiklik: ADO.NET sağlayıcısı için Microsoft.Data.SqlClient gerekir

ADO.NET sağlayıcıları (kümeleme, kalıcılık, anımsatıcılar) artık Microsoft.Data.SqlClient yerine System.Data.SqlClient gerektirir. Proje başvurularınızı güncelleştirin:

<!-- Remove -->
<PackageReference Include="System.Data.SqlClient" Version="..." />

<!-- Add -->
<PackageReference Include="Microsoft.Data.SqlClient" Version="5.2.0" />

Sabit ad da değişti:

// Orleans 7.x
options.Invariant = "System.Data.SqlClient";

// Orleans 10.0
options.Invariant = "Microsoft.Data.SqlClient";

Kritik değişiklik: [Unordered] öznitelik kullanım dışı bırakıldı

[Unordered] tanımlaması artık arayüzlerde kullanım dışıdır ve hiçbir etkisi yoktur. Bu özniteliğe bakılmaksızın, mesaj sıralaması hiçbir zaman garanti edilmedi. Özniteliği kodunuzdan kaldırın:

// Orleans 7.x
[Unordered]
public interface IMyGrain : IGrainWithStringKey
{
    Task DoSomething();
}

// Orleans 10.0 - just remove the attribute
public interface IMyGrain : IGrainWithStringKey
{
    Task DoSomething();
}

Kritik değişiklik: OrleansConstructorAttribute kullanım dışı bırakıldı

OrleansConstructorAttribute kullanım dışı bırakıldı. Bunun yerine GeneratedActivatorConstructorAttribute veya ActivatorUtilitiesConstructorAttribute kullanın. Bu öznitelikleri yalnızca bağımlılık ekleme yoluyla hizmetlerin eklenmesini gerektiren oluşturuculara uygulayın. Bunları, serileştirilmiş veri özelliklerini veya alanlarını nasıl Orleans ayarlayacağını belirtmek için kullanmayın.

public interface IMyDependency
{
}

// Orleans 7.x
[GenerateSerializer]
public class MyClass
{
    [Id(0)]
    public string Value { get; set; }

    [OrleansConstructor] // Obsolete and ignored
    public MyClass(IMyDependency dependency)
    {
        Dependency = dependency;
    }

    [field: NonSerialized]
    public IMyDependency Dependency { get; }
}

// Orleans 10.0
[GenerateSerializer]
public class MyClass
{
    [Id(0)]
    public string Value { get; set; }

    [GeneratedActivatorConstructor]
    public MyClass(IMyDependency dependency)
    {
        Dependency = dependency;
    }

    [field: NonSerialized]
    public IMyDependency Dependency { get; }
}

Kritik değişiklik: RegisterTimer kullanım dışı bırakıldı

Grain.RegisterTimer Yöntemi kullanımdan kaldırıldı. Bunun yerine zamanlayıcı davranışı üzerinde daha iyi denetim sağlayan yeni RegisterGrainTimer uzantı yöntemlerini kullanın.

// Orleans 7.x
public override Task OnActivateAsync(CancellationToken cancellationToken)
{
    RegisterTimer(
        callback: DoWork,
        state: null,
        dueTime: TimeSpan.FromSeconds(1),
        period: TimeSpan.FromSeconds(10));
    return Task.CompletedTask;
}

// Orleans 10.0
public override Task OnActivateAsync(CancellationToken cancellationToken)
{
    this.RegisterGrainTimer(
        callback: DoWork,
        state: (object?)null,
        options: new GrainTimerCreationOptions
        {
            DueTime = TimeSpan.FromSeconds(1),
            Period = TimeSpan.FromSeconds(10),
            Interleave = true // Set to true for same behavior as old RegisterTimer
        });
    return Task.CompletedTask;
}

Önemli

Varsayılan olarak, RegisterGrainTimer zamanlayıcı geri aramalarının diğer grain çağrılarıyla araya girmesini engelleyen Interleave = false kullanır. Zamanlayıcı geri çağırmalarının eşzamanlı gerçekleştiği eski davranışa ihtiyacınız varsa, bunu açıkça ayarlayın Interleave = true.

10.0 sürümündeki Orleans yeni özellikler

Geçiş yaptıktan sonra şu yeni özelliklerden yararlanabilirsiniz:

8.0'dan Orleans 9.0'a geçiş

8.x'ten Orleans yükseltme yapıyorsanız, 9.0'da Orleans sunulan şu ek değişiklikleri not edin:

  • Güçlü tutarlılık grain dizini: Varsayılan grain dizini artık daha güçlü tutarlılık garantileri sağlar
  • Tam CancellationToken desteği: Grain yöntemleri artık CancellationToken parametrelerini tam olarak destekliyor
  • Bellek kaynaklı etkinlik azaltma: Bellek baskısı altında otomatik birim devre dışı bırakma
  • Daha hızlı üyelik protokolü: Varsayılan hata algılama süresi 10 dakikadan 90 saniyeye düşürüldü
  • Varsayılan yerleştirme ResourceOptimized olarak değiştirildi (9,2+): Varsayılan tahıl yerleştirme stratejisi RandomPlacement'den ResourceOptimizedPlacement olarak değiştirildi

Uygulamanız rastgele yerleştirmeye bağlıysa açıkça yapılandırın:

siloBuilder.Services.AddSingleton<PlacementStrategy, RandomPlacement>();

// Or on specific grains
[RandomPlacement]
public class MyGrain : Grain, IMyGrain { }

7.0'dan Orleans 8.0'a geçiş

7.x'ten Orleans yükseltme yapıyorsanız, 8.0'da Orleans sunulan şu değişiklikleri not edin:

  • Yeni Zamanlayıcı API: RegisterGrainTimer kullanıma sunulmuştur RegisterTimer değiştirmek için
  • .NET Aspire tümleştirme: .NET Aspire için birinci sınıf destek
  • Kaynak-Optimizasyonu Yerleştirme: CPU ve hafıza kullanımına dayalı yeni yerleştirme stratejisi
  • Etkinleştirme Yeniden Bölümleme (8.2+): Otomatik tane yeniden dengeleme için deneysel özellik

Sıralı yükseltmeler

Önemli protokol ve API değişiklikleri nedeniyle 7.x'ten Orleans 10.0'a sıralı yükseltmeler önerilmez. Yerine:

  1. Yeni bir küme, Orleans 10.0 çalışacak şekilde dağıtın.
  2. Gerekirse durum verilerini geçirme
  3. Trafiği yeni kümeye değiştirme
  4. Eski kümeyi devreden çıkarma

ADO.NET geçiş betikleri

Kümeleme, kalıcılık veya anımsatıcılar için ADO.NET kullanıyorsanız, uygun geçiş betiklerini uygulayın:

3.x'ten Orleans 7.0'a geçiş

Orleans 7.0, barındırma iyileştirmeleri, özel serileştirme, değişmezlik ve tahıl soyutlamaları dahil olmak üzere çeşitli yararlı değişiklikler sunar.

Göç

Taneleri ve akışları tanımlama şekillerindeki Orleans değişiklikler nedeniyle, hatırlatıcılar, akışlar veya tane kalıcılığı kullanarak mevcut uygulamaları Orleans 7.0'a taşımak şu anda pek kolay değil.

7.0'a Orleans sıralı yükseltme yoluyla önceki Orleans sürümleri çalıştıran uygulamaların sorunsuz bir şekilde yükseltilmesi mümkün değildir. Bu nedenle, yeni bir küme dağıtma ve önceki kümeyi devreden çıkarma gibi farklı bir yükseltme stratejisi kullanın. Orleans7.0 sürümü, protokol uyumsuzluğuna neden olacak şekilde kablo protokolünü değiştirir; bu, kümelerin Orleans içinde 7.0 ve önceki Orleans sürümlerini çalıştıran konakların karışımını içeremeyeceği anlamına gelir.

Büyük sürümler arasında bile uyumluluğu bozan değişikliklerden uzun yıllardır kaçınılmaktadır. Neden şimdi? İki önemli neden vardır: kimlikler ve serileştirme. Kimliklerle ilgili olarak, tanecik ve akış kimlikleri artık dizelerden oluşmaktadır. Bu, taneciklerin genel tür bilgilerini düzgün bir şekilde kodlamasını sağlar ve uygulama etki alanına eşleme akışlarını kolaylaştırır. Daha önce, Orleans, genel tanecikleri temsil edemeyen karmaşık bir veri yapısı kullanarak tane türlerini tanımlar, bu da istisnai durumlara yol açardı. Akışlar, uygulama etki alanıyla eşlemesi verimli ancak zor olan bir stringGuid ad alanı ve anahtar tarafından belirlendi. Serileştirme artık sürüme dayanıklıdır. Bu, türlerin belirli uyumlu yollarla değiştirilebileceği ve bir dizi kurala uyularak uygulamanın serileştirme hatası olmadan yükseltilebileceği anlamına gelir. Bu özellik özellikle uygulama türleri akışlarda veya tahıl depolamada kalıcı olduğunda yararlıdır. Aşağıdaki bölümlerde önemli değişiklikler ayrıntılı olarak anlatılır ve bunlar daha ayrıntılı olarak ele alınır.

Paketleme değişiklikleri

Bir projeyi 7.0'a Orleans yükseltirken aşağıdaki eylemleri gerçekleştirin:

  • Tüm istemciler Microsoft.Orleans.İstemci'ye referans vermelidir.
  • Tüm silolar (sunucular) Microsoft.Orleans.Server referans almalıdır.
  • Diğer tüm paketler Orleans'ye başvurmalıdır.
  • Microsoft.Orleans.CodeGenerator.MSBuild ve Microsoft.Orleans.OrleansCodeGenerator.Build tüm başvurularını kaldırın.
  • Microsoft.Orleans.OrleansRuntime ile ilgili tüm referansları kaldırın.
  • ConfigureApplicationParts çağrılarını kaldırın. Uygulama Bölümleri kaldırıldı. için Orleans C# Kaynak Oluşturucu tüm paketlere (istemci ve sunucu dahil) eklenir ve uygulama bölümlerinin eşdeğerini otomatik olarak oluşturur.
  • Microsoft.Orleans.OrleansServiceBus başvurularını OrleansMicrosoft.Streaming.EventHubs ile değiştirin.
  • Anımsatıcılar kullanıyorsanız, Orleans başvurusuna bir başvuru ekleyin.
  • Akışları kullanıyorsanız, Microsoft.Orleans.Streaming için bir başvuru ekleyin.

İpucu

Orleans Tüm örnekler 7.0'a Orleans yükseltilmiştir ve yapılan değişikliklerin başvurusu olarak kullanılabilir. Daha fazla bilgi için bkz Orleans . Sorun #8035 her örnekte yapılan değişiklikleri kategorilere ayırıyor.

Orleans genel kullanım yönergeleri

Tüm Orleans projeleri doğrudan veya dolaylı olarak Microsoft.Orleans.Sdk NuGet paketine başvurur. Bir Orleans proje, örtük kullanımları etkinleştirecek şekilde yapılandırıldığında (örneğin, <ImplicitUsings>enable</ImplicitUsings>), proje hem Orleans hem de Orleans.Hosting ad alanlarını örtük olarak kullanır. Bu, uygulama kodunun bu using yönergelere gerek duymadığı anlamına gelir.

Daha fazla bilgi için bkz. ImplicitUsings ve dotnet/orleans/src/Orleans. Sdk/build/Microsoft.Orleans. Sdk.targets.

Barındırma

ClientBuilder türü, UseOrleansClient üzerindeki IHostBuilder uzantı yöntemiyle değiştirilir. IHostBuilder türü, Microsoft.Extensions.Hosting NuGet paketinden gelir. Bu, bir Orleans istemcinin ayrı bir bağımlılık ekleme kapsayıcısı oluşturmadan mevcut bir konağa eklenebileceği anlamına gelir. İstemci, başlatma sırasında kümeye bağlanır. İşlem tamamlandıktan sonra IHost.StartAsync istemci otomatik olarak bağlanır. Hizmetler, IHostBuilder başlangıcına kayıt sırasına göre eklenir. örneğin, UseOrleansClient çağırmadan önce ConfigureWebHostDefaults çağrılması, Orleans ASP.NET Core başlamadan önce başlatılmasını sağlar ve istemciye ASP.NET Core uygulamasından hemen erişim sağlar.

Önceki ClientBuilder davranışını öykünmek için HostBuilder oluşturun ve bu ayrı bir Orleans istemciyle yapılandırın. bir IHostBuilder ya bir Orleans istemciyle ya da bir Orleans siloyla yapılandırılabilir. Tüm silolar, uygulamanın kullanabileceği şekilde IGrainFactory ve IClusterClient örneklerini kaydeder, bu yüzden istemciyi ayrı olarak yapılandırmak gereksizdir ve desteklenmez.

OnActivateAsync ve OnDeactivateAsync imza değişikliği

Orleans, tanelerin etkinleştirme ve devre dışı bırakma sırasında kod yürütmesine izin verir. Depolamadan durum okuma veya yaşam döngüsü iletilerini günlüğe kaydetme gibi görevleri gerçekleştirmek için bu özelliği kullanın. 7.0'da Orleans , bu yaşam döngüsü yöntemlerinin imzası değişti:

Bu yeni yöntemleri geçersiz kılmaya yönelik aşağıdaki tahıl örneğini göz önünde bulundurun:

public sealed class PingGrain : Grain, IPingGrain
{
    private readonly ILogger<PingGrain> _logger;

    public PingGrain(ILogger<PingGrain> logger) =>
        _logger = logger;

    public override Task OnActivateAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("OnActivateAsync()");
        return Task.CompletedTask;
    }

    public override Task OnDeactivateAsync(DeactivationReason reason, CancellationToken token)
    {
        _logger.LogInformation("OnDeactivateAsync({Reason})", reason);
        return Task.CompletedTask;
    }

    public ValueTask Ping() => ValueTask.CompletedTask;
}

POCO taneleri ve IGrainBase

Orleans içindeki tanecikler artık Grain temel sınıfından veya başka bir sınıftan devralmak zorunda değildir. Bu işlev POCO grains olarak adlandırılır. Aşağıdakilerden herhangi biri gibi uzantı yöntemlerine erişmek için:

Tanecik IGrainBase uygulamalı veya Grain öğesinden devralmalıdır. Aşağıda, bir tahıl sınıfı üzerinde IGrainBase uygulama örneği verilmiştir:

public sealed class PingGrain : IGrainBase, IPingGrain
{
    public PingGrain(IGrainContext context) => GrainContext = context;

    public IGrainContext GrainContext { get; }

    public ValueTask Ping() => ValueTask.CompletedTask;
}

IGrainBase, OnActivateAsync ve OnDeactivateAsync'yi varsayılan uygulamalarla tanımlayarak, tahılın istenirse yaşam döngüsüne katılmasını sağlar.

public sealed class PingGrain : IGrainBase, IPingGrain
{
    private readonly ILogger<PingGrain> _logger;

    public PingGrain(IGrainContext context, ILogger<PingGrain> logger)
    {
        _logger = logger;
        GrainContext = context;
    }

    public IGrainContext GrainContext { get; }

    public Task OnActivateAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("OnActivateAsync()");
        return Task.CompletedTask;
    }

    public Task OnDeactivateAsync(DeactivationReason reason, CancellationToken token)
    {
        _logger.LogInformation("OnDeactivateAsync({Reason})", reason);
        return Task.CompletedTask;
    }

    public ValueTask Ping() => ValueTask.CompletedTask;
}

Serileştirme

7.0 sürümündeki Orleans en zahmetli değişiklik, sürüme dayanıklı serileştiricinin tanıtılmasıdır. Bu değişiklik, uygulamaların evriliyor olması nedeniyle önceki seri hale getiricinin mevcut türlere özellik eklemeyi tolere edememesi ve bu durumun geliştiricilere önemli bir dezavantaj yaratması sonucunda yapılmıştır. Öte yandan, önceki seri hale getirici esnekti ve genel türler, polimorfizm ve başvuru izleme gibi özellikler dahil olmak üzere çoğu .NET türünün değiştirilmeden temsil edilmesine olanak sağlıyordu. Uzun zamandır bir değişiklik gerekti, ama türlerin yüksek sadakatle temsil edilmesine hâlâ ihtiyaç var. Bu nedenle, Orleans 7.0, .NET türlerinin yüksek doğrulukta temsilini sağlayan ve türlerin gelişmesine olanak tanıyan yeni bir seri hale getirici tanıtıyor. Yeni seri hale getirici, öncekine göre çok daha verimlidir ve bu, uçtan uca aktarım hızında 170%'a kadar bir artış sağlamaktadır.

Daha fazla bilgi için 7.0 ile ilgili olarak aşağıdaki makalelere Orleans bakın:

Tahıl Kimlikleri

Her bir tanecik, tahılın türünden ve anahtarından oluşan benzersiz bir kimliğe sahiptir. Önceki Orleans sürümlerde, tanecik anahtarlarını desteklemek için GrainId üzerinde birleşik bir tür kullanılmıştır.

Bu yaklaşım, tahıl anahtarlarıyla ilgilenirken biraz karmaşıklık içerir. Tahıl kimlikleri iki bileşenden oluşur: tür ve anahtar. Tür bileşeni daha önce sayısal tür kodu, kategori ve 3 bayt genel tür bilgilerinden oluşuyordu.

Tahıl kimlikleri artık hem type/key hem de type dize olan key biçimindedir. En yaygın kullanılan tanecik anahtar arabirimidir IGrainWithStringKey. Bu, taneli kimliğin çalışma şeklini büyük ölçüde basitleştirir ve genel tane türleri desteğini geliştirir.

Grain arabirimleri artık karma kod ve herhangi bir genel tür parametresinin dize gösterimi yerine insan tarafından okunabilir bir ad kullanılarak temsil edilmektedir.

Yeni sistem daha özelleştirilebilir ve bu özelleştirmeler özniteliklerle yönlendirilebilir.

  • GrainTypeAttribute(String) bir tane üzerinde, tanecik class kimliğinin Tür bölümünü belirtir.
  • DefaultGrainTypeAttribute(String) bir tanecik interface üzerinde, bir tanecik referansı alındığında varsayılan olarak çözülmesi gereken tanecik türünüIGrainFactory belirtir. Örneğin, IGrainFactory.GetGrain<IMyGrain>("my-key") çağrıldığında, yukarıda belirtilen özniteliğe sahipse, tahıl fabrikası tahıla bir "my-type/my-key" başvurusu geri döndürür.
  • GrainInterfaceTypeAttribute(String) arabirim adının geçersiz kılınmasına izin verir. Bu mekanizmayı kullanarak açıkça bir ad belirtmek, mevcut tanecik başvurularıyla uyumluluğu bozmadan arabirim türünün yeniden adlandırılmasına olanak tanır. Bu durumda arabirimde de AliasAttribute olması gerektiğini, çünkü kimliği seri hale getirilebileceğini unutmayın. Tür takma adı belirtme hakkında daha fazla bilgi için, serileştirme bölümüne bakın.

Yukarıda belirtildiği gibi, türler için varsayılan tanecik sınıfını ve arabirim adlarını geçersiz kılma, mevcut dağıtımlarla uyumluluğu bozmadan temel türlerin yeniden adlandırılmasına olanak tanır.

Veri akış kimlikleri

Akışlar ilk yayımlandığında Orleans, akışlar yalnızca Guid kullanılarak tanımlanabiliyordu. Bu yaklaşım bellek ayırma açısından verimliydi ancak anlamlı akış kimlikleri oluşturmayı zorlaştırdı ve genellikle belirli bir amaca uygun akış kimliğini belirlemek için bazı kodlama veya dolaylı işlemler gerekti.

7.0'da Orleans akışlar dizeler kullanılarak tanımlanır. üç Orleans.Runtime.StreamIdstruct özellik içerir: StreamId.Namespace, StreamId.Keyve StreamId.FullKey. Bu özellik değerleri UTF-8 dizeleri olarak kodlanmıştır. Örnek için bkz. StreamId.Create(String, String).

SimpleMessageStreams'in BroadcastChannel ile değiştirilmesi

SimpleMessageStreams (SMS olarak da adlandırılır) 7.0'da kaldırılır. SMS, Orleans.Providers.Streams.PersistentStreams ile aynı arabirime sahipti, ancak doğrudan birimden birime çağrılara dayandığı için davranışı çok farklıydı. Karışıklığı önlemek için SMS kaldırıldı ve Orleans.BroadcastChannel adlı yeni bir ikame getirildi.

BroadcastChannel yalnızca örtük abonelikleri destekler ve bu durumda doğrudan yerini alabilir. Açık abonelikler gerekiyorsa veya arabirimin PersistentStream kullanılması gerekiyorsa (örneğin, sms üretimde kullanılırken EventHub testlerde kullanıldıysa), MemoryStream en iyi adaydır.

BroadcastChannel SMS ile aynı davranışlara sahipken MemoryStream diğer akış sağlayıcıları gibi davranır. Aşağıdaki Yayın Kanalı kullanım örneğini göz önünde bulundurun:

// Configuration
builder.AddBroadcastChannel(
    "my-provider",
    options => options.FireAndForgetDelivery = false);

// Publishing
var grainKey = Guid.NewGuid().ToString("N");
var channelId = ChannelId.Create("some-namespace", grainKey);
var stream = provider.GetChannelWriter<int>(channelId);

await stream.Publish(1);
await stream.Publish(2);
await stream.Publish(3);

// Simple implicit subscriber example
[ImplicitChannelSubscription]
public sealed class SimpleSubscriberGrain : Grain, ISubscriberGrain, IOnBroadcastChannelSubscribed
{
    // Called when a subscription is added to the grain
    public Task OnSubscribed(IBroadcastChannelSubscription streamSubscription)
    {
        streamSubscription.Attach<int>(
          item => OnPublished(streamSubscription.ChannelId, item),
          ex => OnError(streamSubscription.ChannelId, ex));

        return Task.CompletedTask;

        // Called when an item is published to the channel
        static Task OnPublished(ChannelId id, int item)
        {
            // Do something
            return Task.CompletedTask;
        }

        // Called when an error occurs
        static Task OnError(ChannelId id, Exception ex)
        {
            // Do something
            return Task.CompletedTask;
        }
    }
}

MemoryStream Yalnızca yapılandırmanın değiştirilmesi gerektiğinden geçiş daha kolaydır. Aşağıdaki MemoryStream yapılandırmayı göz önünde bulundurun:

builder.AddMemoryStreams<DefaultMemoryMessageBodySerializer>(
    "in-mem-provider",
    _ =>
    {
        // Number of pulling agent to start.
        // DO NOT CHANGE this value once deployed, if you do rolling deployment
        _.ConfigurePartitioning(partitionCount: 8);
    });

OpenTelemetry

Telemetri sistemi Orleans 7.0'da güncelleştirilir ve önceki sistem ölçümler için .NET Ölçümleri ve izleme için ActivitySource gibi standartlaştırılmış .NET API'leri lehine kaldırılır.

Bunun bir parçası olarak, mevcut Microsoft.Orleans.TelemetryConsumers.* paketleri kaldırılır. Orleans tarafından yayılan ölçümlerin tercih edilen izleme çözümüne entegrasyonunu akıcı hale getirmek için yeni bir paket kümesi ele alınıyor. Her zaman olduğu gibi geri bildirim ve katkılar kabul edilir.

Araç, dotnet-counters geçici sağlık durumu izleme ve birinci düzey performans araştırması için performans izleme özelliğine sahiptir. Sayaçlar için Orleansdotnet-counters aracını kullanarak bunları izleyin:

dotnet counters monitor -n MyApp --counters Microsoft.Orleans

Benzer şekilde, aşağıdaki kodda gösterildiği gibi openTelemetry ölçümlerine Microsoft.Orleans ölçümlerini ekleyin:

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics => metrics
        .AddPrometheusExporter()
        .AddMeter("Microsoft.Orleans"));

Dağıtılmış izlemeyi etkinleştirmek için aşağıdaki kodda gösterildiği gibi OpenTelemetry'yi yapılandırın:

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.SetResourceBuilder(ResourceBuilder.CreateDefault()
            .AddService(serviceName: "ExampleService", serviceVersion: "1.0"));

        tracing.AddAspNetCoreInstrumentation();

        // Good baseline for general Orleans observability
        tracing.AddSource(Orleans.Diagnostics.ActivitySources.ApplicationGrainActivitySourceName);
        tracing.AddSource(Orleans.Diagnostics.ActivitySources.LifecycleActivitySourceName);

        /*
        // Other source also available
        // Persistence spans
        tracing.AddSource(Orleans.Diagnostics.ActivitySources.StorageActivitySourceName);
        // Internal Runtime spans
        tracing.AddSource(Orleans.Diagnostics.ActivitySources.RuntimeActivitySourceName);
        */

        /*
        // Optionally add all Microsoft.Orleans.* Sources at once
        tracing.AddSource(Orleans.Diagnostics.ActivitySources.AllActivitySourceName);
        */

        tracing.AddZipkinExporter(options =>
        {
            options.Endpoint = new Uri("http://localhost:9411/api/v2/spans");
        });
    });

Yukarıdaki kodda, OpenTelemetry aşağıdakileri izlemek üzere yapılandırılmıştır:

  • Microsoft.Orleans.Application
  • Microsoft.Orleans.Lifecycle

Etkinliği yaymak için AddActivityPropagation çağırın.

builder.Host.UseOrleans((_, clientBuilder) =>
{
    clientBuilder.AddActivityPropagation();
});

Özellikleri çekirdek paketten ayrı paketlere yeniden düzenleme

7.0'da Orleans uzantılar, ' Orleans.Corea bağlı olmayan ayrı paketler halinde hesaba katılmıştır. Yani, Orleans.Streaming, Orleans.Remindersve Orleans.Transactions çekirdekten ayrılmıştır. Bu, bu paketlerin yalnızca kullanılanlar için ödeme gerektirdiği ve çekirdek kodun Orleans bu özellikler için ayrılmadığı anlamına gelir. Bu yaklaşım çekirdek API yüzeyini ve montaj boyutunu azaltır, çekirdeği basitleştirir ve performansı artırır. Performansla ilgili olarak, içindeki Orleans işlemler daha önce olası işlemleri koordine etmek için her yöntem için bir kod yürütülmesini gerektiriyormuş. Bu koordinasyon mantığı artık yöntem bazında taşındı.

Bu, derlemeyi bozan bir değişikliktir. Daha önce temel sınıfta tanımlanan Grain yöntemleri çağırarak anımsatıcılarla veya akışlarla etkileşim kuran mevcut kod artık uzantı yöntemleri olduğundan bozulabilir. Uzantı yöntemlerinin nitelenmesi gerektiğinden, this (örn. GetReminders) dahil olacak şekilde this belirtmeyen çağrıları (örn. this.GetReminders()) güncelleyin. Bu çağrılar güncelleştirilmezse bir derleme hatası oluşur ve nelerin değiştiğini bilmeden gerekli kod değişikliği belirgin olmayabilir.

İşlem istemcisi

Orleans 7.0, işlemleri koordine etmek için yeni bir soyutlama sağlar: Orleans.ITransactionClient. Daha önce yalnızca tanecikler işlemleri koordine edebilirdi. ITransactionClient kullanılarak bağımlılık enjeksiyonu ile erişilebildiğinden, istemciler herhangi bir aracı taneciğe ihtiyaç duymadan işlemleri koordine edebilir. Aşağıdaki örnek, kredileri bir hesaptan çeker ve tek bir işlem içinde başka bir hesapta depolar. Bu kodu bir dilimin içinden veya bağımlılık ekleme kapsayıcısından alan ITransactionClient bir dış istemciden çağırın.

await transactionClient.RunTransaction(
  TransactionOption.Create,
  () => Task.WhenAll(from.Withdraw(100), to.Deposit(100)));

İstemci tarafından koordine edilen işlemler için, istemcinin yapılandırma sırasında gerekli hizmetleri eklemesi gerekir:

clientBuilder.UseTransactions();

BankAccount örneği, kullanımını ITransactionClientgösterir. Daha fazla bilgi için bkz Orleans . işlemler.

Çağrı zincirine yeniden girebilme

Grainler tek iş parçacıklıdır ve istekleri varsayılan olarak başından sonuna kadar tek tek işler. Başka bir deyişle, tahıllar varsayılan olarak yeniden giriş yapılmaz. ReentrantAttribute öğesinin bir tahıl sınıfına eklenmesi, tahılın tek işlem yapan bir yapıda kalırken, birden çok isteği birbirine geçmeli bir şekilde eşzamanlı olarak işlemesine olanak tanır. Bu yetenek, iç durumu olmayan veya HTTP çağrıları yapma ya da veritabanına yazma gibi birçok eşzamanlı olmayan işlem gerçekleştiren nesneler için yararlı olabilir. İstekler araya girebildiğinde ek dikkat gerekir: Zaman uyumsuz işlem tamamlanıp yöntem yürütmeye devam edene kadar, bir await ifadesinden önce bir taneciğin durumunun gözlemlenmesi mümkün olsa da bu durum değişebilir.

Örneğin, aşağıdaki dilim bir sayacı temsil eder. Çoğul çağrıların iç içe geçmesine izin verecek şekilde ReentrantAttribute olarak işaretlenir. Increment() yöntemi, dahili sayacı artırmalı ve gözlemlenen değeri döndürmelidir. Ancak, Increment() yöntem gövdesi bir await noktadan önce grain'in durumunu gözlemlediğinden ve daha sonra güncelleştirdiğinden, birden çok iç içe geçmiş yürütme Increment() alınan toplam çağrı sayısından _value daha az sonuç verebilir. Bu, hatalı reentrancy kullanımı nedeniyle ortaya çıkan bir hatadır.

öğesini kaldırmak ReentrantAttribute bu sorunu çözmek için yeterlidir.

[Reentrant]
public sealed class CounterGrain : Grain, ICounterGrain
{
    int _value;

    /// <summary>
    /// Increments the grain's value and returns the previous value.
    /// </summary>
    public Task<int> Increment()
    {
        // Do not copy this code, it contains an error.
        var currentVal = _value;
        await Task.Delay(TimeSpan.FromMilliseconds(1_000));
        _value = currentVal + 1;
        return currentValue;
    }
}

Bu tür hataları önlemek için, tanecikler varsayılan olarak yeniden giriş yapmaz. Dezavantajı, zaman uyumsuz işlemler gerçekleştiren tanecikler için, zaman uyumsuz bir işlemin tamamlanmasını beklerken diğer istekleri işleyememesi nedeniyle aktarım hızının azaltılmasıdır. Bunu hafifletmek için, Orleans belirli durumlarda yeniden girişe izin vermek için çeşitli seçenekler sunar:

  • Sınıfın tamamı için: grene ReentrantAttribute öğesinin yerleştirilmesi, diğer isteklerle örtüşmek üzere tahıla yönelik herhangi bir isteğin yapılmasına olanak tanır.
  • Yöntemlerin bir alt kümesi için: AlwaysInterleaveAttribute'nin tanecik arabirim yöntemine yerleştirilmesi, bu yönteme yönelik isteklerin diğer isteklerle iç içe geçmesine ve diğer isteklerin bu yöntemle iç içe geçmesine olanak tanır.
  • Yöntemlerin bir alt kümesi için: ReadOnlyAttribute tane arabirimi yöntemine yerleştirilmesi, bu yönteme yönelik isteklerin diğer ReadOnlyAttribute isteklerle kesişmesine izin verir ve diğer ReadOnlyAttribute isteklerin bu yönteme yönelik isteklerle kesişmesine olanak tanır. Bu anlamda, AlwaysInterleaveAttribute'in bir biçimi olup daha kısıtlıdır.
  • Bir çağrı zinciri içindeki tüm istekler için: RequestContext.AllowCallChainReentrancy() ve RequestContext.SuppressCallChainReentrancy(), sonraki işlemlerin işleme yeniden girişine izin verme seçeneğine izin verip çıkmasına olanak tanır. her iki çağrı da istekten çıkarken atılması gereken bir değer döndürür. Bu nedenle, bunları aşağıdaki gibi kullanın:
public Task<int> OuterCall(IMyGrain other)
{
    // Allow call-chain reentrancy for this grain, for the duration of the method.
    using var _ = RequestContext.AllowCallChainReentrancy();
    await other.CallMeBack(this.AsReference<IMyGrain>());
}

public Task CallMeBack(IMyGrain grain)
{
    // Because OuterCall allowed reentrancy back into that grain, this method
    // will be able to call grain.InnerCall() without deadlocking.
    await grain.InnerCall();
}

public Task InnerCall() => Task.CompletedTask;

Seçmeli etkinleştirme: Her birim için ve her çağrı zinciri için yeniden girilebilirlik. Örneğin, A tanesi ve B tanesi olmak üzere iki taneyi göz önünde bulundurun. Eğer A tanesi, B tanesini çağırmadan önce çağrı zincirine yeniden girişe olanak sağlıyorsa, B tanesi bu çağrıda A tanesine geri çağrı yapabilir. Ancak, B tanesi de çağrı zinciri girişini etkinleştirmediyse, A tanesi B tanesini geri çağıramaz. Dilim başına, çağrı zinciri başına etkinleştirilir.

Tanecikler ayrıca using var _ = RequestContext.SuppressCallChainReentrancy() kullanarak çağrı zinciri yeniden giriş bilgilerini bir çağrı zincirinin aşağı akmasını engelleyebilir. Bu, sonraki çağrıların yeniden girmesini engeller.

ADO.NET geçiş betikleri

ADO.NET kullanan Orleans kümeleme, kalıcılık ve anımsatıcılarla ileriye doğru uyumluluğu sağlamak için uygun SQL geçiş betiği gereklidir:

Kullanılan veritabanı için dosyaları seçin ve sırayla uygulayın.

3.x'ten Orleans 7.0'a geçiş

3.x kullanıcıları için Orleans , yukarıdaki sürüm seçiciyi Orleans kullanarak 7.0 belgeleri bölümündeki geçiş kılavuzunu izleyin.

Önemli

Orleans 3.x artık desteklenmiyor. En son özellikler ve güvenlik güncelleştirmeleri için 10.0'a Orleans geçiş yapmayı göz önünde bulundurun.

  • Last updated on