Aracılığıyla paylaş

.NET kullanarak Azure Kuyruk Depolamaya başlayın

  • Makale

Genel Bakış

Azure Kuyruk Depolama, uygulama bileşenleri arasında bulut mesajlaşması sağlar. Uygulamaları ölçeklendirmek için tasarlarken, uygulama bileşenleri genellikle birbirinden bağımsız olarak ölçeklenebilmeleri için ayrılır. Kuyruk Depolama bulutta, masaüstünde, şirket içi sunucuda veya mobil cihazda çalışan uygulama bileşenleri arasında zaman uyumsuz mesajlaşma sağlar. Kuyruk Depolama, zaman uyumsuz görevleri yönetmeyi ve süreç iş akışları oluşturmayı da destekler.

Bu öğretici hakkında

Bu öğreticide Azure Kuyruk Depolama kullanarak bazı yaygın senaryolar için .NET kodu yazma işlemi gösterilmektedir. Kapsanan senaryolara kuyruk oluşturma ve silme ile kuyruk iletileri ekleme, okuma ve silme dahildir.

Tahmini tamamlanma süresi: 45 dakika

Önkoşullar

Kuyruk depolama nedir?

Azure Kuyruk depolama, HTTP veya HTTPS kullanan kimlik doğrulaması yapılmış çağrılar aracılığıyla dünyanın her yerinden erişilebilen çok sayıda iletinin depolanması için bir hizmettir. Tek bir kuyruk iletisinin boyutu 64 KB’ye kadar olabilir ve bir kuyrukta, depolama hesabının toplam kapasite sınırına kadar milyonlarca ileti bulunabilir. Kuyruk depolama genellikle zaman uyumsuz olarak işlenmek üzere bir iş kapsamı oluşturmak için kullanılır.

Kuyruk hizmeti kavramları

Azure Kuyruk hizmeti aşağıdaki bileşenleri içerir:

Azure Kuyruk hizmeti bileşenleri

  • Depolama Hesabı: Azure Depolama'ya tüm erişim bir depolama hesabı üzerinden gerçekleştirilir. Depolama hesapları hakkında daha fazla bilgi için bkz. Depolama hesabına genel bakış.

  • Kuyruk: Kuyrukta bir dizi ileti vardır. Tüm iletiler bir kuyrukta olmalıdır. Kuyruk adının tamamen küçük harfli olması gerektiğini unutmayın. Kuyrukların adlandırılması hakkında daha fazla bilgi için bkz. Kuyrukları ve Meta Verileri Adlandırma.

  • İleti: İleti, biçimi ne olursa olsun en çok 64 KB büyüklüktedir. Bir iletinin kuyrukta kalabileceği en uzun süre 7 gündür. Sürüm 2017-07-29 veya üzeri için yaşam süresi üst sınırı herhangi bir pozitif sayı veya iletinin süresinin dolmadığını belirten -1 olabilir. Bu parametre atlanırsa, varsayılan yaşam süresi yedi gündür.

  • URL biçimi: Kuyruklar şu URL biçimi kullanılarak adreslenebilir: http://<storage account>.queue.core.windows.net/<queue>

    Aşağıdaki URL diyagramdaki bir kuyruğun adresini belirtir:

    http://myaccount.queue.core.windows.net/incoming-orders

Azure depolama hesabı oluşturma

İlk Azure depolama hesabınızı oluşturmanın en kolay yolu Azure Portalı’nı kullanmaktır. Daha fazla bilgi için bkz. Depolama hesabı oluşturma.

Azure PowerShell, Azure CLI veya .NET için Azure Depolama Kaynak Sağlayıcısı’nı da kullanarak Azure depolama hesabı oluşturabilirsiniz.

Şu anda Azure'da depolama hesabı oluşturmamayı tercih ediyorsanız, kodunuzu yerel bir ortamda çalıştırmak ve test etmek için Azurite depolama öykünücüsü de kullanabilirsiniz. Daha fazla bilgi için bkz. Yerel Azure Depolama geliştirmesi için Azurite öykünücüsü kullanma.

Geliştirme ortamınızı kurma

Ardından, geliştirme ortamınızı Visual Studio’da ayarlayın; böylece bu kılavuzdaki kod örneklerini denemeye hazır olursunuz.

Windows konsol uygulaması projesi oluşturma

