From 24b2f2b534c1df82bdf096df1254b02454940080 Mon Sep 17 00:00:00 2001 From: Petr Onderka Date: Thu, 8 Mar 2018 11:56:05 +0100 Subject: [PATCH] Fixes and improvements to Semantic analysis Get started --- .../get-started/semantic-analysis.md | 63 ++++++++++--------- docs/csharp/roslyn-sdk/toc.md | 4 +- .../{SemanticQuickStart => }/Program.cs | 14 ++--- .../SemanticQuickStart.csproj | 0 .../SemanticQuickStart.sln | 0 5 files changed, 38 insertions(+), 43 deletions(-) rename samples/csharp/roslyn-sdk/SemanticQuickStart/{SemanticQuickStart => }/Program.cs (89%) rename samples/csharp/roslyn-sdk/SemanticQuickStart/{SemanticQuickStart => }/SemanticQuickStart.csproj (100%) rename samples/csharp/roslyn-sdk/SemanticQuickStart/{SemanticQuickStart => }/SemanticQuickStart.sln (100%) diff --git a/docs/csharp/roslyn-sdk/get-started/semantic-analysis.md b/docs/csharp/roslyn-sdk/get-started/semantic-analysis.md index b51cad7844934..050c9ea53876b 100644 --- a/docs/csharp/roslyn-sdk/get-started/semantic-analysis.md +++ b/docs/csharp/roslyn-sdk/get-started/semantic-analysis.md @@ -20,7 +20,7 @@ In this tutorial, you explore the **Symbol** and **Binding APIs**. These APIs pr As you work more with the .NET Compiler SDK, you become familiar with the distinctions between Syntax API and the Semantic API. The **Syntax API** allows you to look at the _structure_ of a program. However, often you want richer information about the semantics or _meaning_ of a program. While a loose code file or snippet of VB or C# code can be syntactically analyzed in isolation, it's not meaningful to ask questions such as "what's the type of this variable" in a vacuum. The meaning of a type name may be dependent on assembly references, namespace imports, or other code files. Those questions are answered using the **Semantic API**, specifically the class. -An instance of is analogous to a single project as seen by the compiler and represents everything needed to compile a Visual Basic or C# program. The **compilation** includes the set of source files to be compiled, assembly references, compiler options. You can reason about the meaning of the code using all the other information in this context. A allows you to find **Symbols** - entities such as types, namespaces, members, and variables which names and other expressions refer to. The process of associating names and expressions with **Symbols** is called **Binding**. +An instance of is analogous to a single project as seen by the compiler and represents everything needed to compile a Visual Basic or C# program. The **compilation** includes the set of source files to be compiled, assembly references, and compiler options. You can reason about the meaning of the code using all the other information in this context. A allows you to find **Symbols** - entities such as types, namespaces, members, and variables which names and other expressions refer to. The process of associating names and expressions with **Symbols** is called **Binding**. Like , is an abstract class with language-specific derivatives. When creating an instance of Compilation, you must invoke a factory method on the (or ) class. @@ -31,7 +31,7 @@ In this tutorial, you look at the "Hello World" program again. This time, you qu > [!IMPORTANT] > The following samples require the **.NET Compiler SDK** installed as part of Visual Studio 2017. You can find the .NET Compiler SDK as the last optional component listed under the **Visual Studio extension development** workload. The templates aren't installed without this component. -You can see the finished code for this sample in [our GitHub samples repository](https://github.com/dotnet/samples/csharp/roslyn-sdk/SemanticQuickStart). +You can see the finished code for this sample in [our GitHub repository](https://github.com/dotnet/docs/tree/master/samples/csharp/roslyn-sdk/SemanticQuickStart). > [!NOTE] > The Syntax Tree types use inheritance to describe the different syntax elements that are valid at different locations in the program. Using these APIs often means casting properties or collection members to specific derived types. In the following examples, the assignment and the casts are separate statements, using explicitly typed variables. You can read the code to see the return types of the API and the runtime type of the objects returned. In practice, it's more common to use implicitly typed variables and rely on API names to describe the type of objects being examined. @@ -45,52 +45,53 @@ Create a new C# **Stand-Alone Code Analysis Tool** project: You're going to analyze the basic "Hello World!" program shown earlier. Add the text for the Hello World program as a constant in your `Program` class: -[!code-csharp[Declare the program test](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#1 "Declare a constant string for the program text to analyze")] +[!code-csharp[Declare the program test](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#1 "Declare a constant string for the program text to analyze")] Next, add the following code to build the syntax tree for the code text in the `programText` constant. Add the following line to your `Main` method: -[!code-csharp[Create the tree](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#2 "Create the syntax tree")] +[!code-csharp[Create the tree](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#2 "Create the syntax tree")] Next, build a from the tree you already created. The "Hello World" sample relies on the and types. You need to reference the assembly that declares those two types in your compilation. Add the following line to your `Main` method to create a compilation of your syntax tree, including the reference to the appropriate assembly: -[!code-csharp[Create the compilation](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#3 "Create the compilation for the semantic model")] +[!code-csharp[Create the compilation](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#3 "Create the compilation for the semantic model")] -The method adds references to the compilation. The method loads an assembly as a reference. +The method adds references to the compilation. The method loads an assembly as a reference. ## Querying the semantic model -Once you have a you can ask it for a for any contained in that . You can think of the semantic model as the source for all the information would normally get from intellisense. A can answer questions like "What names are in scope at this location?" "What members are accessible from this method?" "What variables are used in this block of text?" and "What does this name/expression refer to?" Add this statement to create the semantic model: +Once you have a you can ask it for a for any contained in that . You can think of the semantic model as the source for all the information you would normally get from intellisense. A can answer questions like "What names are in scope at this location?", "What members are accessible from this method?", "What variables are used in this block of text?", and "What does this name/expression refer to?" Add this statement to create the semantic model: -[!code-csharp[Create the semantic model](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#4 "Create the semantic model")] +[!code-csharp[Create the semantic model](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#4 "Create the semantic model")] ## Binding a name The creates the from the . After creating the model, you can query it to find the first `using` directive, and retrieve the symbol information for the `System` namespace. Add these two lines to your `Main` method to create the semantic model and retrieve the symbol for the first using statement: -[!code-csharp[Find the namespace symbol for the first using](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#5 "Find the namespace symbol for the first using")] +[!code-csharp[Find the namespace symbol for the first using](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#5 "Find the namespace symbol for the first using")] -The preceding code shows how to obtain a object for your HelloWorld . Once the model is obtained, the name in the first `using` directive is bound to retrieve a for the `System` namespace. The preceding code also illustrates that you use the **syntax model** to find the structure of the code; you use the **semantic model** to understand its meaning. The **syntax model** finds the string `System` in the using statement. The **semantic model** has all the information about the types defined in the `System` namespace. +The preceding code shows how to bind the name in the first `using` directive to retrieve a for the `System` namespace. The preceding code also illustrates that you use the **syntax model** to find the structure of the code; you use the **semantic model** to understand its meaning. The **syntax model** finds the string `System` in the using statement. The **semantic model** has all the information about the types defined in the `System` namespace. From the object you can obtain the using the property. This property returns the symbol this expression refers to. For expressions that don't refer to anything (such as numeric literals) this property is `null`. When the is not null, the denotes the type of the symbol. In this example, the property is a . Add the following code to your `Main` method. It retrieves the symbol for the `System` namespace and then displays all the child namespaces declared in the `System` namespace: -[!code-csharp[Display all the child namespaces](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#6 "Display all the child namespaces from this compilation")] +[!code-csharp[Display all the child namespaces](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#6 "Display all the child namespaces from this compilation")] Run the program and you should see the following output: ``` -Collections -Configuration -Deployment -Diagnostics -Globalization -IO -Reflection -Resources -Runtime -Security -StubHelpers -Text -Threading +System.Collections +System.Configuration +System.Deployment +System.Diagnostics +System.Globalization +System.IO +System.Numerics +System.Reflection +System.Resources +System.Runtime +System.Security +System.StubHelpers +System.Text +System.Threading Press any key to continue . . . ``` @@ -105,31 +106,31 @@ The "Hello World" program contains a struct includes a property that enables access to the semantic information about the type of the literal. In this example, that's the `string` type. Add a declaration that assigns this property to a local variable: -[!code-csharp[Find the semantic information about the string type](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#8 "Use the string literal to access the semantic information in the string type.")] +[!code-csharp[Find the semantic information about the string type](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#8 "Use the string literal to access the semantic information in the string type.")] To finish this tutorial, let's build a LINQ query that creates a sequence of all the public methods declared on the `string` type that return a `string`. This query gets complex, so let's build it line by line, then reconstruct it as a single query. The source for this query is the sequence of all members declared on the `string` type: -[!code-csharp[Access the sequence of members on the string type](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#9 "Access the sequence of members on the string type.")] +[!code-csharp[Access the sequence of members on the string type](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#9 "Access the sequence of members on the string type.")] That source sequence conatins all members, including properties and fields, so filter it using the method to find elements that are objects: -[!code-csharp[Filter the sequence to only methods](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#10 "Find the subset of the collection that is the methods.")] +[!code-csharp[Filter the sequence to only methods](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#10 "Find the subset of the collection that is the methods.")] Next, add another filter to return only those methods that are public and return a `string`: -[!code-csharp[Filter on return type and accessibility](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#11 "Find only the public methods that return a string.")] +[!code-csharp[Filter on return type and accessibility](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#11 "Find only the public methods that return a string.")] Select only the name property, and only distinct names by removing any overloads: -[!code-csharp[find the distinct names.](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#12 "Use the string literal to access the semantic information in the string type.")] +[!code-csharp[find the distinct names.](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#12 "Use the string literal to access the semantic information in the string type.")] You can also build the full query using the LINQ query syntax, and then display all the method names in the console: -[!code-csharp[build and display the results of this query.](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs#12 "Build and display the results of the query.")] +[!code-csharp[build and display the results of this query.](../../../../samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs#12 "Build and display the results of the query.")] Build and run the program. You should see the following output: diff --git a/docs/csharp/roslyn-sdk/toc.md b/docs/csharp/roslyn-sdk/toc.md index 943e8f205c5f9..fef630d44cffa 100644 --- a/docs/csharp/roslyn-sdk/toc.md +++ b/docs/csharp/roslyn-sdk/toc.md @@ -6,7 +6,7 @@ ## Quick starts ### [Syntax analysis](get-started/syntax-analysis.md) -### [Semantic Analysis](get-started/semantic-analysis.md) +### [Semantic analysis](get-started/semantic-analysis.md) - \ No newline at end of file + diff --git a/samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs b/samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs similarity index 89% rename from samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs rename to samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs index 09fbbc08c12ce..c306f9990497d 100644 --- a/samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/Program.cs +++ b/samples/csharp/roslyn-sdk/SemanticQuickStart/Program.cs @@ -1,14 +1,8 @@ using System; -using static System.Console; -using System.Collections.Generic; using System.Linq; -using System.Text; using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.CSharp; -using Microsoft.CodeAnalysis.CSharp.Symbols; using Microsoft.CodeAnalysis.CSharp.Syntax; -using Microsoft.CodeAnalysis.MSBuild; -using Microsoft.CodeAnalysis.Text; namespace SemanticQuickStart { @@ -37,14 +31,14 @@ static void Main(string[] args) // SyntaxTree tree = CSharpSyntaxTree.ParseText(programText); - var root = (CompilationUnitSyntax)tree.GetRoot(); + CompilationUnitSyntax root = tree.GetCompilationUnitRoot(); // // var compilation = CSharpCompilation.Create("HelloWorld") .AddReferences(MetadataReference.CreateFromFile( typeof(string).Assembly.Location)) - .AddSyntaxTrees(tree); + .AddSyntaxTrees(tree); // // @@ -52,7 +46,7 @@ static void Main(string[] args) // // - // Use the syntax tree to find "using System" + // Use the syntax tree to find "using System;" UsingDirectiveSyntax usingSystem = root.Usings[0]; NameSyntax systemName = usingSystem.Name; @@ -64,7 +58,7 @@ static void Main(string[] args) var systemSymbol = (INamespaceSymbol)nameInfo.Symbol; foreach (INamespaceSymbol ns in systemSymbol.GetNamespaceMembers()) { - Console.WriteLine(ns.Name); + Console.WriteLine(ns); } // diff --git a/samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/SemanticQuickStart.csproj b/samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart.csproj similarity index 100% rename from samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/SemanticQuickStart.csproj rename to samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart.csproj diff --git a/samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/SemanticQuickStart.sln b/samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart.sln similarity index 100% rename from samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart/SemanticQuickStart.sln rename to samples/csharp/roslyn-sdk/SemanticQuickStart/SemanticQuickStart.sln