{"id":28928231,"url":"https://github.com/ktsu-dev/sdk","last_synced_at":"2026-01-26T01:08:11.214Z","repository":{"id":290005116,"uuid":"973088994","full_name":"ktsu-dev/Sdk","owner":"ktsu-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-17T02:07:14.000Z","size":422,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-17T14:35:52.493Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ktsu-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":"COPYRIGHT.md","agents":null,"dco":null,"cla":null}},"created_at":"2025-04-26T08:26:07.000Z","updated_at":"2026-01-17T02:07:19.000Z","dependencies_parsed_at":"2025-05-15T13:21:40.142Z","dependency_job_id":"a120cbf7-5350-41a4-b4a6-7352fe01a799","html_url":"https://github.com/ktsu-dev/Sdk","commit_stats":null,"previous_names":["ktsu-dev/sdk"],"tags_count":100,"template":false,"template_full_name":null,"purl":"pkg:github/ktsu-dev/Sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FSdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FSdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FSdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FSdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ktsu-dev","download_url":"https://codeload.github.com/ktsu-dev/Sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FSdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28763198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T00:37:26.264Z","status":"ssl_error","status_checked_at":"2026-01-26T00:37:25.959Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-22T14:12:36.197Z","updated_at":"2026-01-26T01:08:11.198Z","avatar_url":"https://github.com/ktsu-dev.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ktsu.Sdk\n\nA comprehensive, robust MSBuild-based SDK for .NET projects that standardizes configuration, metadata management, and package workflows. Features intelligent project structure detection, hierarchical solution discovery, and path-based namespace generation. Supports multiple .NET versions (.NET 5.0+, .NET Standard 2.0/2.1) with optimizations for .NET 9.0+.\n\n## Quick Start\n\n### Installation\n\nAdd the SDK to your global.json (recommended):\n\n```json\n{\n  \"sdk\": {\n    \"version\": \"10.0.0\",\n    \"rollForward\": \"latestMinor\"\n  },\n  \"msbuild-sdks\": {\n    \"ktsu.Sdk\": \"2.2.0\",\n    \"ktsu.Sdk.ConsoleApp\": \"2.2.0\",\n    \"ktsu.Sdk.App\": \"2.2.0\"\n  }\n}\n```\n\nOr reference directly in your project file:\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cSdk Name=\"ktsu.Sdk\" Version=\"2.2.0\" /\u003e\n\n  \u003cPropertyGroup\u003e\n    \u003c!-- Your project-specific properties --\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\n### Basic Usage\n\nFor a library project:\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cSdk Name=\"ktsu.Sdk\" /\u003e\n\u003c/Project\u003e\n```\n\nFor a console application:\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cSdk Name=\"ktsu.Sdk\" /\u003e\n  \u003cSdk Name=\"ktsu.Sdk.ConsoleApp\" /\u003e\n\u003c/Project\u003e\n```\n\nFor a GUI application:\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cSdk Name=\"ktsu.Sdk\" /\u003e\n  \u003cSdk Name=\"ktsu.Sdk.App\" /\u003e\n\u003c/Project\u003e\n```\n\n## Key Features\n\n### 🏗️ **Intelligent Project Structure**\n\n- **Hierarchical Solution Discovery**: Automatically finds solution files up to 5 directory levels above the project\n- **Path-Based Namespace Generation**: Creates namespaces from directory structure between solution and project\n- **Smart Project Detection**: Automatically detects primary, console, GUI, and test project types\n- **Nested Project Support**: Works seamlessly with deeply nested project structures\n\n### 🛡️ **Robust Error Handling**\n\n- **Safe Array Operations**: Prevents index-out-of-bounds errors in MSBuild expressions\n- **Null-Safe String Operations**: Comprehensive null/empty checks for all string manipulations\n- **Graceful Fallbacks**: Provides sensible defaults when metadata files or properties are missing\n- **Comprehensive Validation**: Built-in validation for all file operations and property access\n\n### 📦 **Advanced Package Management**\n\n- **Multi-Target Support**: .NET 10.0, 9.0, 8.0, 7.0, 6.0, 5.0, .NET Standard 2.0/2.1 (default: net10.0)\n- **MSBuildSdk Packaging**: Properly configured for MSBuild SDK project packaging\n- **Automatic Metadata Integration**: Seamlessly includes markdown files in package metadata\n- **Package Validation**: Built-in API compatibility and package validation\n- **Source Link Integration**: Automatic GitHub and Azure Repos source linking for debugging\n- **Central Package Management**: Requires and works with Directory.Packages.props\n\n### 🔧 **Development Workflow**\n\n- **Analyzer-Enforced Requirements**: Roslyn analyzers (KTSU0001/KTSU0002) ensure proper package dependencies and internals visibility with helpful diagnostics and code fixers\n- **Internals Visibility**: Code fixer to easily add InternalsVisibleTo attributes for test projects\n- **GitHub Integration**: Built-in support for GitHub workflows and CI/CD\n- **Cross-Platform Support**: Compatible with Windows, macOS, and Linux\n- **Documentation Generation**: Automated XML documentation file generation\n- **Strict Code Quality**: Nullable enabled, warnings as errors, latest analyzer rules\n\n## SDK Components\n\nThis repository contains three SDK packages:\n\n### **ktsu.Sdk** (Core)\n\nThe base SDK that all projects should reference. Provides:\n\n- Solution and project discovery\n- Namespace generation\n- Metadata file integration\n- Multi-target framework support\n- Automatic project references\n- Package configuration\n- Code quality defaults\n\n### **ktsu.Sdk.ConsoleApp**\n\nExtension SDK for console applications. Adds:\n\n- `OutputType=Exe` configuration\n- Single target framework (net10.0)\n- Cross-platform console optimizations\n\n### **ktsu.Sdk.App**\n\nExtension SDK for GUI applications (ImGui, WinForms, WPF, etc.). Adds:\n\n- `OutputType=WinExe` on Windows (no console window)\n- `OutputType=Exe` on other platforms\n- Single target framework (net10.0)\n- Platform-specific runtime configurations\n\n## Detailed Usage\n\n### Setup Requirements\n\n1. **Central Package Management**: Create a `Directory.Packages.props` file at your solution root:\n\n```xml\n\u003cProject\u003e\n  \u003cPropertyGroup\u003e\n    \u003cManagePackageVersionsCentrally\u003etrue\u003c/ManagePackageVersionsCentrally\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\n1. **Metadata Files**: Create these optional markdown files at your solution root (they will be automatically included in NuGet packages):\n   - `AUTHORS.md` - Used for namespace generation and package authors\n   - `VERSION.md` - Version number (can be managed by build scripts)\n   - `DESCRIPTION.md` - Package description\n   - `CHANGELOG.md` - Release notes\n   - `LICENSE.md` - License information\n   - `COPYRIGHT.md` - Copyright notice\n   - `TAGS.md` - NuGet package tags\n   - `README.md` - Package documentation\n   - `AUTHORS.url` - URL to author/organization\n   - `PROJECT.url` - URL to project repository\n\n2. **icon.png**: Optional package icon at solution root\n\n### Overriding Defaults\n\nThe SDK provides sensible defaults, but you can override any property:\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cSdk Name=\"ktsu.Sdk\" /\u003e\n\n  \u003cPropertyGroup\u003e\n    \u003c!-- Override target frameworks --\u003e\n    \u003cTargetFrameworks\u003enet10.0;net9.0\u003c/TargetFrameworks\u003e\n\n    \u003c!-- Override namespace --\u003e\n    \u003cRootNamespace\u003eMyCompany.MyProject\u003c/RootNamespace\u003e\n\n    \u003c!-- Disable nullable if needed --\u003e\n    \u003cNullable\u003edisable\u003c/Nullable\u003e\n\n    \u003c!-- Allow warnings in test projects --\u003e\n    \u003cTreatWarningsAsErrors Condition=\"$(IsTestProject) == 'true'\"\u003efalse\u003c/TreatWarningsAsErrors\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\n### Project Type Detection\n\nThe SDK automatically detects different project types in your solution:\n\n- **Primary Project**: The main project of your solution (YourSolution, YourSolution.Core)\n- **Console Projects**: Command-line interface projects (YourSolution.CLI, YourSolution.Cli, YourSolutionCli, YourSolutionCLI, YourSolution.ConsoleApp, YourSolution.Console)\n- **GUI App Projects**: Application projects (YourSolution.App, YourSolutionApp, YourSolution.WinApp, YourSolutionWinApp, YourSolution.ImGuiApp, YourSolutionImGuiApp)\n- **Test Projects**: Test projects (YourSolution.Test, YourSolution.Tests, YourSolutionTest, YourSolutionTests)\n\nEach project type receives appropriate default settings, references, and output configurations (console apps vs. GUI apps).\n\n### Intelligent Namespace Generation\n\nThe SDK creates intelligent namespaces based on your project's directory structure:\n\n**Examples:**\n\n```\nMySolution/src/Core/Utils/MyProject.csproj\n→ ProjectNamespace: src.Core.Utils.MyProject\n\nMySolution/libs/MyLib/MyLib.csproj  \n→ ProjectNamespace: libs.MyLib (already ends with project name)\n\nMySolution/MyApp/MyApp.csproj\n→ ProjectNamespace: MyApp (directory equals project name)\n```\n\n**Final Namespace Pattern:**\n`{AuthorsNamespace}.{ProjectNamespace}` where AuthorsNamespace comes from AUTHORS.md\n\n### Hierarchical Solution Discovery  \n\nThe SDK automatically searches for solution files up the directory hierarchy:\n\n```\nMyProject/                     ← Level 3: Check here  \n├── MyProject.sln             ← Found! Use this directory\n└── apps/                     ← Level 2: Check here\n    └── frontend/             ← Level 1: Check here  \n        └── src/              ← Level 0: Start here (project directory)\n            └── MyApp.csproj\n```\n\nThis enables the SDK to work with any nested project structure without configuration.\n\n## Advanced Configuration Features\n\n### Analyzer-Enforced Requirements\n\nThe SDK automatically includes the `ktsu.Sdk.Analyzers` package (with version synchronization) that enforces proper project configuration with helpful diagnostics and code fixers:\n\n**KTSU0001 (Error)**: Projects must include required standard packages\n- Enforces SourceLink packages (GitHub, Azure Repos)\n- Enforces Polyfill package for non-test projects\n- Enforces compatibility packages (System.Memory, System.Threading.Tasks.Extensions) based on target framework\n- Diagnostic message includes package name and version number\n\n**KTSU0002 (Error)**: Projects must expose internals to test projects\n- Code fixer automatically adds `[assembly: InternalsVisibleTo(...)]` attribute\n- Use Ctrl+. (Quick Actions) to apply the fix\n\n**Polyfill Configuration**: For non-test projects, the SDK automatically enables:\n- `PolyEnsure=true` - Enables ensure/guard clause polyfills\n- `PolyNullability=true` - Enables nullability-related polyfills\n\nThese analyzers ensure consistent project structure while giving you explicit control over dependencies.\n\n### Available Properties\n\nThe SDK makes these properties available for conditional logic in your project files:\n\n**Project Type Detection:**\n\n- `IsPrimaryProject` - True if this is the main library project\n- `IsCliProject` - True if this is a console application\n- `IsAppProject` - True if this is a GUI application\n- `IsTestProject` - True if this is a test project\n\n**Project Type Existence:**\n\n- `PrimaryProjectExists` - True if primary project was found\n- `CliProjectExists` - True if CLI project was found\n- `AppProjectExists` - True if app project was found\n- `TestProjectExists` - True if test project was found\n\n**Project Paths:**\n\n- `SolutionDir` - Path to solution directory\n- `SolutionPath` - Full path to .sln file\n- `SolutionName` - Solution name without extension\n- `PrimaryProjectPath` - Path to primary project\n- `TestProjectPath` - Path to test project\n\n**Namespace Properties:**\n\n- `AuthorsNamespace` - Namespace prefix from AUTHORS.md\n- `ProjectNamespace` - Namespace from directory path\n- `RootNamespace` - Final combined namespace\n- `TestProjectNamespace` - Namespace for test project\n\n**Package Properties:**\n\n- `IsPackable` - True for library projects\n- `IsPublishable` - True for executable projects\n- `IsExecutable` - True if OutputType is Exe or WinExe\n- `IsLibrary` - True if OutputType is Library and not a test project\n\nUse these in your project files:\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003c!-- Example: Only pack if not a prerelease --\u003e\n  \u003cIsPackable Condition=\"$(IsPrerelease) == 'true'\"\u003efalse\u003c/IsPackable\u003e\n\n  \u003c!-- Example: Different settings for test projects --\u003e\n  \u003cSomeProperty Condition=\"$(IsTestProject) == 'true'\"\u003eTestValue\u003c/SomeProperty\u003e\n\u003c/PropertyGroup\u003e\n```\n\n### Robust Error Handling\n\nThe SDK includes comprehensive error handling to prevent common MSBuild failures:\n\n- **Safe Array Access**: Prevents \"index out of bounds\" errors when accessing file lists or string arrays\n- **Null Property Checks**: All string operations include null/empty validation  \n- **File Existence Validation**: All file operations verify existence before processing\n- **Graceful Degradation**: Missing metadata files don't cause build failures\n\n### Standardized Package Creation\n\nLibrary projects are automatically configured for NuGet packaging with:\n\n- **Automatic Metadata Population**: Uses markdown files for package description, changelog, etc.\n- **Source Link Integration**: Enables source code debugging for published packages\n- **Package Validation**: Built-in API compatibility and package structure validation\n- **Multi-Framework Support**: Targets multiple .NET versions simultaneously\n\n### Cross-Platform Compatibility\n\nProjects are configured with multiple runtime identifiers:\n\n- **Windows**: `win-x64`, `win-x86`, `win-arm64`\n- **macOS**: `osx-x64`, `osx-arm64`\n- **Linux**: `linux-x64`, `linux-arm64`\n\n### Advanced Testing Support\n\n- **Automatic InternalsVisibleTo**: Test projects automatically access internal members\n- **Test Project Detection**: Identifies and configures test projects with appropriate settings\n- **Relaxed Warnings**: Test projects suppress documentation and code style warnings\n\n## Automatic Package References\n\nThe SDK enforces (via analyzers) that projects include these NuGet packages:\n\n### Source Link Support (All Projects)\n\n- **Microsoft.SourceLink.GitHub** - GitHub source linking for debugging\n- **Microsoft.SourceLink.AzureRepos.Git** - Azure Repos source linking\n\n### Polyfills (Non-Test Projects)\n\n- **Polyfill** - Modern language feature support for older frameworks, with automatic configuration for PolyEnsure and PolyNullability source generators\n\n### Compatibility Packages (Framework-Specific)\n\n- **System.Memory** - For .NET Standard and .NET Framework\n- **System.Threading.Tasks.Extensions** - For netstandard2.0, netcoreapp2.0, and .NET Framework\n\n### Analyzer Package (Non-Test Projects)\n\n- **ktsu.Sdk.Analyzers** - Automatically included with version synchronization to enforce SDK requirements\n\n## Code Quality Defaults\n\nThe SDK enforces strict code quality standards by default:\n\n### Compiler Settings\n\n- **LangVersion**: `latest` - Use latest C# language features\n- **Nullable**: `enable` - Nullable reference types enabled\n- **TreatWarningsAsErrors**: `true` - All warnings treated as errors\n- **ImplicitUsings**: `enable` - Implicit global usings enabled\n\n### Code Analysis\n\n- **AnalysisLevel**: `latest-all` - All latest analyzer rules enabled\n- **EnableNETAnalyzers**: `true` - .NET code analyzers enabled\n- **EnforceCodeStyleInBuild**: `true` - Code style rules enforced during build\n\n### Suppressed Warnings\n\nThe following warnings are suppressed globally:\n\n- **CA1724**: Type names should not match namespaces\n- **CA1034**: Nested types should not be visible\n- **CA1000**: Do not declare static members on generic types\n- **CA2260**: Implement ISerializable correctly\n- **CA1515**: Override methods should call base methods\n\nAdditional suppressions for test projects:\n\n- **CS1591**: Missing XML comment\n- **CA2225**: Operator overloads have named alternates\n- **IDE0022**: Use expression body for methods\n- **IDE0058**: Expression value is never used\n- **CA1305**: Specify IFormatProvider\n- **CA5394**: Do not use insecure randomness\n- **CA1707**: Identifiers should not contain underscores\n\n### Runtime Configuration\n\n- **InvariantGlobalization**: `true` - Invariant culture for better performance\n- **NeutralLanguage**: `en-US`\n\n## Troubleshooting\n\n### Package Restore Fails\n\n**Problem**: NuGet restore fails with \"ManagePackageVersionsCentrally is not enabled\"\n\n**Solution**: Ensure `Directory.Packages.props` exists at your solution root with `ManagePackageVersionsCentrally` enabled.\n\n### Namespace Generation Issues\n\n**Problem**: Generated namespace doesn't match expectations\n\n**Solution**:\n\n- Check that `AUTHORS.md` exists and contains valid content\n- The namespace format is: `{FirstPartOfAuthors}.{PathToProject}.{ProjectName}`\n- You can always override with `\u003cRootNamespace\u003e` in your project file\n\n### Build Warnings as Errors\n\n**Problem**: Build fails due to warnings being treated as errors\n\n**Solution**: Either fix the warnings or selectively disable warnings:\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003cNoWarn\u003e$(NoWarn);CA1234;IDE5678\u003c/NoWarn\u003e\n\u003c/PropertyGroup\u003e\n```\n\n### Multi-Target Framework Issues\n\n**Problem**: Project builds for too many frameworks\n\n**Solution**: Override `TargetFrameworks` for specific projects:\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003c!-- Single target for applications --\u003e\n  \u003cTargetFramework\u003enet10.0\u003c/TargetFramework\u003e\n  \u003cTargetFrameworks\u003e\u003c/TargetFrameworks\u003e\n\u003c/PropertyGroup\u003e\n```\n\n### Solution Not Found\n\n**Problem**: SDK reports it cannot find a solution file\n\n**Solution**: The SDK searches up to 5 directory levels. Ensure your project is within 5 levels of your .sln file, or manually set `\u003cSolutionDir\u003e` in your project.\n\n## Requirements\n\n- .NET SDK 5.0 or later (optimized for .NET SDK 10.0)\n- Central Package Management (Directory.Packages.props)\n\n## License\n\nSee the [LICENSE.md](LICENSE.md) file for license information.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktsu-dev%2Fsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fktsu-dev%2Fsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktsu-dev%2Fsdk/lists"}