Visual Studio'da yeni bir Windows konsol uygulaması oluşturun. Aşağıdaki adımlarda, Visual Studio 2019'da bir konsol uygulamasının nasıl oluşturulacağı gösterilir. Adımlar Visual Studio’nun diğer sürümlerinde de benzerdir.

  1. Dosya>Yeni Proje'yi> seçin
  2. Platform>Pencereleri'ne tıklayın
  3. Konsol Uygulaması (.NET Framework) seçeneğini belirleyin
  4. İleri’yi seçin
  5. Proje adı alanına uygulamanız için bir ad girin
  6. Oluştur’u seçin

Bu öğreticideki tüm kod örnekleri konsol uygulamanızın Program.cs dosyasındaki Main() yöntemine eklenebilir.

Azure Depolama istemci kitaplıklarını, Azure bulut hizmeti veya web uygulaması ile masaüstü ve mobil uygulamalar da dahil olmak üzere her tür .NET uygulamasında kullanabilirsiniz. Bu kılavuzda, sadeleştirmek için konsol uygulaması kullanmaktayız.

Gereken paketleri yüklemek için NuGet kullanma

Bu öğreticiyi tamamlamak için projenizde aşağıdaki dört pakete başvurmanız gerekir:

Bu paketleri almak için NuGet kullanabilirsiniz. Şu adımları izleyin:

  1. Çözüm Gezgini'da projenize sağ tıklayın ve NuGet Paketlerini Yönet'i seçin.
  2. Gözat'ı seçin
  3. çevrimiçi araması yapın ve Azure Depolama istemci kitaplığını ve bağımlılıklarını yüklemek için Azure.Storage.QueuesYükle'yi seçin. Bu, kuyruk kitaplığının bağımlılıkları olan Azure.Storage.Common ve Azure.Core kitaplıklarını da yükler.
  4. çevrimiçi araması yapın System.Configuration.ConfigurationManagerve yükle'yi seçerek Configuration Manager yükleyin.

Hedef ortamınızı saptama

Bu kılavuzdaki örnekleri çalıştırmak için iki ortam seçeneğiniz vardır:

  • Kodunuzu buluttaki bir Azure Storage hesabına karşı çalıştırabilirsiniz.
  • Kodunuzu Azurite depolama öykünücüsüyle çalıştırabilirsiniz. Azurite, buluttaki bir Azure Depolama hesabına öykünen yerel bir ortamdır. Azurite, uygulamanız geliştirme aşamasındayken kodunuzu test edip hatalarını ayıklamak için ücretsiz bir seçenektir. Öykünücü iyi bilinen hesabı ve anahtarı kullanır. Daha fazla bilgi için bkz. Yerel Azure Depolama geliştirme ve testi için Azurite öykünücüsü kullanma.

Not

Azure Storage ile ilişkili maliyetlerin oluşmasını önlemek için depolama öykünücüsünü hedefleyebilirsiniz. Ancak, buluttaki bir Azure Depolama hesabını hedeflemeyi seçerseniz bu öğreticiyi gerçekleştirme maliyetleri göz ardı edilebilir.

Depolama bağlantı dizenizi alma

.NET için Azure Depolama istemci kitaplıkları, depolama hizmetlerine erişim için uç noktaları ve kimlik bilgilerini yapılandırmak üzere bir depolama bağlantı dizesi kullanılarak desteklenir. Daha fazla bilgi için bkz. Depolama hesabı erişim anahtarlarını yönetme.

Azure portalından kimlik bilgilerinizi kopyalama

Örnek kodun, depolama hesabınıza erişim için yetki vermesi gerekir. Yetki vermek için, depolama hesabınızın kimlik bilgilerini bir bağlantı dizesi şeklinde uygulamaya sağlarsınız. Depolama hesabınızın kimlik bilgilerini görüntülemek için:

  1. Azure portalına gidin.

  2. Depolama hesabınızı bulun.

  3. Depolama hesabına genel bakışın Ayarlar bölümünde Erişim anahtarları’nı seçin. Hesap erişim anahtarlarınız ve her bir anahtar için tam bağlantı dizesi görüntülenir.

  4. key1 bölümünde Bağlantı dizesi değerini bulun ve Kopyala düğmesine tıklayarak bağlantı dizesini kopyalayın. Sonraki adımda bir ortam değişkenine bağlantı dizesini ekleyeceksiniz.

    Azure portalından bağlantı dizesinin kopyalanmasını gösteren ekran görüntüsü

Bağlantı dizeleri hakkında daha fazla bilgi için bkz. Azure Depolama'ya bağlantı dizesi yapılandırma.

