From 8a21980b7763af7667ee2849ad439e07a5dc0228 Mon Sep 17 00:00:00 2001 From: Hirotada Kobayashi Date: Sun, 14 Apr 2024 11:26:49 +0900 Subject: [PATCH] Release 0.6.0-beta --- ...assDiagramGenerator.SourceGenerator.csproj | 28 +-- .../README.md | 163 ++++++++++++++++-- uml/source-generator/0414-001.svg | 1 + uml/source-generator/0414-002.svg | 1 + uml/source-generator/0414-003.svg | 1 + 5 files changed, 167 insertions(+), 27 deletions(-) create mode 100644 uml/source-generator/0414-001.svg create mode 100644 uml/source-generator/0414-002.svg create mode 100644 uml/source-generator/0414-003.svg diff --git a/src/PlantUmlClassDiagramGenerator.SourceGenerator/PlantUmlClassDiagramGenerator.SourceGenerator.csproj b/src/PlantUmlClassDiagramGenerator.SourceGenerator/PlantUmlClassDiagramGenerator.SourceGenerator.csproj index 034fb0d..ad61cd5 100644 --- a/src/PlantUmlClassDiagramGenerator.SourceGenerator/PlantUmlClassDiagramGenerator.SourceGenerator.csproj +++ b/src/PlantUmlClassDiagramGenerator.SourceGenerator/PlantUmlClassDiagramGenerator.SourceGenerator.csproj @@ -24,20 +24,22 @@ README.md git plantuml;SourceGenerator - [0.5.1-beta] - 1. Added the following csproj properties: - - OutputDir: Specifies the output directory. - - AttributeRequired: A flag to indicate whether attributes are required. When set to false, classes without the PlantUmlDiagram attribute will be included in the output. - - IncludeMemberAccessibilities: Specifies the accessibility of members to include in the output. - - ExcludeMemberAccessibilities: Specifies the accessibility of members to exclude from the output. - 2. Added PlantUmlIgnore attribute: - This attribute can be applied to types, properties, methods, etc., to exclude them from the output. - 3. Changed the output folder structure: - Created folders based on namespaces and placed PlantUML files within them. + [0.6.0-beta] +- Partially deprecated properties that can be configured in project files (.csproj). + From this version onwards, only `PlantUmlGenerator_OutputDir` is configurable. +- Modified the `PlantUmlDiagramAttribute` to be applicable at the assembly level. + When applied at the assembly level, it targets all types defined within it for output. +- Added the `PlantUmlAssociationAttribute`. + This allows for the definition of custom associations. +- Added the `PlantUmlIgnoreAssociationAttribute`. + Attach this attribute to members or method parameters where associations are not desired, thereby excluding them from association creation. +- Introduced the `PlantUmlExtraAssociationTargetsAttribute`. + This allows for additional specification of types targeted for association creation. + MIT - 0.5.1.0 - 0.5.1.0 - 0.5.1-beta + 0.6.0.0 + 0.6.0.0 + 0.6.0-beta diff --git a/src/PlantUmlClassDiagramGenerator.SourceGenerator/README.md b/src/PlantUmlClassDiagramGenerator.SourceGenerator/README.md index defa96d..fdbec19 100644 --- a/src/PlantUmlClassDiagramGenerator.SourceGenerator/README.md +++ b/src/PlantUmlClassDiagramGenerator.SourceGenerator/README.md @@ -37,31 +37,25 @@ Add the following section to your project file (.csproj): ```xml - - - $(ProjectDir)generated-uml - false - All - None ``` |Property|Description|Default| |--|--|--| |PlantUmlGenerator_OutputDir|Specifies the directory where the generated UML files will be placed. If you want to establish associations between different projects, specify the same directory for all related projects.|$(ProjectDir)generated_uml| -|PlantUmlGenerator_AttributeRequierd|Set to true if you want to output only types with the PlantUmlDiagramAttribute, or false if you want to output all types defined within the project.|true| -|PlantUmlGenerator_IncludeMemberAccessibilities|Specifies the accessibilities of members to include in the output. Possible values are as follows:
・None
・Public
・Protected
・Internal
・ProtectedInternal
・PrivateProtected
・Private
・All
You can specify multiple values separated by commas.
Example: Public,Protected|All| -|PlantUmlGenerator_ExcludeMemberAccessibilities|Specifies the accessibilities of members to exclude from the output. The format of specification is the same as PlantUmlGenerator_IncludeMemberAccessibilities.|None| - ### 3. Setting Attribute Values Set attribute values for types and their members as needed. #### 3.1 PlantUmlDiagramAttribute -If the project setting `PlantUmlGenerator_AttributeRequierd` is set to true, you need to add this attribute to the types you want to include in the output. +You can apply this attribute to assembly and type definitions (such as classes, structures, interfaces, and enumerations). Types that have this attribute will be included in the class diagram output. If applied to an assembly, it includes all types defined within that assembly. + +```cs +[assembly:PlantUmlDiagram] +``` ```cs [PlantUmlDiagram] @@ -100,7 +94,7 @@ class ClassA #### 3.2 PlantUmlIgnoreAttribute -If the project setting `PlantUmlGenerator_AttributeRequierd` is set to false, all types defined within the project will be included in the output. If you want to exclude certain types from the output, you can apply the `PlantUmlIgnoreAttribute` to those types. +If you define the `PlantUmlDiagramAttribute` at the assembly level, all types defined within that assembly will be included in the class diagram output. However, if you want to exclude specific types from the output, you can apply the `PlantUmlIgnoreAttribute` to those types. ```csharp [PlantUmlIgnore] @@ -131,9 +125,137 @@ class ClassA public void MethodB(){} } ``` +![classA](/uml/source-generator/0302-003.svg) +#### PlantUmlAssociationAttribute +This attribute is used to annotate members or method parameters to create custom associations. The properties below specify the details of the association to be created. Here, the type to which the attribute is attached is referred to as the "Root Type," and the type associated with it is referred to as the "Leaf Type." + +|プロパティ|型|説明| +|--|--|--| +|Node|string|Specifies a string corresponding to the type of association (e.g., o--, ..>).| +|LeafType|System.Type|Specifies the type on the leaf side.| +|RootLabel|string|Specifies the label to be added on the root side.| +|NodeLabel|string|Specifies the label to be added on the line connecting the root and leaf.| +|LeafLabel|string|Specifies the label to be added on the leaf side.| -![classA](/uml/source-generator/0302-003.svg) + +```cs +internal class SampleModel +{ + private readonly ILogger logger; + + [PlantUmlAssociation("*--", + LeafType = typeof(Item), + RootLabel = "IDictionary", + LeafLabel = "*", + NodeLabel = nameof(Items))] + public IDictionary Items { get; } = new Dictionary(); + + public SampleModel([PlantUmlAssociation("..>", NodeLabel = "Injection")] ILogger logger) + { + this.logger = logger; + } +} +``` + +``` +@startuml SampleModel +class SampleModel { + - <> logger : ILogger + + <> Items : IDictionary <> + + SampleModel(logger : ILogger) +} +SampleModel o-l- ILogger : logger +SampleModel "IDictionary" *-- "*" Item : Items +SampleModel ..> ILogger : Injection +@enduml +``` + +![0414-001](/uml/source-generator/0414-001.svg) + +#### PlantUmlIgnoreAssociationAttribute +By attaching it to members you don't want to create associations with, this attribute suppresses the automatic generation of associations. + +```csharp +internal class SampleModel +{ + [PlantUmlIgnoreAssociation] + private readonly ILogger logger; + + [PlantUmlAssociation("*--", + LeafType = typeof(Item), + RootLabel = "IDictionary", + LeafLabel = "*", + NodeLabel = nameof(Items))] + public IDictionary Items { get; } = new Dictionary(); + + public SampleModel([PlantUmlIgnoreAssociation] ILogger logger) + { + this.logger = logger; + } +} +``` + +``` +@startuml SampleModel +class SampleModel { + - <> logger : ILogger + + <> Items : IDictionary <> + + SampleModel(logger : ILogger) +} +SampleModel "IDictionary" *-- "*" Item : Items +@enduml +``` + +![0414-002](/uml/source-generator/0414-002.svg) + +#### PlantUmlExtraAssociationTargetsAttribute +Specify additional types to be targeted for association. +In this tool, the following conditions determine which types are targeted for association: +- Types that are output targets within the project. +- Types for which a .puml file exists in the output folder. + +To create associations with types other than those mentioned above, register them using the `PlantUmlExtraAssociationTargetsAttribute`. This attribute can be applied to both assemblies and type definitions. + +```csharp +[assembly: PlantUmlExtraAssociationTargets( + typeof(KeyValuePair<,>), + typeof(System.Net.Http.HttpClient))] + +[PlantUmlExtraAssociationTargets(typeof(System.IO.Textwriter))] +internal class SampleModel +{ + private HttpClient httpClient; + public IDictionary Items { get; set; } = new Dictionary(); + + public SampleModel(HttpClient httpClient) + { + this.httpClient = httpClient; + } + + public void Write(TextWriter writer) + { + writer.Write("hoge"); + } +} +``` + +``` +@startuml SampleModel +class SampleModel { + - httpClient : HttpClient + + Items : IDictionary <> <> + + SampleModel(httpClient : HttpClient) + + Write(writer : TextWriter) : void +} +SampleModel o-- HttpClient : httpClient +SampleModel *-- "*" "KeyValuePair`2" : Items +SampleModel ..> HttpClient +SampleModel ..> TextWriter +@enduml +``` + +![0414-003](/uml/source-generator/0414-003.svg) ## Specification @@ -922,7 +1044,20 @@ class Parameters <> { ![Example2](/uml/source-generator/0302-014.svg) -## Release Note +## Release Notes + +### [0.6.0-beta] +- Partially deprecated properties that can be configured in project files (.csproj). + From this version onwards, only `PlantUmlGenerator_OutputDir` is configurable. +- Modified the `PlantUmlDiagramAttribute` to be applicable at the assembly level. + When applied at the assembly level, it targets all types defined within it for output. +- Added the `PlantUmlAssociationAttribute`. + This allows for the definition of custom associations. +- Added the `PlantUmlIgnoreAssociationAttribute`. + Attach this attribute to members or method parameters where associations are not desired, thereby excluding them from association creation. +- Introduced the `PlantUmlExtraAssociationTargetsAttribute`. + This allows for additional specification of types targeted for association creation. + ### [0.5.1-beta] 1. Added the following csproj properties: diff --git a/uml/source-generator/0414-001.svg b/uml/source-generator/0414-001.svg new file mode 100644 index 0000000..465e398 --- /dev/null +++ b/uml/source-generator/0414-001.svg @@ -0,0 +1 @@ +SampleModel«readonly» logger : ILogger«readonly» Items : IDictionary<string, Item> «get»SampleModel(logger : ILogger)ILoggerItemloggerInjectionItemsIDictionary<string,Item>* \ No newline at end of file diff --git a/uml/source-generator/0414-002.svg b/uml/source-generator/0414-002.svg new file mode 100644 index 0000000..4456f99 --- /dev/null +++ b/uml/source-generator/0414-002.svg @@ -0,0 +1 @@ +SampleModel«readonly» logger : ILogger«readonly» Items : IDictionary<string, Item> «get»SampleModel(logger : ILogger)ItemItemsIDictionary<string,Item>* \ No newline at end of file diff --git a/uml/source-generator/0414-003.svg b/uml/source-generator/0414-003.svg new file mode 100644 index 0000000..af56b33 --- /dev/null +++ b/uml/source-generator/0414-003.svg @@ -0,0 +1 @@ +SampleModelhttpClient : HttpClientItems : IDictionary<string, Item> «get» «set»SampleModel(httpClient : HttpClient)Write(writer : TextWriter) : voidHttpClientKeyValuePair`2TextWriterhttpClientItems* \ No newline at end of file