Editing .csx: Three Questions

[KarloX2]

Environment data

dotnet --info output:
.NET Command Line Tools (1.0.0-preview2-003131)

Product Information:
Version: 1.0.0-preview2-003131
Commit SHA-1 hash: 635cf40e58

Runtime Environment:
OS Name: Windows
OS Version: 10.0.15063
OS Platform: Windows
RID: win10-x64

VS Code version: 1.18.0
C# Extension version: 1.13.0

Steps to reproduce

I want to edit .csx files. Generally that works file (IntelliSense etc.).

Question 1

Can I somehow add more pre-declared using directives and/or assembly references WITHOUT typing "using .." or "#r .." in the .csx source code, e.g. by adding them to some json file?

Question 2

Is it possible to have the documentation (from .xml files generated together with my assemblies) in the IntelliSense popups?

Question 3

When I use the #r instruction to reference an assembly, can I use a windows environment variable in the path string that follows #r ?

Thanks!

[DustinCampbell]

cc @filipw

[filipw]

Can I somehow add more pre-declared using directives and/or assembly references WITHOUT typing "using .." or "#r .." in the .csx source code, e.g. by adding them to some json file?

The easiest thing you can do for "reusable" #r directives is to place them into a separate .csx file and then reuse that .csx file (since a .csx file can load other .csx files).
For example imagine the following pseudo main.csx:

#r "lib/foo.dll"
#r "bar.dll"

using Foo;
using Bar;

var x = new TypeFromFoo();
var y = new TypeFromBar();

Console.WriteLine(x.ToString());
Console.WriteLine(y.ToString());

You could put both #r into for example references.csx:

#r "lib/foo.dll"
#r "bar.dll"

And then update the main.csx to have the following format:

#load "references.csx"

using Foo;
using Bar;

var x = new TypeFromFoo();
var y = new TypeFromBar();

Console.WriteLine(x.ToString());
Console.WriteLine(y.ToString());

This way you can reuse references.csx across various CSX files. Note that you cannot use that "shared" references.csx to contain using statetments - that's the nature of C# itself - using statements are always scoped to the current file only.

Is it possible to have the documentation (from .xml files generated together with my assemblies) in the IntelliSense popups?

Yes OmniSharp supports that. If your DLL is generated with documentation XML, and that documentation XML is located in the same folder as the DLL you are referencing, OmniSharp will load that documentation and use it in intellisense. In our above example, OmniSharp would be looking for lib/foo.XML and bar.XML documentation files. If you already have such a set up and yet still can't see the documentation, then it is a bug - please open a new issue with repro steps.

When I use the #r instruction to reference an assembly, can I use a windows environment variable in the path string that follows #r ?

No this is not supported. #r and #load are pre-processor directives and must be single line constants. This is defined in the C# spec.

Hope this helps! 🍻

[filipw]

Can I somehow add more pre-declared using directives and/or assembly references WITHOUT typing "using .." or "#r .." in the .csx source code, e.g. by adding them to some json file?

Oh, one more note about this. If you are using CSI to run your scripts it allows you to pass using statements and assembly references as command line parameters. For example you could then write our hypothetical script from my previous comment, in the following way - completely skipping usings and imports:

var x = new TypeFromFoo();
var y = new TypeFromBar();

Console.WriteLine(x.ToString());
Console.WriteLine(y.ToString());

You'd need to supply that at runtime though:

csi.exe main.csx /usings:Foo,Bar /imports:foo.dll,bar.dll

This would work for script execution. However, in such case you'd lose the possibility of getting C# language services in OmniSharp because - of course - OmniSharp wouldn't know about these missing usings and imports that only get passed in at runtime. If this is something that would be important for you, we could look into supporting such scenario via a predefined imports file.

[KarloX2]

@filipw Thanks for your comments!

The reason why I'm asking how I could add some references + usings is that I recognize that there seem to be already some defaults behind the scenes. For example, I don't need to add a "using System.Linq;" statement in my .csx file - is seems to be pre-declared and I'd like to add a few things to that list (if it exists somewhere). Is that possible?

As for the documentation. Not only my own .xml documentation isn't displayed, but also the .NET documentation (e.g. for methods like Console.WriteLine() does not appear in the IntelliSense popup. Only the signature of the method is displayed, but no help text. If there a magic switch somewhere?

Thanks

[KarloX2]

Oh, one more note about this. If you are using CSI to run your scripts it allows you to pass using statements and assembly references as command line parameters...

Yes, thanks, this is exactly the background and I want to specify using and references that way. More precisely, I don't use CSI but my own scripting host process that utilizes Microsoft.CodeAnalysis.CSharp.Scripting ("Roslyn Scripting") and my host process sets up the options in a similar way like when using CSI with the command line options you mentioned. That's why I don't like to add it again in the .csx source to satisfy the editor.

If this is something that would be important for you, we could look into supporting such scenario via a predefined imports file.

Yes, that would really be great! Is that easy to implement?

[filipw]

The reason why I'm asking how I could add some references + usings is that I recognize that there seem to be already some defaults behind the scenes. For example, I don't need to add a "using System.Linq;" statement in my .csx file - is seems to be pre-declared and I'd like to add a few things to that list (if it exists somewhere). Is that possible?

Yes there is a fixed set of references and using statements that are pre-imported. This is part of the (loosely agreed with the Roslyn Scripting team 😄) CSX standard and at the moment consists of:

• Assembly references:

System
System.Core
Microsoft.CSharp
System.ValueTuple.dll

• namespaces

System
System.IO
System.Collections.Generic
System.Console
System.Diagnostics
System.Dynamic
System.Linq
System.Linq.Expressions
System.Text
System.Threading.Tasks

Everything beyond that has to be imported by the user.

Now, in OmniSharp we try to drive scripting features from the perspective of CSI. So actually, CSI also supports the notion of .rsp files, which are effectively "seed files".
In fact, if you are on a Windows machine, and have MSBuild installed, you are likely to have a C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\MSBuild\15.0\Bin\Roslyn\csi.rsp file, which defines the defaults for CSI (as listed above).

A sample .rsp file looks like this:

/r:lib\foo.dll
/r:bar.dll
/u:Foo
/u:Bar

Looks like this would suit your needs as you could potentially benefit from using .rsp files for injecting your own namespaces and references into OmniSharp intellisense.

OmniSharp doesn't support that at the moment, but we can add it, it's not a big change - and I think it would be a nice addition as it would give you a possibility to tune OmniSharp to suit exactly the scenario like you describe - having custom CSX hosts / runners, which otherwise are difficult to capture.

[KarloX2]

@filipw
That is EXACTLY what I need!

[filipw]

@KarloX2 OK great. I spun off a new issue from our discussion OmniSharp/omnisharp-roslyn#1024

Regarding XML docs, the docs for "system" types (default references) on desktop .NET are currently not supported - this is tracked here OmniSharp/omnisharp-roslyn#685. The reason is, on desktop CLR, we reference those default system assemblies from the currently running OmniSharp process and at that moment the doc info is not available.

It is supported however in CoreCLR scripting:

Normal references (=your own DLL docs) should definitely load docs correctly, if you have a repro example could you please post in that tracking issue? Thanks! I'll have a look into this myself too.

[KarloX2]

@filipw Thanks! I created a new issue: #1858