Not

Depolama hesabı anahtarınız depolama hesabınızın kök parolasına benzer. Depolama hesabı anahtarınızı korumak için her zaman özen gösterin. Diğer kullanıcılara dağıtmaktan, sabit kodlamaktan ve başkalarının erişebileceği düz metin dosyasına kaydetmekten kaçının. Anahtarınızın tehlikede olduğunu düşünüyorsanız, Azure portalını kullanarak hesap anahtarınızı yeniden oluşturun.

Depolama bağlantı dizenizi korumanın en iyi yolu bir yapılandırma dosyasında tutmaktır. Bağlantı dizenizi yapılandırmak için, app.config dosyasını Visual Studio’daki Çözüm Gezgini'nden açın. Burada gösterilen öğenin içeriğini <appSettings> ekleyin. değerini portaldaki depolama hesabınızdan kopyaladığınız değerle değiştirin connection-string :

<configuration>
    <startup>
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
    </startup>
    <appSettings>
        <add key="StorageConnectionString" value="connection-string" />
    </appSettings>
</configuration>

Örneğin, yapılandırma ayarınız şunun gibi görünür:

<add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=storagesample;AccountKey=GMuzNHjlB3S9itqZJHHCnRkrokLkcSyW7yK9BRbGp0ENePunLPwBgpxV1Z/pVo9zpem/2xSHXkMqTHHLcx8XRA==EndpointSuffix=core.windows.net" />

Azurite depolama öykünücüsü hedeflemek için, iyi bilinen hesap adı ve anahtarıyla eşleyen bir kısayol kullanabilirsiniz. Bu durumda, bağlantı dizesi ayarı şöyle olur:

<add key="StorageConnectionString" value="UseDevelopmentStorage=true" />

Using yönergeleri ekleme

Aşağıdaki using yönergelerini Program.cs dosyasının üst tarafına ekleyin:

using System; // Namespace for Console output
using System.Configuration; // Namespace for ConfigurationManager
using System.Threading.Tasks; // Namespace for Task
using Azure.Identity;
using Azure.Storage.Queues; // Namespace for Queue storage types
using Azure.Storage.Queues.Models; // Namespace for PeekedMessage

Kuyruk Depolama istemcisini oluşturma

sınıfı, QueueClient Kuyruk Depolama'da depolanan kuyrukları almanızı sağlar. Hizmet istemcisini oluşturma yöntemlerinden biri aşağıda verilmiştir:

//-------------------------------------------------
// Create the queue service client
//-------------------------------------------------
public void CreateQueueClient(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to create and manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);
}

İpucu

sınıfını kullanarak gönderdiğiniz iletilerin QueueClient , UTF-8 kodlamalı bir XML isteğine dahil edilebilecek bir biçimde olması gerekir. İsteğe bağlı olarak, uyumlu olmayan iletileri işlemek için MessageEncoding seçeneğini Base64 olarak ayarlayabilirsiniz.

Artık Kuyruk Depolama'dan veri okuyan ve kuyruk depolamaya veri yazan kod yazmaya hazırsınız.

Bir kuyruk oluşturma

Bu örnekte kuyruk oluşturma gösterilmektedir:

//-------------------------------------------------
// Create a message queue
//-------------------------------------------------
public bool CreateQueue(string queueName)
{
    try
    {
        // Get the connection string from app settings
        string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

        // Instantiate a QueueClient which will be used to create and manipulate the queue
        QueueClient queueClient = new QueueClient(connectionString, queueName);

        // Create the queue
        queueClient.CreateIfNotExists();

        if (queueClient.Exists())
        {
            Console.WriteLine($"Queue created: '{queueClient.Name}'");
            return true;
        }
        else
        {
            Console.WriteLine($"Make sure the Azurite storage emulator running and try again.");
            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Exception: {ex.Message}\n\n");
        Console.WriteLine($"Make sure the Azurite storage emulator running and try again.");
        return false;
    }
}

Kuyruğa bir ileti yerleştirme

Var olan kuyruğa ileti eklemek için yöntemini çağırın SendMessage . İleti bir dize (UTF-8 biçiminde) veya bayt dizisi olabilir. Aşağıdaki kod bir kuyruk oluşturur (yoksa) ve bir ileti ekler:

//-------------------------------------------------
// Insert a message into a queue
//-------------------------------------------------
public void InsertMessage(string queueName, string message)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to create and manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    // Create the queue if it doesn't already exist
    queueClient.CreateIfNotExists();

    if (queueClient.Exists())
    {
        // Send a message to the queue
        queueClient.SendMessage(message);
    }

    Console.WriteLine($"Inserted: {message}");
}

