تمرين: تخزين البيانات محليا باستخدام SQLite

15 دقائق

في هذا التمرين، ستستخدم SQLite لتخزين المعلومات محليا مع أحد التطبيقات. في نموذج السيناريو، قررت تخزين البيانات مؤقتا لتطبيق الوسائط الاجتماعية لتحسين الاستجابة. ينشئ هذا التمرين ويستخدم قاعدة بيانات SQLite محلية لتخزين معلومات حول الأشخاص. ستحفظ ملف قاعدة البيانات الفعلي في التخزين المحلي.

تستخدم هذه الوحدة النمطية .NET 8.0 SDK. تأكد من تثبيت .NET 8.0 عن طريق تشغيل الأمر التالي في الوحدة الطرفية للأوامر المفضلة لديك:

dotnet --list-sdks

يظهر إخراج مشابه للمثال التالي:

6.0.317 [C:\Program Files\dotnet\sdk]
7.0.401 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

تأكد من إدراج إصدار يبدأ بـ 8. إذا لم يتم سرد أي منها أو لم يتم العثور على الأمر، فقم بتثبيت أحدث .NET 8.0 SDK.

افتح حل المبتدئين

استنساخ أو تحميل exercise repo.

إشعار

من الأفضل استنساخ محتوى التمرين إلى مسار مجلد قصير، مثل C:\dev، لتجنب تجاوز طول المسار الأقصى للملفات التي تم إنشاؤها.
استخدم Visual Studio لفتح الحل الأشخاص.sln، والذي ستجده في mslearn-dotnetmaui-store-local-data> الأشخاص، أو مجلد البداية في Visual Studio Code.

إشعار

لا تحاول بناء الحل حتى الآن. التعليمات البرمجية غير مكتملة ولن يتم تحويلها برمجيا حتى تضيف العناصر المفقودة لاحقا في هذا التمرين.

تعريف كيان SQLite

انقر بزر الماوس الأيمن فوق مشروع الأشخاص، وحدد إضافة، ثم حدد مجلد جديد لإضافة مجلد جديد إلى المشروع. قم بتسمية المجلد الجديد Models.
انقر بزر الماوس الأيمن فوق مجلد Models ، وحدد Add، وحدد Class. تأكد من تحديد الفئة في القائمة، ثم قم بتسمية الفئة الجديدة Person.cs. حدد إضافة.
تعديل الفئة ووضع علامة عليها ك public:
```
namespace People.Models;

public class Person
{
}
```
أضف خاصية int تسمى Id إلى Person الفئة .

إضافة خاصية string تسمى Name. يجب أن تبدو الفئة كما يلي:

namespace People.Models;

public class Person
{
    public int Id { get; set; }
    public string Name { get; set; }
}

احفظ الملف Person.cs.

إضافة مكتبة SQLite

انقر بزر الماوس الأيمن فوق عقدة مشروع الأشخاص من مستكشف الحلول في Visual Studio.
في قائمة السياق التي تظهر، حدد Manage NuGet Packages.
ابحث عن sqlite-net-pcl وحدده، ثم حدد Install.
ابحث أيضا عن SQLitePCLRaw.bundle_green وحددها، ثم حدد تثبيت.

إذا كنت تستخدم Visual Studio Code، فافتح المحطة الطرفية وهذه الحزم باستخدام الأوامر التالية:

dotnet add package sqlite-net-pcl
dotnet add package SQLitePCLRaw.bundle_green

إضافة سمات SQLite

في ملف Person.cs ، أضف توجيها using لمساحة SQLite الاسم إلى ملف الفئة Person . يتيح لك هذا التوجيه استخدام سمات SQLite.
```
using SQLite;

namespace People.Models;

public class Person
{
    ...
}
```
قم بتعليق Person الفئة بالسمة [Table] ، وحدد اسم الجدول ك people.
حدد الخاصية Id كمفتاح أساسي. قم بتعليقها مع [PrimaryKey] السمتين و [AutoIncrement] .
إضافة تعليقات توضيحية إلى الخاصية Name . حددها MaxLength ك 250. حدد أن كل قيمة في العمود يجب أن تكون Unique.

يجب أن تبدو الفئة المكتملة كما يلي:
```
using SQLite;

namespace People.Models;

[Table("people")]
public class Person
{
    [PrimaryKey, AutoIncrement]
    public int Id { get; set; }

    [MaxLength(250), Unique]
    public string Name { get; set; }
}
```
احفظ الملف Person.cs.

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

افتح الملف PersonRepository.cs .
PersonRepository فحص الفئة. تحتوي هذه الفئة على تعليمة برمجية هيكلية غير مكتملة مع TODO علامات حيث ستضيف الوظيفة للوصول إلى قاعدة البيانات.
using أضف توجيها لمساحات SQLite الأسماء و People.Models إلى ملف الفئة PersonRepository.cs .
أضف حقلا خاصا SQLiteConnection باسم conn إلى الفئة، أعلى الدالة Init .
في الدالة Init ، تحقق لمعرفة ما إذا كان conn لا يساوي null. إذا كان الأمر كذلك، فارجع على الفور.
```
if (conn != null)
    return;
```
بهذه الطريقة، يتم تشغيل التعليمة البرمجية للتهيئة لقاعدة بيانات SQLite مرة واحدة فقط.
تهيئة conn الحقل للاتصال بقاعدة البيانات باستخدام _dbPath المتغير .

