AdvisorSoft.Utils

Sdílené knihovny Advisor Software pro .NET 10, rozdělené do balíčků podle závislostí – aplikace si bere jen to, co potřebuje. Všechny balíčky mají stejnou verzi.

Návod na přechod aplikací (APLS, DocumentFlow) je v doc/adopce-apls-documentflow.md, změny v CHANGELOG.md.

Instalace

Balíčky jsou na firemním feedu https://nuget.advisor-soft.com/v3/index.json (čtení anonymní). Doporučené nuget.config s mapováním zdrojů, aby se balíčky nikdy nestáhly odjinud:

<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="advisor-soft" value="https://nuget.advisor-soft.com/v3/index.json" protocolVersion="3" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org"><package pattern="*" /></packageSource>
    <packageSource key="advisor-soft"><package pattern="AdvisorSoft.*" /></packageSource>
  </packageSourceMapping>
</configuration>

dotnet add package AdvisorSoft.Utils.Email

AdvisorSoft.Utils (jádro)

using AdvisorSoft.Utils.Text;       // "Žádost č. 12".ToSlug() → "zadost-c-12", RemoveDiacritics()
using AdvisorSoft.Utils.Querying;   // q.ApplySort("Nazev desc"), DateRanges.ThisWeek(), PredicateDate…
using AdvisorSoft.Utils.Security;   // HmacSignature, SignedToken, OneTimeToken
using AdvisorSoft.Utils.Files;      // FileSignature.DetectMimeType(name, header), FileNames.Sanitize(name)
using AdvisorSoft.Utils.Calendar;   // IcsCalendar.Write(...), IcsEvent
using AdvisorSoft.Utils.Mail;       // EmailAddressList.Normalize("a@x.cz, b@x.cz")
using AdvisorSoft.Utils.Diff;       // ObjectDiff.Compute(before, after, options)

• Filtrování podle dne v EF Core – PredicateDate.ExprOnDay(x => x.Datum, den) generuje Datum >= den AND Datum < den+1 místo CAST(Datum AS date), takže SQL může použít index.
• Podepsané odkazy – SignedToken.Create(payload, klic) / TryRead<T>(token, klic, out payload); expiraci si dejte do payloadu a ověřte po přečtení.
• Jednorázové tokeny – var (token, hash) = OneTimeToken.Generate(); do DB jen hash, ověření OneTimeToken.Matches(token, hash).
• Upload souborů – typ vždy podle obsahu: FileSignature.DetectMimeType(nazev, prvnich8Bajtu) (null = odmítnout), název přes FileNames.Sanitize.

AdvisorSoft.Utils.Email

using AdvisorSoft.Utils.Email;

builder.Services.AddAdvisorEmailSender(builder.Configuration, o =>
{
    o.DefaultAppPrefix = "[MOJE-APP] ";   // prefix předmětu, pokud ho konfigurace nenastaví
    // o.Mode = EmailSenderMode.Graph;    // vynucený režim (jinak EmailSender:Mode)
});

Registrace přidá přímého odesílatele pod konkrétním typem, pod klíčem EmailSenderKeys.Direct a jako výchozí IEmailSender (jedna instance). Výchozí registraci lze přebít vlastním wrapperem (např. fronta úloh).

{
  "EmailSender": {
    "Mode": "Graph",
    "TenantId": "…", "ClientId": "…", "ClientSecret": "…",
    "FromEmail": "automat@firma.cz",
    "AppPrefix": "[APP-TEST] ",
    "UseTestEmails": true,
    "TestEmails": "vyvojar@firma.cz",
    "CCEmails": "",
    "TemplatesFolder": "EmailTemplates"
  }
}

• UseTestEmails = true přesměruje veškerou poštu na TestEmails (středníkem oddělené).
• CCEmails = skrytá kopie všech e-mailů v produkčním režimu (místo natvrdo zapsaných adres v kódu).
• TemplatesFolder – relativní vůči ContentRootPath, nebo absolutní; ReadTemplate(soubor) čte odtud.
• Graph posílá MIME obsah (limit 4 MB po zakódování); Exchange Online potřebuje v tenantu povolené SMTP AUTH.

AdvisorSoft.Utils.Html

using AdvisorSoft.Utils.Html;

string html = SafeMarkdown.ToHtml(poznamkaOdUzivatele);        // bezpečné do MarkupString / Html.Raw
string email = SafeMarkdown.ToEmailHtml(poznamkaOdUzivatele);  // užší whitelist pro e-mail
string cisty = HtmlSanitization.Default.Sanitize(htmlZEditoru); // sanitizace hotového HTML
string docs = new MarkdownService().MdToHtml(dokumentaceZRepa); // jen důvěryhodný obsah (nesanitizuje)

AdvisorSoft.Utils.Czech

using AdvisorSoft.Utils.Czech;
using AdvisorSoft.Utils.Czech.Ares;
using AdvisorSoft.Utils.Czech.Validation;

IcoValidator.Normalize("6947");               // "00006947" (null = neplatné)
BirthNumberValidator.TryParse("736228/5161", out var narozen, out var pohlavi);
BankAccountValidator.IsValid("19-2000145399/0800");
CzechPlural.Format(5, "terminál", "terminály", "terminálů"); // "5 terminálů"

builder.Services.AddAresClient()               // IAresClient
    .AddStandardResilienceHandler();           // odolnost dle volby aplikace (Microsoft.Extensions.Http.Resilience)

AresLookupResult r = await ares.LookupAsync(ico, nazev);
if (r.IsFound) { var (ulice, mesto) = AresAddressFormatter.Split(r.First!.Address); }

Vývoj

dotnet build AdvisorSoft.Utils.slnx
dotnet test AdvisorSoft.Utils.slnx

Verze = git tag X.Y.Z (MinVer). Vydání: /publish v Claude Code, resp. nugetpub.ps1 (API klíč v NUGET_API_KEY). Lokální ladění s konzumentem bez publikace: deploy/deploy-nuget-local.ps1 -Version 1.0.1-local.1.