Sonraki iletiye gözatın

yöntemini çağırarak PeekMessages kuyruktaki iletileri kuyruktan kaldırmadan göz atabilirsiniz. Parametre için maxMessages bir değer geçirmezseniz, varsayılan değer bir iletiye göz atmaktır.

//-------------------------------------------------
// Peek at a message in the queue
//-------------------------------------------------
public void PeekMessage(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    { 
        // Peek at the next message
        PeekedMessage[] peekedMessage = queueClient.PeekMessages();

        // Display the message
        Console.WriteLine($"Peeked message: '{peekedMessage[0].Body}'");
    }
}

Kuyruğa alınan iletinin içeriğini değiştirme

Kuyrukta yer alan bir iletinin içeriğini değiştirebilirsiniz. Eğer ileti bir iş görevini temsil ediyorsa, bu özelliği kullanarak iş görevinin durumunu güncelleştirebilirsiniz. Aşağıdaki kod kuyruk iletisini yeni içeriklerle güncelleştirir ve görünürlük zaman aşımını 60 saniye daha uzatır. Bu, ileti ile ilişkili işin durumunu kaydeder ve istemciye ileti üzerinde çalışmaya devam etmesi için bir dakika daha zaman verir. Bu tekniği, bir işleme adımı donanım veya yazılım hatası nedeniyle başarısız olursa baştan başlamak zorunda kalmadan kuyruk iletilerinde çok adımlı iş akışlarını izlemek için kullanabilirsiniz. Genellikle bir yeniden deneme sayacı tutmanı gerekir ve bir ileti n seferden daha fazla yeniden denenirse, silebilirsiniz. Bu, her işlendiğinde bir uygulama hatası tetikleyen bir iletiye karşı koruma sağlar.

//-------------------------------------------------
// Update an existing message in the queue
//-------------------------------------------------
public void UpdateMessage(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        // Get the message from the queue
        QueueMessage[] message = queueClient.ReceiveMessages();

        // Update the message contents
        queueClient.UpdateMessage(message[0].MessageId, 
                message[0].PopReceipt, 
                "Updated contents",
                TimeSpan.FromSeconds(60.0)  // Make it invisible for another 60 seconds
            );
    }
}

Sonraki iletiyi dequeue etme

kuyruktaki bir iletiyi iki adımda sıralayın. çağrısı ReceiveMessagesyaptığınızda kuyruktaki bir sonraki iletiyi alırsınız. tarafından ReceiveMessages döndürülen bir ileti, bu kuyruktan gelen iletileri okuyan diğer kodlar için görünmez hale gelir. Varsayılan olarak bu ileti 30 saniye görünmez kalır. kuyruktan iletiyi kaldırmayı tamamlamak için çağrısı da DeleteMessagegerekir. Bir iletinin iki adımlı kaldırılma süreci, donanım veya yazılım arızasından dolayı kodunuzun bir iletiyi işleyememesi durumunda kodunuzun başka bir örneğinin aynı iletiyi alıp yeniden denemesini sağlar. kodunuz, ileti işlendikten hemen sonra çağrır DeleteMessage .

//-------------------------------------------------
// Process and remove a message from the queue
//-------------------------------------------------
public void DequeueMessage(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        // Get the next message
        QueueMessage[] retrievedMessage = queueClient.ReceiveMessages();

        // Process (i.e. print) the message in less than 30 seconds
        Console.WriteLine($"Dequeued message: '{retrievedMessage[0].Body}'");

        // Delete the message
        queueClient.DeleteMessage(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
    }
}

Yaygın Kuyruk Depolama API'leriyle Async-Await desenini kullanma

