Repository navigation
feat(LLMsDocsGenerator): document service registration extensions #1323
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -157,13 +157,15 @@ void AppendComponentLink(ComponentInfo component) | |
| } | ||
|
|
||
| // Injected services | ||
| if (services.Count > 0) | ||
| var serviceTypes = services.Where(service => !service.IsServiceRegistrationExtension).ToList(); | ||
| var registrationExtensions = services.Where(service => service.IsServiceRegistrationExtension).ToList(); | ||
| if (serviceTypes.Count > 0) | ||
| { | ||
| _sb.AppendLine("## 服务及相关接口"); | ||
| _sb.AppendLine(); | ||
| _sb.AppendLine("公开的服务和相关接口;并非所有接口都由依赖注入注册。"); | ||
| _sb.AppendLine(); | ||
| foreach (var service in services) | ||
| foreach (var service in serviceTypes) | ||
| { | ||
| var localized = Localize(service.Summary, lang); | ||
| var summary = !string.IsNullOrEmpty(localized) ? $" - {TruncateSummary(localized, 60)}" : ""; | ||
|
|
@@ -172,11 +174,28 @@ void AppendComponentLink(ComponentInfo component) | |
| _sb.AppendLine(); | ||
| } | ||
|
|
||
| if (registrationExtensions.Count > 0) | ||
| { | ||
| _sb.AppendLine("## 服务注册扩展"); | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ⚪ Low · Extensions get the wrong category When the generated index is read by the CLI, Teach the index parser to assign a category to the service-registration section, or emit a heading level the parser recognizes. Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/MarkdownBuilder.cs` at line 179:
**Extensions get the wrong category**
When the generated index is read by the CLI, `LlmsDocsClient.ParseIndex` recognizes only `###` headings, so it leaves the category unchanged when it reaches this `##` section and assigns that stale (or empty) category to the extension entries. Callers of `ListAsync` receive misleading category values.
Teach the index parser to assign a category to the service-registration section, or emit a heading level the parser recognizes. |
||
| _sb.AppendLine(); | ||
| _sb.AppendLine("公开的 IServiceCollection 注册扩展方法;扩展类本身不是可注入的服务。"); | ||
| _sb.AppendLine(); | ||
| foreach (var extension in registrationExtensions) | ||
| { | ||
| _sb.AppendLine($"- [{extension.Name}](components/{extension.Name}.txt)"); | ||
| } | ||
| _sb.AppendLine(); | ||
| } | ||
|
|
||
| // Footer | ||
| _sb.AppendLine("---"); | ||
| _sb.AppendLine($"生成时间: {DateTime.UtcNow:yyyy-MM-dd}"); | ||
| _sb.AppendLine($"组件总数: {components.Count}"); | ||
| _sb.AppendLine($"服务总数: {services.Count}"); | ||
| _sb.AppendLine($"服务总数: {serviceTypes.Count}"); | ||
| if (registrationExtensions.Count > 0) | ||
| { | ||
| _sb.AppendLine($"服务注册扩展类型总数: {registrationExtensions.Count}"); | ||
| } | ||
|
|
||
| return _sb.ToString(); | ||
| } | ||
|
|
@@ -235,6 +254,12 @@ private static void BuildComponentSection(StringBuilder _sb, ComponentInfo compo | |
| } | ||
| } | ||
|
|
||
| if (component.IsServiceRegistrationExtension) | ||
| { | ||
| _sb.AppendLine("此类型提供服务注册扩展方法,不是可注入的服务。外部服务接口及配置类型的 API 请查阅项目实际引用版本的文档。"); | ||
| _sb.AppendLine(); | ||
| } | ||
|
|
||
| // Service registration (DI): extension services must be registered before use. | ||
| if (component.Registrations.Count > 0) | ||
| { | ||
|
|
@@ -348,7 +373,7 @@ private static void BuildComponentSection(StringBuilder _sb, ComponentInfo compo | |
| foreach (var method in component.PublicMethods.OrderBy(m => m.Name)) | ||
| { | ||
| var paramStr = string.Join(", ", method.Parameters.Select(p => $"{p.Item1} {p.Item2}")); | ||
| _sb.AppendLine($"- `{method.ReturnType} {method.Name}({paramStr})`"); | ||
| _sb.AppendLine($"- `{method.Signature ?? $"{method.ReturnType} {method.Name}({paramStr})"}`"); | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Generated docs accept injected Markdown When an attacker contributes a registration extension with an optional raw-string default containing Markdown or HTML delimiters, Escape the signature for Markdown or render it in a format that safely handles embedded backticks and newlines. Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/MarkdownBuilder.cs` at line 376:
**Generated docs accept injected Markdown**
When an attacker contributes a registration extension with an optional raw-string default containing Markdown or HTML delimiters, `BuildComponentSection` writes the source signature inside a single-backtick code span without escaping it, so embedded backticks or raw-string newlines break out of the span and inject Markdown or HTML into generated documentation consumed by renderers or agents.
Escape the signature for Markdown or render it in a format that safely handles embedded backticks and newlines. |
||
| var methodDescription = Localize(method.Description, lang); | ||
| if (!string.IsNullOrEmpty(methodDescription)) | ||
| { | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟡 Medium · Obsolete APIs appear supported
When an obsolete type or registration method uses a using alias for System.ObsoleteAttribute,
ComponentAnalyzercompares attribute syntax names in both type and method checks, so it includes the obsolete declaration in the generated index and documentation as supported.Resolve each attribute to its symbol and exclude declarations whose attribute symbol is
System.ObsoleteAttribute.Also at
tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:798-806.Prompt for AI agents