JarvisTools.SkolaOnlineClient 1.0.2

SkolaOnlineClient

Lehká .NET knihovna pro přístup k API SkolaOnline (autentizace, informace o uživateli, rozvrhy apod.). Balíček je navržený jako NuGet balíček a podporuje konfiguraci přes appsettings.json (Options pattern) a registraci přes rozšiřující metodu AddSkolaOnlineClient.

Obsah tohoto README se použije jako PackageReadmeFile a zobrazí se na nuget.org.

Hlavní vlastnosti

• Podpora DI (rozhraní a registrace přes IServiceCollection).
• Konfigurace přes IOptions<T> / appsettings.json.
• Interní cache access tokenu pomocí IMemoryCache.
• XML dokumentace (IntelliSense) generovaná při sestavení.

Instalace

Nainstalujte balíček přes NuGet:

dotnet add package SkolaOnlineClient --version <verze>

Konfigurace

Knihovna očekává sekci konfigurace SkolaOnlineClient s poli Username a Password (nebo jinou konfigurací podle vašeho nasazení).

Příklad appsettings.json:

{
  "SkolaOnlineClient": {
    "Username": "honzaircing",
    "Password": "SUPER-HESLO-NEUVADEJTE-VEVERZOVACI"
  }
}

Bezpečnostní doporučení: neukládejte citlivá hesla do repozitáře. Pro vývoj použijte dotnet user-secrets, v CI použijte proměnné prostředí, nebo správce tajemství (Azure Key Vault apod.).

Chcete-li použít jiné zdroje konfigurace (např. environment variables), stačí je namapovat na stejnou sekci SkolaOnlineClient.

Registrace služby (recommended)

V Program.cs (ASP.NET Core / Generic Host) zaregistrujte klienta takto:

using SkolaOnlineClient;

var builder = WebApplication.CreateBuilder(args);

// načte sekci "SkolaOnlineClient" z appsettings/environment
builder.Services.AddSkolaOnlineClient(builder.Configuration);

var app = builder.Build();

AddSkolaOnlineClient provede:

• services.Configure<SkolaOnlineClientConfiguration>(configuration.GetSection("SkolaOnlineClient"))
• registraci HttpClient pro ISkolaOnlineService/SkolaOnlineService
• registraci IMemoryCache

Rychlý příklad použití (DI)

public class SomeService
{
    private readonly ISkolaOnlineService _skolaClient;

    public SomeService(ISkolaOnlineService skolaClient)
    {
        _skolaClient = skolaClient;
    }

    public async Task DoWorkAsync()
    {
        var user = await _skolaClient.GetUserInfo();
        var schedule = await _skolaClient.GetSchoolSchedule("student-id", DateOnly.FromDateTime(DateTime.Today), DateOnly.FromDateTime(DateTime.Today.AddDays(7)), "schoolYearId");
        // zpracovat výsledky
    }
}

Příklad bez DI (manuální vytvoření)

Pokud nechcete DI, můžete vytvořit instanci ručně (užitečné pro konzolové nástroje nebo testy):

using Microsoft.Extensions.Caching.Memory;
using Microsoft.Extensions.Options;

var config = new SkolaOnlineClientConfiguration
{
    Username = Environment.GetEnvironmentVariable("SKOLA_USERNAME") ?? string.Empty,
    Password = Environment.GetEnvironmentVariable("SKOLA_PASSWORD") ?? string.Empty
};

var options = Options.Create(config);
var memoryCache = new MemoryCache(new MemoryCacheOptions());
var service = new SkolaOnlineClient.Services.SkolaOnlineService(memoryCache, options);

var token = await service.GetToken();

API — vybrané metody

(tady zmiňujeme nejdůležitější veřejné metody; skutečné podpisy najdete v XML IntelliSense a reference doc)

• Task<string> GetToken() — získá access token (caching interně).
• Task<User> GetUserInfo() — vrátí informace o přihlášeném uživateli.
• Task<SchoolSchedule> GetSchoolSchedule(string studentId, DateOnly dateFrom, DateOnly dateTo, string schoolYearId) — načte rozvrh.

XML dokumentace / IntelliSense

V projektu je zapnuté generování XML dokumentace (<GenerateDocumentationFile>true</GenerateDocumentationFile>). Ta je zahrnuta v NuGet balíčku a poskytne IntelliSense popisy volajícím aplikacím.

Vytvoření a publikace NuGet balíčku

Lokálně vytvořte nupkg:

dotnet pack -c Release

Publikujte na nuget.org:

dotnet nuget push bin/Release/*.nupkg -k <API_KEY> -s https://api.nuget.org/v3/index.json

Doporučení: publikujte automaticky přes CI (GitHub Actions / Azure Pipelines) a udržujte tajné klíče v secure storage CI.

Metadata balíčku

Ujistěte se, že v SkolaOnlineClient.csproj jsou vyplněna metadata, která budou zobrazena na nuget.org (např. Description, Authors, PackageTags, RepositoryUrl, PackageLicenseExpression, PackageReadmeFile).

Bezpečnost

• Nikdy necommitujte Password do git repozitáře.
• Pro produkci používejte bezpečný store, např. Key Vault nebo připojení přes služby poskytovatele.

Licence

Tento projekt je licencovaný pod MIT (viz PackageLicenseExpression v .csproj).

Kontribuce

V případě zájmu o rozšíření nebo opravy otevřete issue nebo pull request v repozitáři: https://github.com/honzaircing/JarvisTools

Changelog

Krátký changelog udržujte v CHANGELOG.md v kořeni repozitáře.

Pokud chcete, můžu README upravit (více příkladů, detailní reference veřejného API nebo anglickou verzi) — napište, co přidat.