Збудувати віддалений приймач позначок для Markdig (Українська (Ukrainian))

Збудувати віддалений приймач позначок для Markdig

Friday, 07 November 2025

//

27 minute read

Введение

Однією з проблем, з якими я зіткнувся, створюючи цей блог, було те, як ефективно включити зовнішній зміст маркування без ручної копіювання та вставки його всюди.. Я хотів завантажити README-файли з мого GitHub-репозитори. , включити документацію з інших проектів.

В цьому пості я покажу вам, як я збудував Mostlylucid.Markdig.FetchExtension - Kompletне рішення для віддаленого відмітки контенту з Support for multiple storage backends

Зверніть увагу: Це все ще попередження, але я хотів його випустити на екрані

Цей artykuł створений штучним інтелектом -, використовуючи клаудовий код, який також допоміг мені побудувати функцію

Знову підготували: Добавлено disable="true" параметр, так що тепер ми можемо продемонструвати значки правильно без їх обробки!

UPDATE (Nov 7, МSK2: Добавлено Стосунок [TOC] у вашій позначці, щоб автоматично генерувати таблицю контенту, на яку можна натиснути з заголовків dokumentu.

Подивіться на джерело цього тут на GitHub для цього сайту.

NuGet NuGet

Чому будувати це?

Перед тим, як зануритися у технічні деталі, дозвольте мені пояснити проблемуM SK1 У мене є декілька сценаріїв, в яких я повинен включити зовнішній зміст відмітки

  1. README пакетів: Коли я пишу про пакет NuGet, я ' опублікував МSK2 Я хочу включити його README прямо з GitHub
  2. Документація API: Внешні доки API, які часто змінюються, мають бути синхронними
  3. Поділений контент: Документація, яка живе в одній базі, але має бути представлена в багатьох місцях
  4. Результати: Я не хочу ' завантажити цей контент на кожну сторінку

Наївний підхід полягає в тому, щоб використати HTTP-клиента для відбору позначки, коли вам це потрібно.

  • Кожна прохання потрапляє на віддалений сервер
  • Затримка мережі впливає на час завантаження сторінки
  • Ніхто не підтримує аутентифікацію
  • Ніхто не вирішує проміжок

Мені знадобилося щось розумніше: завантажити один разM SK1 интелектно підлаштуватися в кэшіМSK2 автоматично обновляти, і граційно справлятися з невдачами

Уявлення про архітектуру

Поширення скористається підготовкою до обробки, а не є частиною папірної системи аналізу Маркдіґа.. Це вирішальне, бо це означає, що завантажений контент проходить крізь всю папірну систему Маркдіг.

graph TD
    A[Markdown with fetch tags] --> B[MarkdownFetchPreprocessor]
    B --> C{Check Cache}
    C -->|Fresh| D[Return Cached Content]
    C -->|Stale/Missing| E[Fetch from Remote URL]
    E -->|Success| F[Update Cache]
    E -->|Failure| G{Has Cached?}
    G -->|Yes| H[Return Stale Cache]
    G -->|No| I[Return Error Comment]
    F --> J[Replace fetch with Content]
    D --> J
    H --> J
    I --> J
    J --> K[Processed Markdown]
    K --> L[Your Markdig Pipeline]
    L --> M[Final HTML]

Головним моментом тут є передрозробка. Перед тим, як ваш знак падіння досягне трубопроводу Маркдіґа

  1. Сканувати <fetch> ярлики
  2. Відтворити зміст ( з кэша або віддаленогоM SK1
  3. Заміняйте ярлики справжнім відмітком
  4. Давай Маркдіг обробить все разом

Це гарантує послідовність - всі відмітки отримують однакове лікування незалежно від джерела

Початкова синтаксиса

Використовування розширення є простим. У вашому значенніM SK1

# My Documentation

<!-- Failed to fetch content from https://raw.githubusercontent.com/user/repo/main/README.md: HTTP 404: Not Found -->

Це – МСК0, це – МSK1. Поширення буде

  • Візьміть README з GitHub
  • Заховувати його протягом 24 годин
  • Возв 'язувати в кэші зміст на наступних запитах
  • Автоматичний-рефірш, коли закінчується Cache

Архітектура постачальника зберігання

Один із принципів дизайну, який я дотримувався гнучкість. Різні додатки мають різні потреби . Невелика демонстраційна програма не потребує PostgreSQLM SK3 але мультиплінарний- серверний розгортування створює production doesMSC5 Тому я збудував встромливу архітектуру для зберігання

graph LR
    A[IMarkdownFetchService Interface] --> B[InMemoryMarkdownFetchService]
    A --> C[FileBasedMarkdownFetchService]
    A --> D[PostgresMarkdownFetchService]
    A --> E[SqliteMarkdownFetchService]
    A --> F[SqlServerMarkdownFetchService]
    A --> G[YourCustomService]

    B --> H[ConcurrentDictionary]
    C --> I[File System + SemaphoreSlim]
    D --> J[PostgreSQL Database]
    E --> K[SQLite Database]
    F --> L[SQL Server Database]
    G --> M[Your Storage Backend]

Кораовий інтерфейс

Все реалізується IMarkdownFetchService:

public interface IMarkdownFetchService
{
    Task<MarkdownFetchResult> FetchMarkdownAsync(
        string url,
        int pollFrequencyHours,
        int blogPostId = 0);

    Task<bool> RemoveCachedMarkdownAsync(
        string url,
        int blogPostId = 0);
}

Прості та чисті. Кожна інсталяція управляє зберіганням по-своєму ,, але інтерфейс залишається послідовним МSK2

В-Сховище пам 'ятіM SK1 Чудово для демонстрацій

Найпростіше застосування ConcurrentDictionary:

public class InMemoryMarkdownFetchService : IMarkdownFetchService
{
    private readonly ConcurrentDictionary<string, CacheEntry> _cache = new();
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<InMemoryMarkdownFetchService> _logger;

    public async Task<MarkdownFetchResult> FetchMarkdownAsync(
        string url,
        int pollFrequencyHours,
        int blogPostId)
    {
        var cacheKey = GetCacheKey(url, blogPostId);

        // Check cache
        if (_cache.TryGetValue(cacheKey, out var cached))
        {
            var age = DateTimeOffset.UtcNow - cached.FetchedAt;
            if (age.TotalHours < pollFrequencyHours)
            {
                _logger.LogDebug("Returning cached content for {Url}", url);
                return new MarkdownFetchResult
                {
                    Success = true,
                    Content = cached.Content
                };
            }
        }

        // Fetch fresh content
        var fetchResult = await FetchFromUrlAsync(url);

        if (fetchResult.Success)
        {
            _cache[cacheKey] = new CacheEntry
            {
                Content = fetchResult.Content,
                FetchedAt = DateTimeOffset.UtcNow
            };
        }
        else if (cached != null)
        {
            // Fetch failed, return stale cache
            _logger.LogWarning("Fetch failed, returning stale cache for {Url}", url);
            return new MarkdownFetchResult
            {
                Success = true,
                Content = cached.Content
            };
        }

        return fetchResult;
    }

    private static string GetCacheKey(string url, int blogPostId)
        => $"{url}_{blogPostId}";
}

Як бачите, це робить наступне:

  1. Створює ключ кэшу з URL та блогового поста ID
  2. Проверяє, чи ми зберігаємо контент в кэші і чи він свіжий
  3. Якщо кэш свіжий, повертає його негайно
  4. Якщо stale, намагається завантажити свіжий контент
  5. Під час успішного, оновлення кэшу
  6. Якщо втрачається Cached content, , повертає стару Cache (staleM SK2while-revalidateMSC4
  7. При невдачі без кэша, повертає błąd

Цей візерунок - застарілий-while-реvalidate - є вирішальним для надійності . Навіть якщо GitHub зазнає краху МSK2 ваш сайт продовжує працювати зキャッシュованим контентом

Файл-На основі зберігання: Проста тривалість

Для одиночного-розгортання сервера,файлуM SK2здатний до storування

public class FileBasedMarkdownFetchService : IMarkdownFetchService
{
    private readonly string _cacheDirectory;
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<FileBasedMarkdownFetchService> _logger;
    private readonly SemaphoreSlim _fileLock = new(1, 1);

    public async Task<MarkdownFetchResult> FetchMarkdownAsync(
        string url,
        int pollFrequencyHours,
        int blogPostId)
    {
        var cacheKey = ComputeCacheKey(url, blogPostId);
        var cacheFile = GetCacheFilePath(cacheKey);

        await _fileLock.WaitAsync();
        try
        {
            // Check if file exists and is fresh
            if (File.Exists(cacheFile))
            {
                var fileInfo = new FileInfo(cacheFile);
                var age = DateTimeOffset.UtcNow - fileInfo.LastWriteTimeUtc;

                if (age.TotalHours < pollFrequencyHours)
                {
                    var cached = await File.ReadAllTextAsync(cacheFile);
                    return new MarkdownFetchResult
                    {
                        Success = true,
                        Content = cached
                    };
                }
            }

            // Fetch fresh
            var fetchResult = await FetchFromUrlAsync(url);

            if (fetchResult.Success)
            {
                await File.WriteAllTextAsync(cacheFile, fetchResult.Content);
            }
            else if (File.Exists(cacheFile))
            {
                // Return stale on fetch failure
                var stale = await File.ReadAllTextAsync(cacheFile);
                return new MarkdownFetchResult
                {
                    Success = true,
                    Content = stale
                };
            }

            return fetchResult;
        }
        finally
        {
            _fileLock.Release();
        }
    }

    private string GetCacheFilePath(string cacheKey)
        => Path.Combine(_cacheDirectory, $"{cacheKey}.md");

    private static string ComputeCacheKey(string url, int blogPostId)
    {
        var combined = $"{url}_{blogPostId}";
        using var sha256 = SHA256.Create();
        var bytes = Encoding.UTF8.GetBytes(combined);
        var hash = sha256.ComputeHash(bytes);
        return Convert.ToHexString(hash);
    }
}

Головні моменти:

  1. Використовується SemaphoreSlim для потоку-безпечного доступу до файлів
  2. Хайш URL + блог пост ID для створення безпечних ім 'я файлів
  3. Використовує час модифікації файлу, щоб визначити свіжість
  4. Перетримування через репетицію
  5. Те ж саме безвиходне-while-реvalidate pattern

База даних: ProdukціяM SK1 Готова

Для побудови виробництва: МСК0, особливо мультиплікові, МСК1, серверні налаштування, МSK2, ви хочете спільний кэш, ., те, що МСК4, куди приходять постачальники баз даних

public class PostgresMarkdownFetchService : IMarkdownFetchService
{
    private readonly MarkdownCacheDbContext _dbContext;
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<PostgresMarkdownFetchService> _logger;

    public async Task<MarkdownFetchResult> FetchMarkdownAsync(
        string url,
        int pollFrequencyHours,
        int blogPostId)
    {
        var cacheKey = GetCacheKey(url, blogPostId);

        // Query cache
        var cached = await _dbContext.MarkdownCache
            .FirstOrDefaultAsync(c => c.CacheKey == cacheKey);

        if (cached != null)
        {
            var age = DateTimeOffset.UtcNow - cached.LastFetchedAt;
            if (age.TotalHours < pollFrequencyHours)
            {
                return new MarkdownFetchResult
                {
                    Success = true,
                    Content = cached.Content
                };
            }
        }

        // Fetch fresh
        var fetchResult = await FetchFromUrlAsync(url);

        if (fetchResult.Success)
        {
            if (cached == null)
            {
                cached = new MarkdownCacheEntry
                {
                    CacheKey = cacheKey,
                    Url = url,
                    BlogPostId = blogPostId
                };
                _dbContext.MarkdownCache.Add(cached);
            }

            cached.Content = fetchResult.Content;
            cached.LastFetchedAt = DateTimeOffset.UtcNow;
            await _dbContext.SaveChangesAsync();
        }
        else if (cached != null)
        {
            // Return stale
            return new MarkdownFetchResult
            {
                Success = true,
                Content = cached.Content
            };
        }

        return fetchResult;
    }
}

схема бази даних проста:

CREATE TABLE markdown_cache (
    id SERIAL PRIMARY KEY,
    cache_key VARCHAR(128) NOT NULL UNIQUE,
    url VARCHAR(2048) NOT NULL,
    blog_post_id INTEGER NOT NULL,
    content TEXT NOT NULL,
    last_fetched_at TIMESTAMP WITH TIME ZONE NOT NULL,
    CONSTRAINT ix_markdown_cache_cache_key UNIQUE (cache_key)
);

CREATE INDEX ix_markdown_cache_url_blog_post_id
    ON markdown_cache(url, blog_post_id);

У багатому-застосуванні сервера, це дає вам концентрацію вキャッシュі на всіх instanціяхM SK2

graph TB
    subgraph "Load Balancer"
        LB[Load Balancer]
    end

    subgraph "Application Servers"
        A1[App Server 1<br/>FetchExtension]
        A2[App Server 2<br/>FetchExtension]
        A3[App Server 3<br/>FetchExtension]
    end

    subgraph "Shared Cache"
        PG[(PostgreSQL<br/>markdown_cache table)]
    end

    subgraph "External Content"
        R1[Remote URL 1]
        R2[Remote URL 2]
        R3[Remote URL 3]
    end

    LB --> A1
    LB --> A2
    LB --> A3

    A1 <-->|Read/Write Cache| PG
    A2 <-->|Read/Write Cache| PG
    A3 <-->|Read/Write Cache| PG

    A1 -.->|Fetch if cache miss| R1
    A2 -.->|Fetch if cache miss| R2
    A3 -.->|Fetch if cache miss| R3

Усі сервери мають один і той самий кэш. Коли Сервер | 1 | отримує README | МSK2 | Сервери |2 | та |МSK4 | негайно користуються цим кэшованим контентом

Налагодження розширення

Начати - просто. Перший , заinstalувати базовий пакет:

dotnet add package mostlylucid.Markdig.FetchExtension

Тоді виберите ваш постачальник зберігання:

# For in-memory (demos/testing)
# Already included in base package

# For file-based storage
# Already included in base package

# For PostgreSQL
dotnet add package mostlylucid.Markdig.FetchExtension.Postgres

# For SQLite
dotnet add package mostlylucid.Markdig.FetchExtension.Sqlite

# For SQL Server
dotnet add package mostlylucid.Markdig.FetchExtension.SqlServer

Konfiguracja в ASP.NET Core

У вашому Program.cs:

using Mostlylucid.Markdig.FetchExtension;

var builder = WebApplication.CreateBuilder(args);

// Option 1: In-Memory (simplest)
builder.Services.AddInMemoryMarkdownFetch();

// Option 2: File-Based (persists across restarts)
builder.Services.AddFileBasedMarkdownFetch("./markdown-cache");

// Option 3: PostgreSQL (multi-server)
builder.Services.AddPostgresMarkdownFetch(
    builder.Configuration.GetConnectionString("MarkdownCache"));

// Option 4: SQLite (single server with DB)
builder.Services.AddSqliteMarkdownFetch("Data Source=markdown-cache.db");

// Option 5: SQL Server (enterprise)
builder.Services.AddSqlServerMarkdownFetch(
    builder.Configuration.GetConnectionString("MarkdownCache"));

var app = builder.Build();

// If using database storage, ensure schema exists
if (app.Environment.IsDevelopment())
{
    app.Services.EnsureMarkdownCacheDatabase();
}

// Configure the extension with your service provider
FetchMarkdownExtension.ConfigureServiceProvider(app.Services);

app.Run();

Інтеграція з Markdown Rendering

Ключом є етап попереднього обробки.

public class MarkdownRenderingService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly MarkdownFetchPreprocessor _preprocessor;
    private readonly MarkdownPipeline _pipeline;

    public MarkdownRenderingService(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
        _preprocessor = new MarkdownFetchPreprocessor(serviceProvider);

        _pipeline = new MarkdownPipelineBuilder()
            .UseAdvancedExtensions()
            .UseSyntaxHighlighting()
            .UseToc()  // Add TOC support for [TOC] markers
            .UseYourCustomExtensions()
            .Build();
    }

    public string RenderMarkdown(string markdown)
    {
        // Step 1: Preprocess to handle fetch tags
        var processed = _preprocessor.Preprocess(markdown);

        // Step 2: Run through your normal Markdig pipeline
        return Markdown.ToHtml(processed, _pipeline);
    }
}

Потік::

  1. Ваша позначка містить <fetch> ярлики
  2. Препроцесор вирішує їх до реального відмітку
  3. Об 'єднана позначка вниз проходить через Маркдіг
  4. Все отримуєш на замовлення, стильM SK1 і т.д.

Заawansовані характеристики

генерація контенту

Даний пакет включає в себе відокремити Століння змісту (TOC) rozszerzenieM SK2 В той час, як це ' упаковується поряд з завантаженням rozszerzenia МSK4 це МСК5 є цілком незалежною і може бути використана сама по собі М СК6 Ви можете автоматично генерувати таблицю змісту, на яку можна натиснути з вашого документу M СК7 заголовки MСК8

Початкове використання:

Просто додайте [TOC] будь-де в вашому значенні:

# My Document

[TOC]

# Introduction
Content here...

# Getting Started
More content...

## Installation
Details...

Це генерує вбудований список усіх заголовків з якорними зв 'язками:

<nav class="ml_toc" aria-label="Table of Contents">
  <ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#getting-started">Getting Started</a>
      <ul>
        <li><a href="#installation">Installation</a></li>
      </ul>
    </li>
  </ul>
</nav>

Різні класи CSS:

Ви можете визначити звичайну класи CSS для дизайну:

[TOC cssclass="my-custom-toc"]

Це відображається за допомогою вашої спеціальної класи:

<nav class="my-custom-toc" aria-label="Table of Contents">
  <!-- TOC content -->
</nav>

Як це працює:

  1. Auto-Detection: TOC автоматично визначає мінімальний рівень заголовку у вашому документі і враховує його відповідноM SK1 Якщо ваш документ починається з H2, то TOC сприймає H 2 як верхній рівень

  2. генерація идентівок: Заголовки автоматично отримують ідентичні знаки для прив 'язування к Anchor

    • "Зачато запускатиM SK1 МSK2 id="getting-started"
    • "API Референція id="api-reference"
  3. Помістена структура: Рендерер створює добре вбудований ul/li структура, яка відображає ієрархію ваших документів.

Уможливлення підтримки TOC:

Під час конфігурації вашого трубопроводу Markdig, додайте розширення TOC:

var pipeline = new MarkdownPipelineBuilder()
    .UseAdvancedExtensions()
    .UseToc()  // Add TOC support - position in pipeline doesn't matter!
    .Use<YourOtherExtensions>()
    .Build();

Позиція трубопроводу: На відміну від деяких розширень Маркдіґа,, розширення TOC неважливо, де його додати в трубопроводі. Поширення автоматичноM SK1

  • Вserts its parser at the beginning of the parser list (position 0)
  • Відтворює після закінчення аналізу, зібрання заголовків з усього документа

Отже, ви можете додати .UseToc() будь-де - початковий МSK1 середній МSK2 або кінець вашої конструкції трубопроводу .

Важливо: Поширення TOC цілком незалежна від поширення забирання.

  • Використовувати TOC без залучення
  • Використовувати прийти без TOC
  • Використовуйте обидва разом

Nota: Маркер TOC працює як в головних файлах відмітки вниз, так і в отриманому віддаленому контенті. Якщо ви завантажуєте README з GitHub, який містить [TOC], він автоматично генерує таблицю змісту з того документу ' заголовки .UseToc() до вашого трубопроводу).

Перетворення зв 'язку

Коли вибираєте віддалене відмітення, ( особливо з GitHub ), пов 'язані зв' язки розриваютьсяM SK2 Поширення може їх автоматично переписати:

<!-- Failed to fetch content from https://raw.githubusercontent.com/user/repo/main/docs/README.md: HTTP 404: Not Found -->

Це трансформує:

  • ./CONTRIBUTING.md → https://github.com/user/repo/blob/main/docs/CONTRIBUTING.md
  • ../images/logo.png → https://github.com/user/repo/blob/main/images/logo.png
  • Захищає абсолютні URL та анкери

Втілення використовує Markdig AST, щоб переписати посилання:

public class MarkdownLinkRewriter
{
    public static string RewriteLinks(string markdown, string sourceUrl)
    {
        var document = Markdown.Parse(markdown);
        var baseUri = GetBaseUri(sourceUrl);

        foreach (var link in document.Descendants<LinkInline>())
        {
            if (IsRelativeLink(link.Url))
            {
                link.Url = ResolveRelativeLink(baseUri, link.Url);
            }
        }

        using var writer = new StringWriter();
        var renderer = new NormalizeRenderer(writer);
        renderer.Render(document);
        return writer.ToString();
    }

    private static bool IsRelativeLink(string url)
    {
        if (string.IsNullOrEmpty(url)) return false;
        if (url.StartsWith("http://") || url.StartsWith("https://")) return false;
        if (url.StartsWith("#")) return false;  // Anchor
        if (url.StartsWith("mailto:")) return false;
        return true;
    }
}

Fetch Metadata Summary

Ви можете показати читачів, коли контент був опиняний на останній раз:

<!-- Failed to fetch content from https://api.example.com/status.md: HTTP request failed: Name or service not known (api.example.com:443) -->

Це відображає з заголовком:

Звідси завантажений контент https://apiMSC1example.comM SK3statusMST4md на 06 янв.

Або настроить шаблон:

<!-- Failed to fetch content from https://example.com/docs.md: HTTP 404: Not Found -->

Виход:~~~~

Найновіше обновлено: M SK1 Січні 2025 | | МSK3 | | | Статус: Cached МSK6 Дальне поновленняMSC7 в МSK8 годині

Доступні позиціонери:

  • {retrieved:format} - Data ostatniого завантаженняM SK1time
  • {age} - ЛюдськийM SK1читаний час від завантаження
  • {url} - Адрес URL
  • {nextrefresh:format} - Коли контент буде обновлятися
  • {pollfrequency} - Тривалістьキャッシュу в годині
  • {status} - Статусキャッシュу

Загнічення обробки для документації

Коли пишеш документ про завантаження rozszerzenia (наче цей artykułM SK1 вам потрібен спосіб показати ярлики без їх обробки disable="true" атрибут:

<!-- This will be processed and fetch content -->
<!-- Failed to fetch content from https://example.com/README.md: HTTP 404: Not Found -->

<!-- This will NOT be processed - useful for documentation -->
<!-- Failed to fetch content from https://example.com/README.md: HTTP 404: Not Found -->

Знак неповносправний залишається в значку, так як "-" є МSK1 , досконалий для МСК2 .

  • Пишаючи документи про саму розширенню
  • Створювання прикладів в курсах
  • Показywanie синтаксису тегов без триггерування заходів

Це працює для обох <fetch> і <fetch-summary> ярлики:

<!-- No fetch data available for https://example.com/api/status.md -->

Система подій для моніторингу

Поширення публікує події для всіх операцій залучення:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddPostgresMarkdownFetch(connectionString);

        var sp = services.BuildServiceProvider();
        var eventPublisher = sp.GetRequiredService<IMarkdownFetchEventPublisher>();

        // Subscribe to events
        eventPublisher.FetchBeginning += (sender, args) =>
        {
            Console.WriteLine($"Fetching {args.Url}...");
        };

        eventPublisher.FetchCompleted += (sender, args) =>
        {
            var source = args.WasCached ? "cache" : "remote";
            Console.WriteLine($"Fetched {args.Url} from {source} in {args.Duration.TotalMilliseconds}ms");
        };

        eventPublisher.FetchFailed += (sender, args) =>
        {
            Console.WriteLine($"Failed to fetch {args.Url}: {args.ErrorMessage}");
        };
    }
}

Це дає змогу легко об 'єднатися з Application Insights, Prometheus, або своєю логістичною інфраструктуроюM SK2

sequenceDiagram
    participant MD as Markdown Processor
    participant EP as Event Publisher
    participant FS as Fetch Service
    participant ST as Storage Backend
    participant L as Your Listeners

    MD->>EP: FetchBeginning
    EP->>L: Notify FetchBeginning
    EP->>FS: FetchMarkdownAsync(url)
    FS->>ST: Check Cache
    alt Cache Fresh
        ST-->>FS: Cached Content
        FS->>EP: FetchCompleted (cached=true)
    else Cache Stale/Missing
        FS->>FS: HTTP GET
        alt Success
            FS->>ST: Update Cache
            ST-->>FS: OK
            FS->>EP: FetchCompleted (cached=false)
        else Failure
            FS->>EP: FetchFailed
            EP->>L: Notify FetchFailed
        end
    end
    EP->>L: Notify FetchCompleted
    EP->>L: Notify ContentUpdated
    FS-->>MD: MarkdownFetchResult

    Note over L: Listeners can be: Logging, Metrics, Telemetry, Webhooks

Стратегія Caching у деталях

Керування відбувається за шаблоном машини.

stateDiagram-v2
    [*] --> CheckCache: Fetch Request

    CheckCache --> Fresh: Cache exists & age < pollFrequency
    CheckCache --> Stale: Cache exists & age >= pollFrequency
    CheckCache --> Missing: No cache entry

    Fresh --> ReturnCached: Return cached content
    ReturnCached --> [*]

    Stale --> FetchRemote: Attempt HTTP GET
    Missing --> FetchRemote: Attempt HTTP GET

    FetchRemote --> UpdateCache: Success
    FetchRemote --> HasStale: Failure

    UpdateCache --> ReturnFresh: Return new content
    ReturnFresh --> [*]

    HasStale --> ReturnStale: Return stale cache
    HasStale --> ReturnError: No cache available

    ReturnStale --> [*]
    ReturnError --> [*]

    note right of Fresh
        pollFrequency = 0
        means always stale
    end note

    note right of HasStale
        Stale-while-revalidate
        pattern ensures uptime
    end note

Найголовніша ідея тут:

  1. Свежа кэша - Повернімося негайноM SK1 не втрачає мережі
  2. Похибка залишена - Попробуйте забрати свіжийM SK1, але повернемось до старого, якщо завантаження не спрацює
  3. Позбавлена Cache - Потрібно забрати або повернути błąd
  4. Нульна частота полюсу - Знову приймати свіжий МSK1потрібний для тестуванняM SK2

Ця модель називається застарілий-while-реvalidate і це ' чудове для надійності . Навіть якщо ваш ресурс знизиться МSK2 ваша веб-страна продовжує подавати вキャッシュі контент

Виведення та управління キャッシュами

Інколи вам потрібно вручну підірвати кэш:

public class MarkdownController : Controller
{
    private readonly IMarkdownFetchService _fetchService;

    public async Task<IActionResult> InvalidateCache(string url)
    {
        var removed = await _fetchService.RemoveCachedMarkdownAsync(url);

        if (removed)
        {
            return Ok(new { message = "Cache invalidated" });
        }

        return NotFound(new { message = "No cache entry found" });
    }
}

Або через веб-шоки, коли зміст змінюється:

// GitHub webhook notifies of README update
app.MapPost("/webhooks/github", async (
    GitHubWebhookPayload payload,
    IMarkdownFetchService fetchService) =>
{
    if (payload.Repository?.FullName == "user/repo" &&
        payload.Commits?.Any(c => c.Modified?.Contains("README.md") == true) == true)
    {
        var url = "https://raw.githubusercontent.com/user/repo/main/README.md";
        await fetchService.RemoveCachedMarkdownAsync(url);

        return Results.Ok(new { message = "Cache invalidated" });
    }

    return Results.Ok(new { message = "No action needed" });
});

Випробовування розширення

Поширення включає в себе цілковите тестування. Тут' як я їх структуруюM SK2

public class MarkdownFetchServiceTests
{
    [Fact]
    public async Task FetchMarkdownAsync_CachesContent()
    {
        // Arrange
        var services = new ServiceCollection();
        services.AddLogging();
        services.AddInMemoryMarkdownFetch();
        var sp = services.BuildServiceProvider();

        var fetchService = sp.GetRequiredService<IMarkdownFetchService>();
        var url = "https://raw.githubusercontent.com/user/repo/main/README.md";

        // Act - First fetch (from network)
        var result1 = await fetchService.FetchMarkdownAsync(url, 24, 0);

        // Act - Second fetch (from cache)
        var result2 = await fetchService.FetchMarkdownAsync(url, 24, 0);

        // Assert
        Assert.True(result1.Success);
        Assert.True(result2.Success);
        Assert.Equal(result1.Content, result2.Content);
    }

    [Fact]
    public async Task FetchMarkdownAsync_ReturnsStaleOnFailure()
    {
        // Arrange
        var services = new ServiceCollection();
        services.AddLogging();
        services.AddInMemoryMarkdownFetch();
        var sp = services.BuildServiceProvider();

        var fetchService = sp.GetRequiredService<IMarkdownFetchService>();
        var url = "https://httpstat.us/200?sleep=100";

        // Act - First fetch succeeds
        var result1 = await fetchService.FetchMarkdownAsync(url, 0, 0);

        // Change URL to fail
        var badUrl = "https://httpstat.us/500";

        // Act - Second fetch fails, should return stale
        var result2 = await fetchService.FetchMarkdownAsync(badUrl, 0, 0);

        // Assert
        Assert.True(result1.Success);
        // Even though fetch failed, we return success with stale content
        Assert.True(result2.Success);
    }
}

Рівень ефективності

Поширення розроблена для продуктивності

  1. Спільний словник - В МSK1застосування пам 'яті ConcurrentDictionary для потоку-безпечного доступу
  2. Семафор-слім - ФайліM SK1за допомогою асинкового блокування запобігають умовам гонки
  3. Індекси бази даних - Усі постачальники баз даних мають правильні індекси на ключах кэшу
  4. Об 'єднання HTTP-клиентів - Використовується IHttpClientFactory для ефективного повторного використання підключення
  5. Асинк усюди - Ніхто не блокує дзвінків

Типові показники на мого домашньому сервері:

  • Cache hit: M SK1 ≥1ms
  • Похибка в кэші з мережею: M SK1ms ( залежить від віддаленого сервера)
  • Подивитися на базу даних: M SK1ms (PostgreSQL з відповідними індексами)
  • Подивитися на файлову систему: M SK1ms

Розгортання з діями GitHub

Я публікую всі чотири пакети в NuGet за допомогою GitHub Actions з OIDC аутентифікацією:

name: Publish Markdig.FetchExtension

on:
  push:
    tags:
      - 'fetchextension-v*.*.*'

permissions:
  id-token: write
  contents: read

jobs:
  build-and-publish:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Setup .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '9.0.x'

    - name: Extract version from tag
      id: get_version
      run: |
        TAG=${GITHUB_REF#refs/tags/fetchextension-v}
        echo "VERSION=$TAG" >> $GITHUB_OUTPUT

    - name: Build
      run: dotnet build Mostlylucid.Markdig.FetchExtension/Mostlylucid.Markdig.FetchExtension.csproj --configuration Release -p:Version=${{ steps.get_version.outputs.VERSION }}

    - name: Pack
      run: dotnet pack Mostlylucid.Markdig.FetchExtension/Mostlylucid.Markdig.FetchExtension.csproj --configuration Release --no-build -p:PackageVersion=${{ steps.get_version.outputs.VERSION }} --output ./artifacts

    - name: Login to NuGet (OIDC)
      id: nuget_login
      uses: NuGet/login@v1
      with:
        user: 'mostlylucid'

    - name: Publish to NuGet
      run: dotnet nuget push ./artifacts/*.nupkg --api-key ${{ steps.nuget_login.outputs.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate

Дослідження OIDC безпечніше, ніж зберігання API ключів. - GitHub генерує короткі - живі टोकони автоматично

Реальний- Світове використання

Ось як я його використовую в своїх блогах

# My NuGet Package Documentation

Here's the official README from GitHub:

# Umami.Net

**Version 1.1.0** · [Upgrade guide](https://github.com/scottgal/mostlylucidweb/blob/umamiv1.1.0/Umami.Net/MIGRATION.md) · [Release notes](https://github.com/scottgal/mostlylucidweb/blob/umamiv1.1.0/Umami.Net/RELEASE.md)

A .NET 8, 9 and 10 client for [Umami Analytics](https://umami.is), reviewed against
[Umami 3.4.0](https://github.com/umami-software/umami/releases/tag/v3.4.0).

The library sends page views, events, visitor identity and Web Vitals, and reads
website analytics. It supports self-hosted username/password or API-key
credentials, and the current Umami Cloud Bearer API-key protocol.

## Install and register

```sh
dotnet add package Umami.Net --version 1.1.0
builder.Services.SetupUmamiClient(builder.Configuration); // Collection and background sender
builder.Services.SetupUmamiData(builder.Configuration);   // Authenticated analytics API

Обидві розширення використовують Analytics розділ конфігурації. Зарегистрируйтесь або обидва. Rejestracja не змінює ваші додатки ' рівень запису або провайдерів M SK2

{
  "Analytics": {
    "UmamiPath": "https://analytics.example.com/",
    "WebsiteId": "12345678-1234-1234-1234-123456789abc",
    "ApiVersion": "V3"
  }
}

Установити секрети за допомогою секретів користувача або змінних середовища, а не зобов 'язання вони. Для саморобногоM SK1 домашнє Умамі 3.4, набір Analytics__ApiKey до ключа інтерфейсу користувача створено в настроях → API ключіM SK1 Client надсилає Authorization: Bearer ... і не називає аут-енд-пойнтів,, які блоковані для цих ключівM SK1

Альтернативно, постачання Analytics__Username і Analytics__Password. Klient журнали в, перевіряють існуючі टोकони за допомогою POST /api/auth/verify, і повертає 401 раз після того, як винудили новий входM SK1 Вишкоди авторського права веб-сайту, потім повертаються 401 без повторюваності на нескінченний часM SK1 Частковий символ МSK2FA не прийметься як закінчений login; використовувати API ключ для безпосереднього доступу до M SK1FA

Для Umami Cloud, configure UmamiPath як https://api.umami.is/v1/ ( або кінцевий пункт регіону, такі як /v1/eu/), UseCloudApi: true, і ApiKey. klient зберігає цей базовий шлях і викидає self-hosted /api попередник. Колекція використовує трекер/хозяйник колекції, а не аутентифіковані дані хмари API; зареєструвати колекціонер окремо, якщо ваші кінцеві точки відрізняються

Ключи API та сучасні маршрути аналізу потребують сервера, який їх підтримує. Цей пакет не поновлює ваш сервер Umami, мігрує свою базу даних або не дозволяє такі як повторення сеансу або MCP.

Переслідування

В 'язати UmamiClient для негайного збору:

using var response = await client.TrackPageView("/products?utm_source=newsletter", "Products");
response.EnsureSuccessStatusCode();

using var purchase = await client.Track("purchase", new UmamiEventData
{
    ["revenue"] = 49.95,
    ["currency"] = "GBP"
}, distinctId: "customer-123");

Поворотні методи HttpResponseMessage передавати власника телефону відповідь. *AndDecode методи розробки відповідей та зворотнього аналізу замість метадань. SendAsync додає підтримку anulування, не змінюючи існуючі Send, Track, TrackPageView або Identify підписи.

Текучий колекціонер повертає { cache, sessionId, visitId }. Декодований результат демонструє SessionId, VisitId і Cache; Id також містить поточну сесію ID. Невідоме bareM SK1 Реакції JWT досі декодовані як метадані аналітики. Вони не використовується як доказ аутентифікації. { "beep": "boop" } повертається BotDetected.

var result = await client.TrackPageViewAndDecode("/landing");
using var next = await client.SendAsync(new UmamiPayload
{
    Url = "/pricing",
    CacheToken = result?.Cache,
    DistinctId = "customer-123",
    Tag = "campaign-a",
    Timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds()
}, cancellationToken: cancellationToken);

Торкиキャッシュу належать конкретному відвідувачі. Вони надсилаються явно на навантаження x-umami-cache; klient ніколи не зберігає одного в спільних початкових заголовках Umami 3.4 визначає відвідувачів, використовуючи DistinctId (id на проводі). SessionId на платі зберігається для legacy clients; теперішні сервери обчислюють сеанс Ідентичності замість прийняття телефону-вибрана сесія UUID.

Визначні дані про події, IP-адрес і користувачаM SK1 агент перехиляється, щоб пережити навантаження population. Без перемикання, klient захоплює вхідний користувачевий агентM SK2 шлях база, шлях і строк запитуM SK1 Стрини запиту зберігають параметри UTM. В зворотньому порядку застосування прокси, конфігурувати ASPM SK1NET Core'надіслані довіреними передаткамиМSK3розробка заголовків перед збиранням подій так RemoteIpAddress відображає потенційного відвідувача.

UseDefaultUserAgent є явною надтримкою, зачуваною для існуючих інтеграцій; він зберігає оригінал агента в даних подій. Normal collection preserves the real і дозволяє Bot-фільтруванню Umami ' для застосування

Веб Vitals

using var response = await client.TrackPerformanceAsync(new UmamiPayload
{
    Url = "/checkout", Title = "Checkout",
    Lcp = 1800, Inp = 120, Cls = 0.04, Fcp = 950, Ttfb = 180
});

Часові поля - мілісекунди МСК0 CLS - безімірний бал МSK1 Значення перевіряються з сучасним коллектором'с діапазонамиM SK1 Timestamp це Unix секунд; дата запиту аналітики конвертується в Unix мілісекунд.

Доставка на фоні

В 'язати UmamiBackgroundSender щоб зафіксувати метадані прохання і запорядковувати доставку:

await sender.TrackPageView("/products", "Products");
await sender.Track("checkout", new UmamiEventData { ["cartSize"] = 3 });
await sender.Identify(distinctId: "customer-123");

В 'язка пам' яті в' - зберігає до МSK1 подійM SK2 Операції черги чекають, коли вони закінчуються забезпечити зворотній тиск замість необмеженого росту пам 'яті. Запуск завершується сценарист і виштовхує доки не закінчуються події до кінцевого терміну anulації میزبانа. anulує доставки. Перебои в процесі можуть втратити дані в чергахM SK1 використовувати надійний поштовий ящик, якщо що є неприйнятним. Втрачена доставка зареєстрована без зупинки читачаM SK1 Письми для відстеження не перевіряються автоматично, тому що acknowledgement втрачено інакше можна подвоїти число подій

Сущені методи аналізу

В 'язати UmamiDataService:

var request = new MetricsRequest
{
    StartAtDate = DateTime.UtcNow.AddDays(-7),
    EndAtDate = DateTime.UtcNow,
    Type = MetricType.path,
    Limit = 20,
    UtmSource = "newsletter"
};
var metrics = await data.GetMetrics(request);
if (metrics.Status == HttpStatusCode.OK)
    foreach (var row in metrics.Data ?? []) Console.WriteLine($"{row.x}: {row.y}");

Сущені методи залишаються доступними: GetStats, GetPageViews, GetMetrics, GetExpandedMetrics, GetEventsSeries, і GetActiveUsers. Статуси нормалізуються обидва спадщини { value, prev } поля і теперішні числові kopā плюс comparison до існуючого .pageviews.value / .pageviews.prev модель. Активні відвідувачі прийняти спадок x і теперішнього visitors поля.

ApiVersion поганий до V3. MetricType.url карти до type=path в комплекті V3. V2 щоб зберегти стару метричну wartość; V1 для чіткого спадку path → url і hostname → host мапування параметрів. Виявление версії не автоматично. Неправильні M SK1 запити не записуються і не надсилаються мовчазно Мапи Compatibility не обіцяють, що кожна функція існує на старших серверах.

Метрічні виміри включають distinctId і utmSource, utmMedium, utmCampaign, utmContent, utmTerm; їхній верблюдName дроту Case зберігаються MetricType.event lista імена подій, не використовуючи фильтр подій. Букети хвилин підтримують; по упередній ставці серії подій до UTC, коли не вдається часовий поясM SK1 Поширені вимоги включають: розрізнені-індивідуальність, UTMM SK2 подіяMSC3 типMST4 співпадіння та відхилення фильтры. Фильтры URLM SK1 зашифровані один разМSK2 оператори і літери регекс зберігаються.

Статистика веб-сайту

Umami 3.4 відображає веб-сайт

var report = await data.GetAnalyticsAsync(AnalyticsEndpoint.PerformanceChart,
    new AnalyticsRequest
    {
        StartAtDate = DateTime.UtcNow.AddDays(-7), EndAtDate = DateTime.UtcNow,
        Unit = Unit.day, Timezone = "Europe/London", Metric = "lcp"
    }, cancellationToken);

AnalyticsEndpoint obejmuje приналежність, ventilationM SK1 funnel / goals statsMSC3 heatmaps, подорожіМСК0 затримкаМSK1 статистичні показники ефективностіМСК2картаМ СК3метріяМсК4 метрика UTMMСК5 доходи статистичні дані/картаМSK1метріяM SK2 сеанси та події. Критерії відрізняються в залежності від кінцевого результату офіційні контракти. Наприклад, прибуток Currency, UTM вимагає Type такі як utm_source, і провізор каналу бере JSON Steps плюс Window.

Загальним результатом є UmamiResult<JsonElement>, зберігає кожен набір данихM SK1s справжня форма. GetAnalyticsAsync<T> Obsługа оператора-визначені типовані моделіM SK1 Ці методи показують аналізні набіри даних ; вони не відтворюють інтерфейсу Umami, або запис сеансу браузера відтворювати потоки.

Аннотації

var note = await data.CreateAnnotationAsync(new AnnotationInput(
    DateTimeOffset.UtcNow, "Website refresh deployed", AllDay: false), cancellationToken);
var notes = await data.GetAnnotationsAsync(page: 1, pageSize: 20, cancellationToken: cancellationToken);
// UpdateAnnotationAsync(id, input), GetAnnotationAsync(id), DeleteAnnotationAsync(id)

Annotations have typed inputs, responses and paginated lists . Creating/updating використовує POST,, а видалення - DELETEM SK1, що відповідає поточним контрактам містити 1–500 символиM SK1 Ці методи виконують записи тільки тоді, коли їх експлицитно називають

Інші ресурси вебсайту

SendWebsiteRequestAsync<T> керує додатковими документованими ресурсами, в тому числі врятовані канали/ ціліM SK1 сегменти , деталі сеансу і повторення метадань. Поставка rel 'єрний шлях ресурсу веб-сайту; він відкидає абсолютні URLsM SK1 перехід та вбудова строки запиту. Идентифікатор веб-сайту та хост завжди приходять з конфігураціїM SK1

var goals = await data.SendWebsiteRequestAsync<JsonElement>(HttpMethod.Get, "goals",
    new Dictionary<string, string?> { ["page"] = "1", ["pageSize"] = "20" },
    cancellationToken: cancellationToken);

Metodа зберігає структурований JSON і дозволяє друкувати моделі результатів. Ресурс схеми та права залишаються тими, що у конфигурованому Umami сервері. Це робить не відкривати API konta-направлення ключами або адміністративні шляхиM SK1

Для Assistenta доступ, Umami M SK1 надає свій власний Сервер MCP. Використовуйте цей сервер з відповідним API ключом; цей пакет - HTTP аналітика klient, не Implementation MCP

Непрацездатність та anulація

Відповідь про проблеми транспортування UmamiResult<T>: МSK1 для проблеми з мережею 504 для HTTP тайм-аута , МSK2 для неправильних JSON відповідей МSK3 і статусу сервера для HTTP невдачі. Виражене anulування викликателя розповсюджується так: OperationCanceledException. Неправильні локальні аргументи та діапазон дати перед wysłanням запитів. Відповіді та невдачі спроби повторного спроб знищеніM SK1

Лише GET-запити отримують обмежені перехідні /429 ретрими в Rejestrі ІД. 401 реаuthentication is separately bounded to one retry не відібрано для тимчасових транспортних помилок. API-key M SK2 відповіді не запускають відхилення пароля. Logs omit authM SK1 cache tokens , payloads and query strings.

Validation and release

dotnet test Umami.Net.Test/Umami.Net.Test.csproj
scripts/test-umami-integration.sh # Spins up disposable Umami 3.4.0 + PostgreSQL; 51 real cases per target
dotnet build Umami.Net/Umami.Net.csproj -c Release
dotnet pack Umami.Net/Umami.Net.csproj -c Release --no-build -o /tmp/umami-pack

Пакет має ціль: net8.0, net 9.0 і netМSK2 використовувати ярлики релізу umamiv*.*.*; вебсайт release-* ярлики не публікують пакетів NuGet. Погляньте перегляд результатів та перевірки для використання на даний момент.

Установлення

Пакет доступний на NuGet...

This keeps documentation synchronized automatically. When I update the README on GitHub, the blog post stays in sync (within 24 hours).

Conclusion

Building this extension taught me several things:

  1. Preprocessing > Parsing - Handling fetch tags before Markdig ensures consistency
  2. Stale-While-Revalidate - This pattern is incredibly valuable for reliability
  3. Pluggable Storage - Different deployments need different solutions
  4. Events for Observability - Being able to monitor fetch operations is crucial
  5. Thread Safety Matters - Concurrent access needs careful handling
  6. Bonus Features - The package now includes a separate TOC extension for generating tables of contents

The extension is open source and available on NuGet:

Source code is on GitHub: scottgal/mostlylucidweb

If you're building a documentation site, blog, or any application that needs to include external markdown content, give it a try. It's designed to be simple to use but powerful enough for production deployments.

Finding related posts...
logo

© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.