مشاركة عبر

قم بترحيل تطبيقك لاستخدام Azure Cosmos DB .NET SDK v3

  • مقالة

ينطبق على: NoSQL

هام

للتعرف على Azure Cosmos DB .NET SDK v3، راجعRelease notes، .NET GitHub repository، Performance Tips .NET SDK v3، وTroubleshooting guide.

تسلط هذه المقالة الضوء على بعض اعتبارات ترقية تطبيق .NET الحالي إلى Azure Cosmos DB .NET SDK v3 الأحدث لواجهة برمجة التطبيقات ل NoSQL. يتوافق Azure Cosmos DB .NET SDK v3 مع مساحة اسم Microsoft.Azure.Azure Cosmos DB. تستطيع استخدام المعلومات المقدمة في هذا المستند إذا كنت تقوم بترحيل تطبيقك من أي من حزم Azure Cosmos DB .NET SDK التالية:

  • Azure Cosmos DB .NET Framework SDK v2 لواجهة برمجة التطبيقات ل NoSQL
  • Azure Cosmos DB .NET Core SDK v2 لواجهة برمجة التطبيقات ل NoSQL

تساعدك الإرشادات الواردة في هذه المقالة أيضا على ترحيل المكتبات الخارجية التالية التي أصبحت الآن جزءا من Azure Cosmos DB .NET SDK v3 لواجهة برمجة التطبيقات ل NoSQL:

  • .NET تغيير مكتبة معالج التغذية 2.0
  • مكتبة التعليمات البرمجية المنفذ المجمعة .NET 1.1 أو أحدث

ما الجديد في V3 SDK

تحتوي حزمة V3 SDK على العديد من تحسينات الاستخدام والأداء، بما في ذلك:

  • تسمية نموذج البرمجة بديهية
  • NET قياسي 2.0 **
  • زيادة الأداء من خلال دعم دفق واجهة برمجة التطبيقات
  • تدرج هرمي سلس يحل محل الحاجة إلى مصنع معرف موارد منتظم
  • دعم مدمج لتغيير مكتبة معالج الموجز
  • دعم مدمج للعمليات الجماعية
  • واجهات برمجة تطبيقات قابلة للحركة لتسهيل اختبار الوحدة
  • دفعة المعاملات ودعم Blazor
  • المسلسلات القابلة للتوصيل
  • حاويات مقياس غير مقسمة والتحجيم التلقائي

** تستهدف SDK .NET Standard 2.0 الذي يوحد Azure Cosmos DB .NET Framework و.NET Core SDK في .NET SDK واحد. يمكنك استخدام .NET SDK في أي نظام أساسي يقوم بتنفيذ .NET Standard 2.0، بما في ذلك تطبيقات .NET Framework 4.6.1+ و.NET Core 2.0+.

تظل معظم الشبكات ومنطق إعادة المحاولة والمستويات الأدنى من عدة تطوير البرامج دون تغيير إلى حد كبير.

الإصدار 3 من Azure Cosmos قاعدة بيانات .NET عدة تطوير البرامج هو الآن مفتوح المصدر. نرحب بأي طلبات سحب وستُسجل المشاكل وتُتتبع الملاحظات على GitHub. سنعمل على الاستفادة من أي ميزات من شأنها تحسين تجربة العملاء.

لماذا الانتقال إلى .NET v3 SDK

بالإضافة إلى التحسينات العديدة في قابلية الاستخدام والأداء، لن يتم نقل استثمارات الميزات الجديدة التي تم إجراؤها في أحدث SDK إلى منافذ الإصدارات القديمة. عدة تطوير البرامج v2 في وضع الصيانة حاليًا. للحصول على أفضل تجربة تطوير، نوصي بالبدء دائمًا بأحدث إصدار مدعوم من عدة تطوير البرامج.

يتغير الاسم الرئيسي من v2 SDK إلى v3 SDK

تم تطبيق تغييرات الاسم التالية عبر .NET 3.0 SDK للتوافق مع اصطلاحات تسمية واجهة برمجة التطبيقات لواجهة برمجة التطبيقات ل NoSQL:

  • DocumentClientتمت إعادة تسميته إلىCosmosClient
  • Collectionتمت إعادة تسميته إلىContainer
  • Documentتمت إعادة تسميته إلىItem