conn.CreateTable استخدم الأسلوب لإنشاء جدول لتخزين Person البيانات. يجب أن تبدو الدالة المكتملة Init كما يلي:

using SQLite;
using People.Models;
...

private SQLiteConnection conn;
...
private void Init()
{
   if (conn != null)
      return;

   conn = new SQLiteConnection(_dbPath);
   conn.CreateTable<Person>();
}

إدراج صف في قاعدة البيانات

في PersonRepository الفئة ، ابحث عن AddNewPerson الأسلوب .
TODO استبدل التعليق في هذا الأسلوب بالتعليمات البرمجية لإدراج كائن جديدPerson. تستدعي Init التعليمات البرمجية أولا للتحقق من تهيئة قاعدة البيانات، ثم تستخدم SQLiteConnection أسلوب الكائن Insert . result تعيين المتغير إلى القيمة التي يرجعها Insert الأسلوب، كما هو موضح في التعليمات البرمجية التالية:
```
public void AddNewPerson(string name)
{
    int result = 0;
    try
    {
        // enter this line
        Init();

        // basic validation to ensure a name was entered
        if (string.IsNullOrEmpty(name))
            throw new Exception("Valid name required");

        // enter this line
        result = conn.Insert(new Person { Name = name });
        ...
    }
    ...
}
```

استرداد الصفوف من قاعدة البيانات

في PersonRepository الفئة ، ابحث عن GetAllPeople الأسلوب .
استدعاء Init للتحقق من تهيئة قاعدة البيانات.
استخدم الأسلوب العام Table\<T> لاسترداد كافة الصفوف في الجدول. حدد Person كمعلمة النوع.
استخدم أسلوب الملحق ToList() لتحويل النتيجة إلى مجموعة List\<Person> وإرجاع هذه المجموعة.
أضف معالجة الأخطاء عن طريق التفاف التعليمات البرمجية في كتلة try-catch . إذا كان هناك خطأ، فقم بتعيين الخاصية StatusMessage إلى خاصية الاستثناء Message وإرجاع مجموعة فارغة. يجب أن يبدو الأسلوب المكتمل كما يلي:
```
public List<Person> GetAllPeople()
{
   try
   {
      Init();
      return conn.Table<Person>().ToList();
   }
   catch (Exception ex)
   {
      StatusMessage = string.Format("Failed to retrieve data. {0}", ex.Message);
   }

   return new List<Person>();
}
```
احفظ الملف PersonRepository.cs.

دمج المستودع في واجهة المستخدم

افتح ملف MauiProgram.cs .
في الدالة CreateMauiApp ، بعد العبارات التي تضيف MainPage الصفحة كخدمة أحادية إلى التطبيق، أضف التعليمات البرمجية لتنفيذ المهام التالية:
- أنشئ متغير سلسلة باسم dbPath. تهيئة هذه السلسلة باستخدام التعبير FileAccessHelper.GetLocalFilePath("people.db3"). سيسمى ملف قاعدة البيانات الذي يستخدمه التطبيق people.db3، وسيقوم التطبيق بحفظ هذا الملف في التخزين المحلي على الجهاز.
- استخدم إدخال التبعية لإضافة PersonRepository الفئة كخدمة أحادية إلى التطبيق. PersonRepository تعرض الفئة الدالة الإنشائية التي تأخذ المسار إلى ملف قاعدة البيانات كمعلمة سلسلة.
يجب أن تبدو التعليمات البرمجية المكتملة للدالة CreateMauiApp كما يلي:
```
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        });

    // Add this code
    string dbPath = FileAccessHelper.GetLocalFilePath("people.db3");
    builder.Services.AddSingleton<PersonRepository>(s => ActivatorUtilities.CreateInstance<PersonRepository>(s, dbPath));

    return builder.Build();
}
```
احفظ ملف MauiProgram.cs.
قم بتوسيع App.xaml في مستكشف الحلول، ثم افتح ملف App.xaml.cs.
أضف خاصية public، static تسمى PersonRepo للاحتفاظ بعنصر PersonRepository إلى App الفئة .
تهيئة الخاصية PersonRepo في الدالة الإنشائية عن طريق إضافة معلمة PersonRepository إلى الدالة الإنشائية وتعيين الخاصية "PersonRepo" إلى القيمة في هذه المعلمة. يجب أن تبدو الفئة المكتملة App كما يلي:
```
public partial class App : Application
{
    public static PersonRepository PersonRepo { get; private set; }

    public App(PersonRepository repo)
    {
        InitializeComponent();

        MainPage = new AppShell();

        PersonRepo = repo;
    }
}
```

إشعار

تقوم عملية إدخال التبعية تلقائيا بملء المعلمة repo إلى الدالة الإنشائية.

اختبر التطبيق

أنشئ الحل باستخدام CTRL+Shift+B وابدأ تصحيح الأخطاء باستخدام F5. عند ظهور واجهة المستخدم، أدخل اسمك وحدد إضافة شخص.
حدد الحصول على الكل الأشخاص وتحقق من ظهور اسمك.
جرب عن طريق إضافة المزيد من الأسماء واسترداد قائمة الأشخاص المخزنين.
ارجع إلى Visual Studio أو Visual Studio Code وتوقف عن تصحيح الأخطاء باستخدام Shift+F5.
أعد تشغيل التطبيق وحدد الحصول على الكل الأشخاص. تحقق من أن الأسماء التي قمت بتخزينها مسبقا لا تزال مخزنة في قاعدة البيانات. أغلق التطبيق عند الانتهاء.

متابعة