diff --git a/src/libraries/System.CodeDom/src/PACKAGE.md b/src/libraries/System.CodeDom/src/PACKAGE.md new file mode 100644 index 00000000000000..2785a3e5888a38 --- /dev/null +++ b/src/libraries/System.CodeDom/src/PACKAGE.md @@ -0,0 +1,127 @@ +## About + + + +Provides functionality for dynamically generating and compiling source code using the Code Document Object Model (CodeDOM). + +It allows developers to represent code in a language-agnostic format and then generate code in multiple languages, such as C# and VB.NET. +The primary use cases include creating dynamic code generation tools, runtime code generation, and facilitating code analysis or transformation. + +For a new modern development consider using the [.NET Compiler Platform SDK](https://learn.microsoft.com/dotnet/csharp/roslyn-sdk/), in particular [Roslyn source generators](https://learn.microsoft.com/dotnet/csharp/roslyn-sdk/source-generators-overview#get-started-with-source-generators). + +## Key Features + + + +* Write code using a common object model that can be translated into multiple programming languages. +* Generate and compile code at runtime based on the CodeDOM. + +## How to Use + + + +Generating and compiling C# code: + +```csharp +using System.CodeDom; +using System.CodeDom.Compiler; +using Microsoft.CSharp; + +// Create a new CodeCompileUnit to hold the code +var compileUnit = new CodeCompileUnit(); + +// Create a namespace +var codeNamespace = new CodeNamespace("MyNamespace"); +compileUnit.Namespaces.Add(codeNamespace); + +// Create a class +var classDeclaration = new CodeTypeDeclaration("MyClass") +{ + IsClass = true +}; +codeNamespace.Types.Add(classDeclaration); + +// Add a simple method to the class +var method = new CodeMemberMethod +{ + Name = "HelloWorld", + ReturnType = new CodeTypeReference(typeof(void)), +}; +classDeclaration.Members.Add(method); + +var methodInvocation = new CodeMethodInvokeExpression(new CodeTypeReferenceExpression("Console"), + "WriteLine", + new CodePrimitiveExpression("Hello, World!")); +method.Statements.Add(methodInvocation); + +// Generate C# code from the CodeDOM structure +CodeDomProvider provider = new CSharpCodeProvider(); + +using (var writer = new StringWriter()) +{ + var codeGenereationOptions = new CodeGeneratorOptions() + { + BlankLinesBetweenMembers = false, + IndentString = " ", + }; + + provider.GenerateCodeFromCompileUnit(compileUnit, writer, codeGenereationOptions); + Console.WriteLine(writer.GetStringBuilder().ToString()); +} +``` + +This example generates: + +```csharp +//------------------------------------------------------------------------------ +// +// This code was generated by a tool. +// +// Changes to this file may cause incorrect behavior and will be lost if +// the code is regenerated. +// +//------------------------------------------------------------------------------ + +namespace MyNamespace { + + public class MyClass { + private void HelloWorld() { + Console.WriteLine("Hello, World!"); + } + } +} +``` + +## Main Types + + + +The main types provided by this library are: + +* `System.CodeDom.CodeObject` +* `System.CodeDom.CodeCompileUnit` +* `System.CodeDom.CodeNamespace` +* `System.CodeDom.CodeTypeDeclaration` +* `System.CodeDom.CodeMemberMethod` +* `System.CodeDom.CodeTypeReference` +* `System.CodeDom.CodeMethodInvokeExpression` +* `System.CodeDom.CodeTypeReferenceExpression` +* `System.CodeDom.CodePrimitiveExpression` +* `System.CodeDom.Compiler.CodeDomProvider` +* `System.CodeDom.Compiler.CodeGeneratorOptions` +* `Microsoft.CSharp.CSharpCodeProvider` +* `Microsoft.VisualBasic.VBCodeProvider` + +## Additional Documentation + + + +* [API documentation](https://learn.microsoft.com/dotnet/api/system.codedom) +* [Compile and generate dynamic source code](https://learn.microsoft.com/dotnet/framework/reflection-and-codedom/dynamic-source-code-generation-and-compilation) + +## Feedback & Contributing + + + +System.CodeDom is released as open source under the [MIT license](https://licenses.nuget.org/MIT). +Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime). diff --git a/src/libraries/System.CodeDom/src/System.CodeDom.csproj b/src/libraries/System.CodeDom/src/System.CodeDom.csproj index a987278ff05393..76ba0e1a9d3f64 100644 --- a/src/libraries/System.CodeDom/src/System.CodeDom.csproj +++ b/src/libraries/System.CodeDom/src/System.CodeDom.csproj @@ -6,19 +6,11 @@ false false true - Provides types that can be used to model the structure of a source code document and to output source code for that model in a supported language. - -Commonly Used Types: -System.CodeDom.CodeObject -System.CodeDom.Compiler.CodeDomProvider -Microsoft.CSharp.CSharpCodeProvider -Microsoft.VisualBasic.VBCodeProvider + Provides types that can be used to model the structure of a source code document and to output source code for that model in C# or Visual Basic. disable $(NoWarn);nullable - - false