تتم إعادة تسمية جميع كائنات الموارد بخصائص إضافية، والتي تتضمن اسم المورد للتوضيح.

فيما يلي بعض التغييرات الرئيسية في اسم الفئة:

عدة تطوير البرامج .NET v2 .NET v3 SDK
Microsoft.Azure.Documents.Client.DocumentClient Microsoft.Azure.Cosmos.CosmosClient
Microsoft.Azure.Documents.Client.ConnectionPolicy Microsoft.Azure.Cosmos.CosmosClientOptions
Microsoft.Azure.Documents.Client.DocumentClientException Microsoft.Azure.Cosmos.CosmosException
Microsoft.Azure.Documents.Client.Database Microsoft.Azure.Cosmos.DatabaseProperties
Microsoft.Azure.Documents.Client.DocumentCollection Microsoft.Azure.Cosmos.ContainerProperties
Microsoft.Azure.Documents.Client.RequestOptions Microsoft.Azure.Cosmos.ItemRequestOptions
Microsoft.Azure.Documents.Client.FeedOptions Microsoft.Azure.Cosmos.QueryRequestOptions
Microsoft.Azure.Documents.Client.StoredProcedure Microsoft.Azure.Cosmos.StoredProcedureProperties
Microsoft.Azure.Documents.Client.Trigger Microsoft.Azure.Cosmos.TriggerProperties
Microsoft.Azure.Documents.SqlQuerySpec Microsoft.Azure.Cosmos.QueryDefinition

تم استبدال الفئات في .NET v3 SDK

تم استبدال الفئات التالية على عدة تطوير البرامج 3.0:

  • Microsoft.Azure.Documents.UriFactory

تم استبدال فئة Microsoft.Azure.Documents.UriFactory بالتصميم الفائق.

Container container = client.GetContainer(databaseName,containerName);
ItemResponse<SalesOrder> response = await this._container.CreateItemAsync(
        salesOrder,
        new PartitionKey(salesOrder.AccountNumber));
  • Microsoft.Azure.Documents.Document

نظرا لأن .NET v3 SDK يسمح للمستخدمين بتكوين محرك تسلسل مخصص، فلا يوجد بديل مباشر للنوع Document . عند استخدام Newtonsoft.Json (محرك إنشاء تسلسل افتراضي)، يُمكن استخدام JObject لتحقيق نفس الوظيفة. عند استخدام محرك إنشاء تسلسل مختلف، يمكنك استخدام نوع المستند json الأساسي الخاص به (على سبيل المثال، JsonDocument لـ System.Text.Json). يُوصى باستخدام نوع #C الذي يعكس مخطط العناصر بدلًا من الاعتماد على أنواع عامة.

  • Microsoft.Azure.Documents.Resource

لا يوجد استبدال مباشر ل Resource، في الحالات التي تم استخدامها للمستندات، اتبع إرشادات ل Document.

  • Microsoft.Azure.Documents.AccessCondition

IfNoneMatch أو IfMatch متوفرة الآن على Microsoft.Azure.Cosmos.ItemRequestOptions مباشرة.

التغييرات في إنشاء معرف العنصر

لم يعد يتم ملء معرف العنصر تلقائيًا في .NET v3 SDK. لذلك، يجب أن يتضمن معرف العنصر على وجه التحديد معرفًا تم إنشاؤه. عرض المثال التالي:

[JsonProperty(PropertyName = "id")]
public Guid Id { get; set; }

تم تغيير السلوك الافتراضي لوضع الاتصال

يتم الآن تعيين SDK v3 افتراضيا إلى أوضاع اتصال Direct + TCP مقارنة ب v2 SDK السابق، والذي تم تعيينه افتراضيا على أوضاع اتصالات البوابة + HTTPS. يوفر هذا التغيير أداءً محسنًا وقابلية التوسع.

تغييرات في FeedOptions (QueryRequestOptions في SDK v3.0)

تمت الآن FeedOptionsإعادة تسمية الفئة في SDK v2QueryRequestOptions في SDK v3 وداخل الفئة، تم تغيير العديد من الخصائص في الاسم و / أو القيمة الافتراضية أو تمت إزالتها تمامًا.

