Table of Contents

Class ProjectFile

Namespace
RDCore.SDK.Workspace
Assembly
RDCore.SDK.Protocol.dll

The in-memory model of a workspace's .rdproj project file (RD-VBAL §2.2.3).

public sealed record ProjectFile : IEquatable<ProjectFile>
Inheritance
ProjectFile
Implements
Inherited Members

Remarks

It reads with JsonSerializer and nothing else, so a client of the platform, such as an IDE's add-in, reads a project's modules and files without the platform.

Constructors

ProjectFile()

A project file of an empty project, at the platform's virtual workspace (RDCoreWorkspaceUri).

public ProjectFile()

ProjectFile(ProjectFile)

A copy of source: of the same version, and as synthesized as it was, until it is written. A copy is clean.

public ProjectFile(ProjectFile source)

Parameters

source ProjectFile

The project file to copy.

ProjectFile(string)

A project file of an empty project, at uri.

public ProjectFile(string uri)

Parameters

uri string

The workspace root (Uri).

ProjectFile(string, RDCoreProject)

A project file of project, at uri, that no platform wrote yet (its Version is empty).

public ProjectFile(string uri, RDCoreProject project)

Parameters

uri string

The workspace root (Uri).

project RDCoreProject

The project the file describes.

Fields

FileName

The ProjectFile filename is the same for all instances.

public static readonly string FileName

Field Value

string

SchemaVersion

The version of the .rdproj format the platform reads and writes, as major.minor (RD-VBAL §2.2.3), which a project file is stamped with (Version). A change an older platform can still read, such as a new member, raises the minor; a change it cannot read raises the major.

public const string SchemaVersion = "1.1"

Field Value

string

Remarks

Before the format had a version of its own, a project file was stamped with the version of the platform that wrote it: 1.0.0 by the first builds, 0.1.x by the next. They read as the format 1.0 and an older one (SchemaOf(string?)), and are both the format 1.0. The format 1.1 adds the project's build section (Build).

Properties

Configuration

An array of string values containing the relative paths of configuration settings file(s) included in this project.

public string[] Configuration { get; init; }

Property Value

string[]

ExtensionData

The members of the project file this model does not know, as they were read, which are written back: a project file a newer platform wrote keeps what that platform added when an older one writes it (SchemaVersion).

[JsonExtensionData]
public Dictionary<string, JsonElement>? ExtensionData { get; init; }

Property Value

Dictionary<string, JsonElement>

IsDirty

true if the project file has unsaved changes.

[JsonIgnore]
public bool IsDirty { get; init; }

Property Value

bool

IsSynthesized

true for a project the platform made up for a folder that has no .rdproj, from the source files under it, and that was not written yet.

[JsonIgnore]
public bool IsSynthesized { get; init; }

Property Value

bool

Remarks

Opening a folder never writes a project file into it: a synthesized project lives in memory until the first change made to it - a file the client created, renamed or deleted - is saved, and it is then a .rdproj like any other (RD-VBAL §2.2.3).

ProjectInfo

Describes the workspace structure (files, folders, project references, etc.)

public RDCoreProject ProjectInfo { get; init; }

Property Value

RDCoreProject

Uri

The location of the project file on disk.

[JsonIgnore]
public string Uri { get; init; }

Property Value

string

Remarks

This property is assigned on load rather than de/serialized, and serves as the workspace root everything else is relative to.

Version

The version of the .rdproj format the project file is in (SchemaVersion): kept as it is read and copied, and stamped when it is written (WithSchemaVersion()). It is empty for a project file no platform wrote yet.

[JsonConverter(typeof(ProjectFileVersionJsonConverter))]
public string Version { get; init; }

Property Value

string

Remarks

It is read whatever it is: a number is read as its text, and anything else that is not a string as its JSON, which no format is (Unparseable). A project file is never refused for what it says here.

Methods

Equals(ProjectFile?)

Whether other is the project file at the same workspace root (Uri).

public bool Equals(ProjectFile? other)

Parameters

other ProjectFile

The project file to compare with.

Returns

bool

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

NameRangeIn(string)

Where the text of a project file writes the project's name (Name): the value of its Name member, between its quotes. An edit of that range renames the project in its file and leaves the rest of the text as it is.

public static SourceRange? NameRangeIn(string text)

Parameters

text string

The text of a project file, as FileName is read.

Returns

SourceRange?

The range, by line and character from 0; null when the text is not a JSON object, or its object has no Name member whose value is a string.

ReadAsync(Stream, string, CancellationToken)