Bu örnekte yaygın Kuyruk Depolama API'leriyle Async-Await düzeninin nasıl kullanılacağı gösterilmektedir. Örnek, her yöntemin soneki tarafından Async gösterildiği gibi verilen yöntemlerin her birinin zaman uyumsuz sürümünü çağırır. Zaman uyumsuz bir yöntem kullanıldığında, Async-Await düzeni çağrı tamamlanana kadar yerel yürütmeyi askıya alır. Bu davranış geçerli iş parçacığının başka işler yapmasını sağlar ve böylece performans sorunlarını engellemeye yardımcı olur, uygulamanızın genel yanıt hızını iyileştirir. .NET'te Async-Await desenini kullanma hakkında daha fazla ayrıntı için bkz. Async ve Await (C# ve Visual Basic)

//-------------------------------------------------
// Perform queue operations asynchronously
//-------------------------------------------------
public async Task QueueAsync(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    // Create the queue if it doesn't already exist
    await queueClient.CreateIfNotExistsAsync();

    if (await queueClient.ExistsAsync())
    {
        Console.WriteLine($"Queue '{queueClient.Name}' created");
    }
    else
    {
        Console.WriteLine($"Queue '{queueClient.Name}' exists");
    }

    // Async enqueue the message
    await queueClient.SendMessageAsync("Hello, World");
    Console.WriteLine($"Message added");

    // Async receive the message
    QueueMessage[] retrievedMessage = await queueClient.ReceiveMessagesAsync();
    Console.WriteLine($"Retrieved message with content '{retrievedMessage[0].Body}'");

    // Async delete the message
    await queueClient.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
    Console.WriteLine($"Deleted message: '{retrievedMessage[0].Body}'");

    // Async delete the queue
    await queueClient.DeleteAsync();
    Console.WriteLine($"Deleted queue: '{queueClient.Name}'");
}

İletileri sıralamak için ek seçenekleri kullanma

İletilerin bir kuyruktan alınma şeklini iki yöntemle özelleştirebilirsiniz. İlk olarak toplu iletiler alabilirsiniz (en fazla 32). İkinci olarak daha uzun veya daha kısa bir görünmezlik süresi ayarlayarak kodunuzun her iletiyi tamamen işlemesi için daha az veya daha fazla zaman tanıyabilirsiniz.

Aşağıdaki kod örneği, tek bir çağrıda ReceiveMessages 20 ileti almak için yöntemini kullanır. Ardından her iletiyi bir foreach döngü kullanarak işler. Ayrıca her ileti için görünmezlik zaman aşımı beş dakika olarak ayarlanır. Beş dakikanın tüm iletiler için aynı anda başladığını, bu nedenle çağrısının ReceiveMessagesüzerinden beş dakika geçtikten sonra silinmemiş tüm iletilerin yeniden görünür olacağını unutmayın.

//-----------------------------------------------------
// Process and remove multiple messages from the queue
//-----------------------------------------------------
public void DequeueMessages(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        // Receive and process 20 messages
        QueueMessage[] receivedMessages = queueClient.ReceiveMessages(20, TimeSpan.FromMinutes(5));

        foreach (QueueMessage message in receivedMessages)
        {
            // Process (i.e. print) the messages in less than 5 minutes
            Console.WriteLine($"De-queued message: '{message.Body}'");

            // Delete the message
            queueClient.DeleteMessage(message.MessageId, message.PopReceipt);
        }
    }
}

Kuyruk uzunluğu alma

Bir kuyruktaki ileti sayısı ile ilgili bir tahmin alabilirsiniz. yöntemi, GetProperties ileti sayısı da dahil olmak üzere kuyruk özelliklerini döndürür. özelliği, ApproximateMessagesCount kuyruktaki yaklaşık ileti sayısını içerir. Bu sayı kuyruktaki gerçek ileti sayısından düşük değildir, ancak daha yüksek olabilir.

//-----------------------------------------------------
// Get the approximate number of messages in the queue
//-----------------------------------------------------
public void GetQueueLength(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        QueueProperties properties = queueClient.GetProperties();

        // Retrieve the cached approximate message count.
        int cachedMessagesCount = properties.ApproximateMessagesCount;

        // Display number of messages.
        Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");
    }
}

Bir kuyruk silme

Bir kuyruğu ve içindeki tüm iletileri silmek için kuyruk nesnesinde yöntemini çağırın Delete .

//-------------------------------------------------
// Delete the queue
//-------------------------------------------------
public void DeleteQueue(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        // Delete the queue
        queueClient.Delete();
    }

    Console.WriteLine($"Queue deleted: '{queueClient.Name}'");
}

Sonraki adımlar

Kuyruk Depolama'nın temellerini öğrendiğinize göre, daha karmaşık depolama görevleri hakkında bilgi edinmek için bu bağlantıları izleyin.

Kullanım dışı .NET sürüm 11.x SDK'larını kullanan ilgili kod örnekleri için bkz. .NET sürüm 11.x kullanan kod örnekleri.