عدة تطوير البرامج .NET v2 .NET v3 SDK
FeedOptions.MaxDegreeOfParallelism QueryRequestOptions.MaxConcurrency - تظل القيمة الافتراضية والسلوك المقترن كما هي، وسيتم تنفيذ العمليات التي يتم تشغيلها من جانب العميل أثناء تنفيذ الاستعلام المتوازي بشكل تسلسلي دون توازي.
FeedOptions.PartitionKey QueryRequestOptions.PartitionKey - تم الحفاظ على السلوك.
FeedOptions.EnableCrossPartitionQuery إزالة. السلوك الافتراضي في SDK 3.0 هو أنه سيتم تنفيذ الاستعلامات عبر الأقسام دون الحاجة إلى تمكين الخاصية على وجه التحديد.
FeedOptions.PopulateQueryMetrics إزالة. يتم تمكينه الآن بشكل افتراضي وجزء من التشخيص.
FeedOptions.RequestContinuation إزالة. يتم الآن ترقيته إلى أساليب الاستعلام نفسها.
FeedOptions.JsonSerializerSettings إزالة. راجع كيفية تخصيص التسلسل للحصول على معلومات إضافية.
FeedOptions.PartitionKeyRangeId إزالة. يمكن الحصول على نفس النتيجة من استخدام FeedRange كمدخل إلى أسلوب الاستعلام.
FeedOptions.DisableRUPerMinuteUsage إزالة.

بناء العميل

يوفر .NET SDK v3 CosmosClientBuilder فئة طلاقة تحل محل الحاجة إلى عدة تطوير البرامج v2 URI Factory.

يبني التصميم السلس عناوين URL داخليًا ويسمح بتمريرContainer كائن واحد بدلاً منDocumentClient، DatabaseName، وDocumentCollection.

ينشئ المثال التالي جديدًا CosmosClientBuilderبمستوى تناسق قوي وقائمة بالمواقع المفضلة:

CosmosClientBuilder cosmosClientBuilder = new CosmosClientBuilder(
    accountEndpoint: "https://testcosmos.documents.azure.com:443/",
    authKeyOrResourceToken: "SuperSecretKey")
.WithConsistencyLevel(ConsistencyLevel.Strong)
.WithApplicationRegion(Regions.EastUS);
CosmosClient client = cosmosClientBuilder.Build();

استثناءات

في حالة استخدام v2 SDK DocumentClientExceptionللإشارة إلى الأخطاء في أثناء العملياتCosmosException، يستخدم الإصدار v3 SDK، والذي يعرضStatusCode،Diagnostics، والمعلومات الأخرى المتعلقة بالاستجابة. يتم إجراء تسلسل لجميع المعلومات الكاملة عند ToString()استخدامها:

catch (CosmosException ex)
{
    HttpStatusCode statusCode = ex.StatusCode;
    CosmosDiagnostics diagnostics = ex.Diagnostics;
    // store diagnostics optionally with diagnostics.ToString();
    // or log the entire error details with ex.ToString();
}

التشخيصات

عندما يكون لدى v2 SDK تشخيصات مباشرة فقط متاحة من خلال RequestDiagnosticsStringالخاصية، فإن v3 SDK تستخدمهDiagnostics متاحة في جميع الاستجابات والاستثناءات، والتي تكون أكثر ثراءً ولا تقتصر على الوضع المباشر. وهي لا تشمل فقط الوقت المستغرق في SDK للعملية، ولكن أيضًا المناطق التي اتصلت بها العملية:

try
{
    ItemResponse<MyItem> response = await container.ReadItemAsync<MyItem>(
                    partitionKey: new PartitionKey("MyPartitionKey"),
                    id: "MyId");
    
    TimeSpan elapsedTime = response.Diagnostics.GetElapsedTime();
    if (elapsedTime > somePreDefinedThreshold)
    {
        // log response.Diagnostics.ToString();
        IReadOnlyList<(string region, Uri uri)> regions = response.Diagnostics.GetContactedRegions();
    }
}
catch (CosmosException cosmosException) {
    string diagnostics = cosmosException.Diagnostics.ToString();
    
    TimeSpan elapsedTime = cosmosException.Diagnostics.GetElapsedTime();
    
    IReadOnlyList<(string region, Uri uri)> regions = cosmosException.Diagnostics.GetContactedRegions();
    
    // log cosmosException.ToString()
}

سياسة الاتصال

تمت إعادة تسمية بعض الإعدادات في ConnectionPolicy أو استبدالها ب CosmosClientOptions:

عدة تطوير البرامج .NET v2 .NET v3 SDK
EnableEndpointDiscovery LimitToEndpoint- القيمة مقلوبة الآن، إذاEnableEndpointDiscovery تم ضبطها علىtrue، LimitToEndpointيجب ضبطها علىfalse. قبل استخدام هذا الإعداد، تحتاج إلى فهم كيفية تأثيره على العميل.
ConnectionProtocol إزالة. يرتبط البروتوكول بالوضع، إما أنه بوابة (HTTPS) أو مباشر (TCP). لم يعد الوضع المباشر مع بروتوكول HTTPS مدعومًا على V3 SDK والتوصية هي استخدام بروتوكول TCP.
MediaRequestTimeout إزالة. المرفقات لم تعد مدعومة.
SetCurrentLocation CosmosClientOptions.ApplicationRegion من الممكن استخدامها لتحقيق نفس التأثير.
PreferredLocations CosmosClientOptions.ApplicationPreferredRegions من الممكن استخدامها لتحقيق نفس التأثير.
UserAgentSuffix CosmosClientBuilder.ApplicationName من الممكن استخدامها لتحقيق نفس التأثير.
UseMultipleWriteLocations إزالة. يكتشف SDK تلقائيا ما إذا كان الحساب يدعم نقاط نهاية كتابة متعددة.

سياسة الفهرسة

في نهج الفهرسة، لا يمكن تكوين هذه الخصائص. عندما لا يتم تحديد هذه الخصائص، ستحتوي الآن دائمًا على القيم التالية:

اسم الخاصية قيمة جديدة (غير قابلة للتكوين)
Kind range
dataType String وNumber

راجع هذا القسم للاطلاع على أمثلة سياسة الفهرسة لتضمين المسارات واستبعادها. نظرًا إلى التحسينات في محرك الاستعلام، فإن تكوين هذه الخصائص، حتى في حالة استخدام إصدار أقدم من عدة تطوير البرامج، ليس له أي تأثير على الأداء.

رمز الجلسة المميز

حيث تعرض v2 SDK الرمز المميز للجلسة للاستجابة كما هوResourceResponse.SessionTokenالحال في الحالات التي كان من الضروري فيها التقاط الرمز المميز للجلسة، نظرًا إلى أن الرمز المميز للجلسة هو العنوان، فإن v3 SDK يعرض هذه القيمة في خاصية Headers.Sessionلأي استجابة.

طابع زمني

حيث تعرض v2 SDK الطابع الزمني للمستند من خلالTimestampالخاصية، لأنهDocument لم يعد متاحًا، يمكن للمستخدمين تعيين_ts خاصية النظام إلى خاصية في نموذجهم.

OpenAsync

بالنسبة إلى حالات الاستخدام التيOpenAsync() تم استخدامها لتسخين عميل v2 SDK،CreateAndInitializeAsync يمكن استخدامها لإنشاء عميل v3 SDK وتهيئته.

استخدام واجهات برمجة التطبيقات لمعالج تغذية التغيير مباشرة من v3 SDK

يحتوي v3 SDK على دعم مضمن لواجهات برمجة تطبيقات معالج تغيير التغذية، ما يسمح لك باستخدام نفس عدة تطوير البرامج لبناء تطبيقك وتغيير تنفيذ معالج التغذية. في السابق، كان عليك استخدام مكتبة معالج موجز التغيير المنفصل.

لمزيد من المعلومات، راجع كيفية الترحيل من مكتبة معالج موجز التغيير إلى Azure Cosmos DB .NET v3 SDK

استعلامات موجز التغير

يعتبر تنفيذ استعلامات موجز التغيير على v3 SDK يستخدم نموذج سحب موجز التغيير. اتبع هذا الجدول لكي يتم ترحيل التكوين:

