Class ProjectFile
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
sourceProjectFileThe project file to copy.
ProjectFile(string)
A project file of an empty project, at uri.
public ProjectFile(string uri)
Parameters
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
uristringThe workspace root (Uri).
projectRDCoreProjectThe project the file describes.
Fields
FileName
The ProjectFile filename is the same for all instances.
public static readonly string FileName
Field Value
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
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
IsDirty
true if the project file has unsaved changes.
[JsonIgnore]
public bool IsDirty { get; init; }
Property Value
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
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
Uri
The location of the project file on disk.
[JsonIgnore]
public string Uri { get; init; }
Property Value
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
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
otherProjectFileThe project file to compare with.
Returns
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
Returns
- SourceRange?
The range, by line and character from 0; null when the text is not a JSON object, or its object has no
Namemember 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
streamStreamThe file's content.
workspaceRootstringThe workspace root the project file is at (Uri).
tokenCancellationTokenCancels the read.
Returns
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
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
documentRDCoreFileThe file to add.
Returns
WithFolder(string)
The project file with folder added to the project's folders; it is dirty.
public ProjectFile WithFolder(string folder)
Parameters
folderstringThe folder to add, relative to the workspace root.
Returns
WithModule(RDCoreModule)
The project file with module added to the project's modules; it is dirty.
public ProjectFile WithModule(RDCoreModule module)
Parameters
moduleRDCoreModuleThe module to add.
Returns
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
Returns
WithReference(RDCoreReference)
The project file with reference added last to the project's references; it is dirty.
public ProjectFile WithReference(RDCoreReference reference)
Parameters
referenceRDCoreReferenceThe reference to add.
Returns
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
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
uristringThe workspace root.
Returns
WithVersion(string)
The project file stamped with the version of a format (Version).
public ProjectFile WithVersion(string version)
Parameters
versionstringThe format's version, as
major.minor.
Returns
WithoutDocument(RDCoreFile)
The project file without document; it is dirty.
public ProjectFile WithoutDocument(RDCoreFile document)
Parameters
documentRDCoreFileThe file to remove.
Returns
WithoutFolder(string)
The project file without folder; it is dirty.
public ProjectFile WithoutFolder(string folder)
Parameters
folderstringThe folder to remove.
Returns
WithoutModule(RDCoreModule)
The project file without module; it is dirty.
public ProjectFile WithoutModule(RDCoreModule module)
Parameters
moduleRDCoreModuleThe module to remove.
Returns
WithoutPrecompilerConstant(string)
The project file without the precompiler constant name; it is dirty.
public ProjectFile WithoutPrecompilerConstant(string name)
Parameters
namestringThe constant's name.
Returns
WithoutReference(RDCoreReference)
The project file without reference; it is dirty.
public ProjectFile WithoutReference(RDCoreReference reference)
Parameters
referenceRDCoreReferenceThe reference to remove.