تحليل التغييرات بين إصدارات جداول البيانات هو مهمة روتينية للمالية، وإعداد التقارير، وتدفقات عمل التحقق من البيانات. GroupDocs.Comparison Cloud SDK for .NET يوفر واجهة برمجة تطبيقات قوية تجعل من السهل مقارنة ملفات Excel في .NET دون فحص يدوي. في هذا الدليل ستتعرف على كيفية إعداد المكتبة، تحميل دفاتر العمل، استدعاء نقطة النهاية REST من C#، استرجاع معلومات التغيير التفصيلية، وضبط خيارات المقارنة بدقة للحصول على نتائج دقيقة.

قبل البدء: المتطلبات والتثبيت

قبل البدء، تأكد من أن لديك ما يلي:

  • .NET 6.0 أو أحدث مثبت.
  • بيئة تطوير متكاملة (IDE) مثل Visual Studio 2022.
  • حساب GroupDocs Cloud مع ClientId و ClientSecret.
  • الوصول إلى تخزين GroupDocs Cloud حيث سيتم تحميل ملفات Excel.

قم بتثبيت SDK عبر NuGet:

dotnet add package GroupDocs.Comparison-Cloud

قم بتنزيل أحدث حزمة من صفحة الإصدار. بعد التثبيت، أضف بيانات الاعتماد الخاصة بك في الشيفرة كما هو موضح لاحقًا. أنت الآن جاهز لبدء سير عمل المقارنة.

دليل خطوة بخطوة لمقارنة ملفات Excel في .NET

الخطوات التالية توضح كيفية مقارنة ملفات Excel في .NET باستخدام SDK.

الخطوة 1: تحميل المستند المصدر والمستند الهدف

إنشاء كائن تكوين باستخدام بيانات الاعتماد الخاصة بك وتثبيت CompareApi

var config = new Configuration
{
    ClientId = "YOUR_CLIENT_ID",
    ClientSecret = "YOUR_CLIENT_SECRET"
};

var compareApi = new CompareApi(config);

الخطوة 2: إعداد دفاتر Excel

حدد كائنات FileInfo التي تشير إلى ملفات XLSX المصدر والهدف المخزنة في GroupDocs Cloud storage.

var sourceFile = new FileInfo { FilePath = "input/source.xlsx" };
var targetFile = new FileInfo { FilePath = "input/target.xlsx" };

الخطوة 3: تعيين خيارات المقارنة والإعدادات

قم بتكوين كائن CompareOptions، بما في ذلك إعدادات التغييرات التفصيلية.

var compareOptions = new CompareOptions
{
    SourceFile = sourceFile,
    TargetFiles = new List<FileInfo> { targetFile },
    OutputPath = "output/diff_result.xlsx",
    Settings = new Settings
    {
        ShowDeletedContent = true,
        ShowInsertedContent = true,
        ShowStyleChanges = true,
        GenerateSummaryPage = true
    }
};

للحصول على قائمة كاملة بالإعدادات، راجع مرجع API.

الخطوة 4: تنفيذ المقارنة ومعالجة النتائج

استدعِ طريقة Compare واقرأ معلومات النتيجة الأساسية.

var compareResult = compareApi.Compare(compareOptions);
Console.WriteLine($"Comparison completed. Result file: {compareResult.Path}");
Console.WriteLine($"Number of changes detected: {compareResult.Changes?.Count ?? 0}");

الخطوة 5: استرجاع معلومات التغيير التفصيلية

إذا كنت بحاجة إلى تقرير تفصيلي، استخدم طلب GetChanges.

var changesRequest = new GetChangesRequest
{
    SourceFile = sourceFile,
    TargetFile = targetFile,
    OutputPath = "output/detailed_changes.json"
};
var detailedChanges = compareApi.GetChanges(changesRequest);
Console.WriteLine($"Detailed changes saved to: {detailedChanges.Path}");

مع هذه الخطوات، لقد قمت بأتمتة عملية مقارنة ملفات Excel في .NET بالكامل.

مقارنة ملفات Excel برمجيًا - مثال كامل للكود

يعرض الكود التالي سير العمل الكامل من التكوين إلى معالجة النتيجة.

using System;
using System.Collections.Generic;
using GroupDocs.Comparison.Cloud.Sdk.Api;
using GroupDocs.Comparison.Cloud.Sdk.Client;
using GroupDocs.Comparison.Cloud.Sdk.Model;

namespace CompareExcelDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // Set up API credentials (replace with your actual credentials)
            var config = new Configuration
            {
                ClientId = "YOUR_CLIENT_ID",
                ClientSecret = "YOUR_CLIENT_SECRET"
            };

// Initialize Compare API
            var compareApi = new CompareApi(config);

// Prepare source and target Excel files (must be uploaded to GroupDocs Cloud storage beforehand)
            var sourceFile = new FileInfo { FilePath = "input/source.xlsx" };
            var targetFile = new FileInfo { FilePath = "input/target.xlsx" };

// Define comparison options
            var compareOptions = new CompareOptions
            {
                SourceFile = sourceFile,
                TargetFiles = new List<FileInfo> { targetFile },
                OutputPath = "output/diff_result.xlsx",
                // Optional: specify that we want detailed changes for worksheets
                Settings = new Settings
                {
                    ShowDeletedContent = true,
                    ShowInsertedContent = true,
                    ShowStyleChanges = true,
                    GenerateSummaryPage = true
                }
            };

