Skip to content

Microsoft library guidance

Use this checklist to distinguish configured behavior from compatibility guarantees when choosing Fundamentals packages. It covers selected .NET library, options, and logging recommendations, not TypeScript or every public API. The source links identify the assessed revision; this is not a repository-wide compliance certification.

Status Meaning
conforming The stated example supports the named recommendation within the row’s scope.
partial Some relevant evidence matches, but limits or gaps remain.
not-assessed No conclusion has been established. An omission is not an exemption.
authorized waiver An intentional departure is grounded in an existing applicable policy or explicit maintainer authorization.

Microsoft’s library guidance covers inclusiveness, stability, evolution, debugging, and trust. Its cross-platform targeting guidance recommends starting with net8.0 or later, while distinguishing modern .NET targeting from breadth targeting.

Recommendation or concern Status Fundamentals evidence and limits
Include a modern .NET target conforming The shared build properties configure Release for net10.0;net11.0 and Debug for net10.0. This is a configured-target observation for runtime projects that inherit these settings, not proof of published assets or platform support.
Distinguish runtime libraries from generators partial Cratis.Fundamentals provides the base library and bundles the type-discovery generator. Cratis.OpenTelemetry separately references hosting, exporter, and instrumentation packages. The type-discovery generator and the observability generator (Cratis.Observability.SourceGenerators, which replaces the deprecated forwarding package Cratis.Metrics.Roslyn) override the targets to netstandard2.0 and configure analyzer package paths. Their targets do not extend the runtime library’s reach or establish independently published artifacts.
Cross-platform, trimming, and AOT compatibility not-assessed IsAotCompatible in Fundamentals.csproj is a declaration, not an AOT or trimming audit. Runtime execution across operating systems and published-package compatibility have not been established by this checklist.
Debuggability, package trust, and evolution not-assessed Symbol/source properties configure embedded sources, symbols, and snupkg. Published symbols and package contents, metadata, signing, versioning, binary compatibility, and transitive dependency reach are not assessed.

Microsoft’s options guidance for library authors describes registration patterns for configuration and callbacks. Use the existing OpenTelemetry setup guide for host integration.

Recommendation or concern Status Fundamentals evidence and limits
Expose consumer configuration and options registration partial OpenTelemetryExtensions accepts an optional Action<CratisOpenTelemetryOptions> and offers an explicit IConfiguration overload. It directly creates the public application options, while registering SDK options through AddOptions and consuming SDK IOptions<T>. These are distinct: the callback is not evidence that CratisOpenTelemetryOptions itself has a complete IOptions<T> registration contract.
Configuration binding, validation, and updates not-assessed The assessed overload documents standard OTEL keys, not a named application-options section. Named-section conventions, reload/change notifications, and comprehensive validation against Microsoft’s options patterns remain unassessed. No additional overload or binding contract is implied.

Microsoft’s logging guidance for library authors discusses logger/factory selection when emitting logs and recommends source-generated logging for most situations. Configuring a host pipeline is different from emitting library logs.

Recommendation or concern Status Fundamentals evidence and limits
Structured, categorized, source-generated library logs not-assessed The applicable C# logging policy requires named structured parameters, ILogger<T>, and a separate partial logging class using LoggerMessage. This is policy, not an implementation survey. The OpenTelemetry pipeline enables scopes and formatted messages and conditionally configures export; it does not establish universal library-log adherence.
Bootstrap diagnostics without a host logger partial TypeDiscoveryEventSource emits type-universe diagnostics through EventSource. Its documented boundary is static initialization in a leaf package, before a container, configuration, or ILoggerFactory exists; taking a logging dependency there would introduce an initialization-order hazard. A host can bridge the events. This rationale is not a blanket waiver from Microsoft’s logging guidance.

The supplemental Microsoft standard exception guidance recommends ArgumentException or a subtype for bad arguments and InvalidOperationException for inappropriate object state. This is separate framework design guidance, not an additional rule inferred from the three library-author entry points above.

Recommendation or concern Status Scoped departure and authority
Use standard exception types for argument and state errors authorized waiver The applicable C# exception policy instead requires custom types derived from Exception, prohibits built-in exception types, and requires meaningful messages. Its rationale is to name what went wrong in domain terms. InvalidOpenTelemetryEndpoint is a concrete custom type for an invalid endpoint. The waiver records this standing policy departure, not universal source adherence: the keyed-service fallback also throws a built-in InvalidOperationException.

This checklist does not authorize new exceptions to policy. Maintainer approval of the checklist and its intentional departures remains pending; documenting the standing exception policy does not complete that approval. Reconsider the exception row if maintainers change the policy or the public error contract.

Reassess affected rows when public configuration, logging, target frameworks, or package behavior changes. New departures require maintainer approval. Keep unexamined areas not-assessed rather than extending an example into a repository-wide guarantee.