عدة تطوير البرامج .NET v2 .NET v3 SDK
ChangeFeedOptions.PartitionKeyRangeId FeedRange - من أجل تحقيق التوازي قراءة موجز التغيير يمكن استخدام FeedRanges . لم تعد المعلمة مطلوبة، يمكنك قراءة تغيير موجز لحاوية بأكملها بسهولة الآن.
ChangeFeedOptions.PartitionKey FeedRange.FromPartitionKey - يمكن استخدام FeedRange يمثل مفتاح القسم المطلوب لقراءة موجز التغيير الخاص بقيمة مفتاح القسم هذه.
ChangeFeedOptions.RequestContinuation ChangeFeedStartFrom.Continuation - يمكن إيقاف عداد موجز التغيير واستئنافه في أي وقت عن طريق حفظ الاستمرارية واستخدامه عند إنشاء عداد جديد.
ChangeFeedOptions.StartTime ChangeFeedStartFrom.Time
ChangeFeedOptions.StartFromBeginning ChangeFeedStartFrom.Beginning
ChangeFeedOptions.MaxItemCount ChangeFeedRequestOptions.PageSizeHint - يمكن إيقاف عداد موجز التغيير واستئنافه في أي وقت عن طريق حفظ الاستمرارية واستخدامه عند إنشاء عداد جديد.
IDocumentQuery.HasMoreResults response.StatusCode == HttpStatusCode.NotModified - موجز التغيير غير محدود من الناحية المفاهيمية، لذلك يمكن أن يكون هناك دائما المزيد من النتائج. عندما تحتوي الاستجابة على HttpStatusCode.NotModified تعليمة برمجية الحالة، فهذا يعني أنه لا توجد تغييرات جديدة للقراءة في الوقت الحالي. تستطيع استخدام ذلك لإيقاف وحفظ المتابعة أو للنوم مؤقتا أو الانتظار ثم الاتصال ReadNextAsync مرة أخرى لاختبار التغييرات الجديدة.
عملية معالجة الانقسام لم يعد مطلوبا من المستخدمين التعامل مع استثناءات الانقسام عند قراءة موجز التغيير وسيتم التعامل مع الانقسامات بشفافية دون الحاجة إلى تفاعل المستخدم.

استخدام مكتبة المنفذ بالجملة مباشرة من V3 SDK

يحتوي V3 SDK على دعم مضمن لمكتبة المنفذ بالجملة، مما يسمح لك باستخدام نفس عدة تطوير البرامج لبناء تطبيقك وتنفيذ عمليات مجمعة. في السابق، كان مطلوبًا منك استخدام مكتبة منفذة مجمعة منفصلة.

لمزيد من المعلومات، راجع كيفية الترحيل من مكتبة منفذ مجمعة إلى دعم مجمع في Azure Cosmos DB .NET V3 SDK

تخصيص التسلسل

يسمح .NET V2 SDK بتعيين JsonSerializerSettings في RequestOptions على المستوى التشغيلي المستخدم لإلغاء تسلسل مستند النتيجة:

// .NET V2 SDK
var result = await container.ReplaceDocumentAsync(document, new RequestOptions { JsonSerializerSettings = customSerializerSettings })

يوفر .NET SDK v3 واجهة مسلسل لتخصيص محرك التسلسل بالكامل، أو خيارات تسلسل أكثر عمومية كجزء من بناء العميل.

يمكن تحقيق تخصيص التسلسل على مستوى العملية من خلال استخدام واجهات برمجة تطبيقات Stream:

// .NET V3 SDK
using(Response response = await this.container.ReplaceItemStreamAsync(stream, "itemId", new PartitionKey("itemPartitionKey"))
{

    using(Stream stream = response.ContentStream)
    {
        using (StreamReader streamReader = new StreamReader(stream))
        {
            // Read the stream and do dynamic deserialization based on type with a custom Serializer
        }
    }
}

مقارنات قصاصة برمجية

يوضح مقتطف الشفرة التالي الاختلافات في كيفية إنشاء الموارد بين .NET v2 وv3 SDK:

عمليات قاعدة البيانات

إنشاء قاعدة بيانات

// Create database with no shared provisioned throughput
DatabaseResponse databaseResponse = await client.CreateDatabaseIfNotExistsAsync(DatabaseName);
Database database = databaseResponse;
DatabaseProperties databaseProperties = databaseResponse;

// Create a database with a shared manual provisioned throughput
string databaseIdManual = new string(DatabaseName + "_SharedManualThroughput");
database = await client.CreateDatabaseIfNotExistsAsync(databaseIdManual, ThroughputProperties.CreateManualThroughput(400));

// Create a database with shared autoscale provisioned throughput
string databaseIdAutoscale = new string(DatabaseName + "_SharedAutoscaleThroughput");
database = await client.CreateDatabaseIfNotExistsAsync(databaseIdAutoscale, ThroughputProperties.CreateAutoscaleThroughput(4000));

قراءة قاعدة البيانات عن طريق المعرف

// Read a database
Console.WriteLine($"{Environment.NewLine} Read database resource: {DatabaseName}");
database = client.GetDatabase(DatabaseName);
Console.WriteLine($"{Environment.NewLine} database { database.Id.ToString()}");

// Read all databases
string findQueryText = "SELECT * FROM c";
using (FeedIterator<DatabaseProperties> feedIterator = client.GetDatabaseQueryIterator<DatabaseProperties>(findQueryText))
{
    while (feedIterator.HasMoreResults)
    {
        FeedResponse<DatabaseProperties> databaseResponses = await feedIterator.ReadNextAsync();
        foreach (DatabaseProperties _database in databaseResponses)
        {
            Console.WriteLine($"{ Environment.NewLine} database {_database.Id.ToString()}");
        }
    }
}

احذف قاعدة بيانات

// Delete a database
await client.GetDatabase(DatabaseName).DeleteAsync();
Console.WriteLine($"{ Environment.NewLine} database {DatabaseName} deleted.");

// Delete all databases in an account
string deleteQueryText = "SELECT * FROM c";
using (FeedIterator<DatabaseProperties> feedIterator = client.GetDatabaseQueryIterator<DatabaseProperties>(deleteQueryText))
{
    while (feedIterator.HasMoreResults)
    {
        FeedResponse<DatabaseProperties> databaseResponses = await feedIterator.ReadNextAsync();
        foreach (DatabaseProperties _database in databaseResponses)
        {
            await client.GetDatabase(_database.Id).DeleteAsync();
            Console.WriteLine($"{ Environment.NewLine} database {_database.Id} deleted");
        }
    }
}

عمليات الحاوية

إنشاء حاوية (مقياس تلقائي + وقت العيش مع انتهاء الصلاحية)

private static async Task CreateManualThroughputContainer(Database database)
{
    // Set throughput to the minimum value of 400 RU/s manually configured throughput
    string containerIdManual = ContainerName + "_Manual";
    ContainerResponse container = await database.CreateContainerIfNotExistsAsync(
        id: containerIdManual,
        partitionKeyPath: partitionKeyPath,
        throughput: 400);
}

// Create container with autoscale
private static async Task CreateAutoscaleThroughputContainer(Database database)
{
    string autoscaleContainerId = ContainerName + "_Autoscale";
    ContainerProperties containerProperties = new ContainerProperties(autoscaleContainerId, partitionKeyPath);

    Container container = await database.CreateContainerIfNotExistsAsync(
        containerProperties: containerProperties,
        throughputProperties: ThroughputProperties.CreateAutoscaleThroughput(autoscaleMaxThroughput: 4000);
}

// Create a container with TTL Expiration
private static async Task CreateContainerWithTtlExpiration(Database database)
{
    string containerIdManualwithTTL = ContainerName + "_ManualTTL";

    ContainerProperties properties = new ContainerProperties
        (id: containerIdManualwithTTL,
        partitionKeyPath: partitionKeyPath);

    properties.DefaultTimeToLive = (int)TimeSpan.FromDays(1).TotalSeconds; //expire in 1 day

    ContainerResponse containerResponse = await database.CreateContainerIfNotExistsAsync(containerProperties: properties);
    ContainerProperties returnedProperties = containerResponse;
}

اقرأ خصائص الحاوية

private static async Task ReadContainerProperties(Database database)
{
    string containerIdManual = ContainerName + "_Manual";
    Container container = database.GetContainer(containerIdManual);
    ContainerProperties containerProperties = await container.ReadContainerAsync();
}

احذف حاوية

private static async Task DeleteContainers(Database database)
{
    string containerIdManual = ContainerName + "_Manual";

    // Delete a container
    await database.GetContainer(containerIdManual).DeleteContainerAsync();

    // Delete all CosmosContainer resources for a database
    using (FeedIterator<ContainerProperties> feedIterator = database.GetContainerQueryIterator<ContainerProperties>())
    {
        while (feedIterator.HasMoreResults)
        {
            foreach (ContainerProperties _container in await feedIterator.ReadNextAsync())
            {
                await database.GetContainer(_container.Id).DeleteContainerAsync();
                Console.WriteLine($"{Environment.NewLine}  deleted container {_container.Id}");
            }
        }
    }
}

عمليات العنصر والاستعلام

إنشاء عنصر

private static async Task CreateItemAsync(Container container)
{
    // Create a SalesOrder POCO object
    SalesOrder salesOrder1 = GetSalesOrderSample("Account1", "SalesOrder1");
    ItemResponse<SalesOrder> response = await container.CreateItemAsync(salesOrder1,
        new PartitionKey(salesOrder1.AccountNumber));
}

private static async Task RunBasicOperationsOnDynamicObjects(Container container)
{
    // Dynamic Object
    dynamic salesOrder = new
    {
        id = "SalesOrder5",
        AccountNumber = "Account1",
        PurchaseOrderNumber = "PO18009186470",
        OrderDate = DateTime.UtcNow,
        Total = 5.95,
    };
    Console.WriteLine("\nCreating item");
    ItemResponse<dynamic> response = await container.CreateItemAsync<dynamic>(
        salesOrder, new PartitionKey(salesOrder.AccountNumber));
    dynamic createdSalesOrder = response.Resource;
}

اقرأ جميع العناصر الموجودة في الحاوية

private static async Task ReadAllItems(Container container)
{
    // Read all items in a container
    List<SalesOrder> allSalesForAccount1 = new List<SalesOrder>();

    using (FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
        queryDefinition: null,
        requestOptions: new QueryRequestOptions()
        {
            PartitionKey = new PartitionKey("Account1"),
            MaxItemCount = 5
        }))
    {
        while (resultSet.HasMoreResults)
        {
            FeedResponse<SalesOrder> response = await resultSet.ReadNextAsync();
            SalesOrder salesOrder = response.First();
            Console.WriteLine($"\n1.3.1 Account Number: {salesOrder.AccountNumber}; Id: {salesOrder.Id}");
            allSalesForAccount1.AddRange(response);
        }
    }
}

عناصر الاستعلام

التغييرات في SqlQuerySpec (QueryDefinition في v3.0 SDK)

تمت الآن إعادةSqlQuerySpec تسمية الفئة في SDK v2QueryDefinition إلى SDK v3.

SqlParameterCollection و SqlParameter تمت إزالتها. تتم الآن إضافة المعلمات إلى QueryDefinition النموذج المنشئ باستخدام QueryDefinition.WithParameter. يستطيع المستخدمين الوصول إلى المعلمات باستخدام QueryDefinition.GetQueryParameters

private static async Task QueryItems(Container container)
{
    // Query for items by a property other than Id
    QueryDefinition queryDefinition = new QueryDefinition(
        "select * from sales s where s.AccountNumber = @AccountInput")
        .WithParameter("@AccountInput", "Account1");

    List<SalesOrder> allSalesForAccount1 = new List<SalesOrder>();
    using (FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
        queryDefinition,
        requestOptions: new QueryRequestOptions()
        {
            PartitionKey = new PartitionKey("Account1"),
            MaxItemCount = 1
        }))
    {
        while (resultSet.HasMoreResults)
        {
            FeedResponse<SalesOrder> response = await resultSet.ReadNextAsync();
            SalesOrder sale = response.First();
            Console.WriteLine($"\n Account Number: {sale.AccountNumber}; Id: {sale.Id};");
            allSalesForAccount1.AddRange(response);
        }
    }
}

حذف عنصر

private static async Task DeleteItemAsync(Container container)
{
    ItemResponse<SalesOrder> response = await container.DeleteItemAsync<SalesOrder>(
        partitionKey: new PartitionKey("Account1"), id: "SalesOrder3");
}

استعلامات موجز التغير

private static async Task QueryChangeFeedAsync(Container container)
{
    FeedIterator<SalesOrder> iterator = container.GetChangeFeedIterator<SalesOrder>(ChangeFeedStartFrom.Beginning(), ChangeFeedMode.Incremental);

    string continuation = null;
    while (iterator.HasMoreResults)
    {
        FeedResponse<SalesOrder> response = await iteratorForTheEntireContainer.ReadNextAsync();
    
        if (response.StatusCode == HttpStatusCode.NotModified)
        {
            // No new changes
            continuation = response.ContinuationToken;
            break;
        }
        else 
        {
            // Process the documents in response
        }
    }
}

الخطوات التالية