try
            {
                // Call the Compare API
                var compareResult = compareApi.Compare(compareOptions);

// Output basic result information
                Console.WriteLine($"Comparison completed. Result file: {compareResult.Path}");
                Console.WriteLine($"Number of changes detected: {compareResult.Changes?.Count ?? 0}");

// Iterate through change details
                if (compareResult.Changes != null)
                {
                    foreach (var change in compareResult.Changes)
                    {
                        Console.WriteLine("--------------------------------------------------");
                        Console.WriteLine($"Change Type   : {change.ChangeType}");
                        Console.WriteLine($"Worksheet     : {change.Worksheet}");
                        Console.WriteLine($"Cell Address  : {change.CellAddress}");
                        Console.WriteLine($"Old Value     : {change.OldValue}");
                        Console.WriteLine($"New Value     : {change.NewValue}");
                        Console.WriteLine($"Is New Row    : {change.IsNewRow}");
                        Console.WriteLine($"Is New Column : {change.IsNewColumn}");
                    }
                }

// Retrieve detailed changes via GetChanges (optional)
                var changesRequest = new GetChangesRequest
                {
                    SourceFile = sourceFile,
                    TargetFile = targetFile,
                    OutputPath = "output/detailed_changes.json"
                };
                var detailedChanges = compareApi.GetChanges(changesRequest);
                Console.WriteLine($"Detailed changes saved to: {detailedChanges.Path}");
            }
            catch (ApiException apiEx)
            {
                Console.WriteLine($"API error: {apiEx.ErrorCode} - {apiEx.Message}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Unexpected error: {ex.Message}");
            }
        }
    }
}

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

إجراء مقارنة Excel عبر REST باستخدام cURL

يمكنك تحقيق النتيجة نفسها دون كتابة كود C# عن طريق استدعاء واجهة برمجة التطبيقات REST مباشرة.

1. المصادقة والحصول على رمز الوصول

curl -X POST "https://api.groupdocs.cloud/v1.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

2. تحميل المصنف المصدر

curl -X PUT "https://api.groupdocs.cloud/v1.0/storage/file?path=input/source.xlsx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -T "./source.xlsx"

3. تحميل دفتر العمل الهدف

curl -X PUT "https://api.groupdocs.cloud/v1.0/storage/file?path=input/target.xlsx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -T "./target.xlsx"

4. تنفيذ المقارنة

curl -X POST "https://api.groupdocs.cloud/v1.0/comparison/compare" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "source_file": {"file_path":"input/source.xlsx"},
           "target_files": [{"file_path":"input/target.xlsx"}],
           "output_path":"output/diff_result.xlsx",
           "settings": {
               "show_deleted_content": true,
               "show_inserted_content": true,
               "show_style_changes": true,
               "generate_summary_page": true
           }
         }'

5. تنزيل دفتر العمل Diff الناتج

curl -X GET "https://api.groupdocs.cloud/v1.0/storage/file?path=output/diff_result.xlsx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o diff_result.xlsx

للحصول على قائمة كاملة بالمعلمات، راجع وثائق API الرسمية.

الخلاصة

باستخدام GroupDocs.Comparison Cloud SDK for .NET يمكنك بسهولة مقارنة ملفات Excel في .NET والحصول على دفتر عمل diff مفصل يبرز كل تعديل. تتيح لك بنية SDK المستندة إلى REST دمج مقارنة جداول البيانات في أي خدمة C# أو واجهة برمجة تطبيقات ويب أو مهمة خلفية بأقل جهد. تذكر أن تحصل على ترخيص مناسب للاستخدام في الإنتاج؛ ترخيص مؤقت متاح من صفحة الترخيص وتفاصيل الترخيص الكامل مدرجة على موقع المنتج. ابدأ بأتمتة تدفقات عمل Excel diff اليوم وتخلص من أخطاء الفحص اليدوي.

FAQs

  • كيف يمكنني مقارنة ملفات Excel في .NET دون كتابة الكثير من الشيفرة؟
    يقوم SDK بتجريد العبء الثقيل. كل ما عليك هو تكوين بيانات الاعتماد، الإشارة إلى ملفي XLSX، واستدعاء compareApi.Compare. تُعيد المكتبة ملف diff وقائمة من كائنات التغيير.

  • ما هو تنسيق نتيجة الفرق؟
    بشكل افتراضي يتم حفظ النتيجة كملف عمل XLSX، مع الحفاظ على التخطيط الأصلي وتطبيق علامات بصرية للحذف والإدراج وتغييرات النمط.

  • هل من الممكن مقارنة دفاتر عمل Excel المحمية؟
    نعم. قدّم كلمة المرور في خاصية Password لكائن FileInfo. سيقوم الـ API بفتح دفتر العمل قبل إجراء المقارنة.

  • هل أحتاج إلى ترخيص للتطوير والاختبار؟
    يمكن الحصول على ترخيص مؤقت من صفحة الترخيص. بالنسبة للنشر في بيئة الإنتاج يجب شراء ترخيص كامل كما هو موضح في صفحة المنتج.

اقرأ المزيد