Reads a .rdproj as the platform reads it: the project file at workspaceRoot, with what a file may leave out made empty and the standard library dropped from its references (IsStandardLibrary).

public static Task<ProjectFile> ReadAsync(Stream stream, string workspaceRoot, CancellationToken token = default)

Parameters

stream Stream

The file's content.

workspaceRoot string

The workspace root the project file is at (Uri).

token CancellationToken

Cancels the read.

Returns

Task<ProjectFile>

Remarks

A list the file gives as null ("Modules": null), or a project the file gives as null, reads as empty, and a null item of a list is left out. The file is UTF-8, with or without a byte order mark; its member names are matched as JsonSerializer matches them by default, case-sensitively, except a file entry's RelativeUri and Super, which are matched whatever their case. A file that is no JSON throws the JsonException that says where.

Exceptions

JsonException

The file is no JSON, or no JSON object.

SchemaOf(string?)

How the format a project file says it is (Version) compares with the one the platform reads and writes (SchemaVersion).

public static ProjectFileSchemaMatch SchemaOf(string? version)

Parameters

version string

What a project file says (Version).

Returns

ProjectFileSchemaMatch

Unstamped when it says nothing, Unparseable when what it says is no version, and otherwise how its major and minor compare with SchemaVersion's.

Remarks

Only the major and minor are compared, and whatever follows them is not: 1.0.0 is the format 1.0, and 0.87.2-rc3 the format 0.87. A lone number is a major: 2 is the format 2.0.

WithDocument(RDCoreFile)

The project file with document added to the project's other files; it is dirty.

public ProjectFile WithDocument(RDCoreFile document)

Parameters

document RDCoreFile

The file to add.

Returns

ProjectFile

WithFolder(string)

The project file with folder added to the project's folders; it is dirty.

public ProjectFile WithFolder(string folder)

Parameters

folder string

The folder to add, relative to the workspace root.

Returns

ProjectFile

WithModule(RDCoreModule)

The project file with module added to the project's modules; it is dirty.

public ProjectFile WithModule(RDCoreModule module)

Parameters

module RDCoreModule

The module to add.

Returns

ProjectFile

WithPrecompilerConstant(string, string)

The project file with the precompiler constant name set to value; it is dirty.

public ProjectFile WithPrecompilerConstant(string name, string value)

Parameters

name string

The constant's name.

value string

The source text of its value.

Returns

ProjectFile

WithReference(RDCoreReference)

The project file with reference added last to the project's references; it is dirty.

public ProjectFile WithReference(RDCoreReference reference)

Parameters

reference RDCoreReference

The reference to add.

Returns

ProjectFile

WithSchemaVersion()

The project file as the platform writes it, stamped with the format it writes (SchemaVersion), unless a newer format is what it says.

public ProjectFile WithSchemaVersion()

Returns

ProjectFile

Remarks

A project file of a newer format keeps its stamp: what this platform does not know of it is written back as it was read (ExtensionData), and the platform that wrote it reads it as its own. A project file of an older format, or no format, or one that cannot be read, is stamped with this one.

WithUri(string)

The project file at another workspace root (Uri); this is not a change to the project.

public ProjectFile WithUri(string uri)

Parameters

uri string

The workspace root.

Returns

ProjectFile

WithVersion(string)

The project file stamped with the version of a format (Version).

public ProjectFile WithVersion(string version)

Parameters

version string

The format's version, as major.minor.

Returns

ProjectFile

WithoutDocument(RDCoreFile)

The project file without document; it is dirty.

public ProjectFile WithoutDocument(RDCoreFile document)

Parameters

document RDCoreFile

The file to remove.

Returns

ProjectFile

WithoutFolder(string)

The project file without folder; it is dirty.

public ProjectFile WithoutFolder(string folder)

Parameters

folder string

The folder to remove.

Returns

ProjectFile

WithoutModule(RDCoreModule)

The project file without module; it is dirty.

public ProjectFile WithoutModule(RDCoreModule module)

Parameters

module RDCoreModule

The module to remove.

Returns

ProjectFile

WithoutPrecompilerConstant(string)

The project file without the precompiler constant name; it is dirty.

public ProjectFile WithoutPrecompilerConstant(string name)

Parameters

name string

The constant's name.

Returns

ProjectFile

WithoutReference(RDCoreReference)

The project file without reference; it is dirty.

public ProjectFile WithoutReference(RDCoreReference reference)

Parameters

reference RDCoreReference

The reference to remove.

Returns

ProjectFile