IBlueprintCatalog
Namespace: Meshmakers.Octo.ConstructionKit.Contracts.BlueprintCatalogs
Interface for a blueprint catalog
public interface IBlueprintCatalog
Properties
Order
Returns the order of the catalog that will be used to resolve blueprints. The lower the order, the higher the priority.
public abstract int Order { get; }
Property Value
CatalogName
Returns the name of the catalog, used for identification. Catalog names must be unique.
public abstract string CatalogName { get; }
Property Value
Description
Returns the description of the catalog, used for outputs including configuration information.
public abstract string Description { get; }
Property Value
CanWrite
Returns true if the catalog can be used to publish or update blueprints, otherwise false.
public abstract bool CanWrite { get; }
Property Value
CanRead
Returns true if the catalog can be used to read blueprints, otherwise false.
public abstract bool CanRead { get; }
Property Value
Methods
RefreshCatalogAsync(Object, Boolean)
Refreshes the catalog, e.g., by reloading from disk or fetching from a remote source.
Task RefreshCatalogAsync(object sourceIdentifier, bool forceRefresh)
Parameters
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
forceRefresh Boolean
When true, bypasses any freshness short-circuit (cache TTL, unchanged
remote timestamp) and rebuilds the cache from the source unconditionally.
Returns
IsSupportingSourceIdentifier(Object)
Returns true, if the defined source identifier is supported by the catalog.
bool IsSupportingSourceIdentifier(object sourceIdentifier)
Parameters
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
Returns
IsExistingAsync(BlueprintIdVersionRange, Object)
Checks if a blueprint exists in this catalog
Task<BlueprintExistingResult> IsExistingAsync(BlueprintIdVersionRange blueprintIdVersionRange, object sourceIdentifier)
Parameters
blueprintIdVersionRange BlueprintIdVersionRange
The blueprint id with version range
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
Returns
Task<BlueprintExistingResult>
A result indicating if the blueprint exists and if yes, which version
IsExistingAsync(BlueprintId, Object)
Checks if a blueprint exists in this catalog
Task<bool> IsExistingAsync(BlueprintId blueprintId, object sourceIdentifier)
Parameters
blueprintId BlueprintId
The blueprint id
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
Returns
Task<Boolean>
True if the blueprint exists in this catalog, otherwise false
GetAsync(BlueprintId, OperationResult, Object, Nullable<CancellationToken>)
Gets a blueprint by its id
Task<BlueprintMetaRootDto> GetAsync(BlueprintId blueprintId, OperationResult operationResult, object sourceIdentifier, Nullable<CancellationToken> cancellationToken)
Parameters
blueprintId BlueprintId
The blueprint id
operationResult OperationResult
Operation results that contain validation messages occurred during deserialization.
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
cancellationToken Nullable<CancellationToken>
A cancellation token that can be used to cancel the operation
Returns
Task<BlueprintMetaRootDto>
The deserialized and validated blueprint
OpenBlueprintFileAsync(BlueprintId, String, Object, CancellationToken)
Opens a readable stream for a single file inside a blueprint's folder.
Task<Stream> OpenBlueprintFileAsync(BlueprintId blueprintId, string relativePath, object sourceIdentifier, CancellationToken cancellationToken)
Parameters
blueprintId BlueprintId
The blueprint id
relativePath String
Path to the file relative to the blueprint root, e.g.
seed-data/entities.yaml. Must use forward-slash separators and must not contain
.. or rooted segments.
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
cancellationToken CancellationToken
A cancellation token that can be used to cancel the operation
Returns
Task<Stream>
A stream positioned at the start of the file; the caller is responsible for disposing it.
Remarks:
This is the canonical way to read files (seed-data, migration scripts) that live alongside a
blueprint's blueprint.yaml. Catalog implementations are free to back this with whatever
storage they use — local file system, HTTP, embedded resources — without exposing a path.
GetBlueprintPath(BlueprintId, Object)
Caution
Use OpenBlueprintFileAsync for reading files inside a blueprint. This API is retained only for the publish path that needs an on-disk source directory.
Gets the absolute path to a blueprint's directory.
string GetBlueprintPath(BlueprintId blueprintId, object sourceIdentifier)
Parameters
blueprintId BlueprintId
The blueprint id
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
Returns
String
The absolute path to the blueprint directory
Remarks:
Retained for the publish path (IBlueprintCatalog.PublishAsync(BlueprintMetaRootDto, String, Boolean, Object, Nullable<CancellationToken>) needs an on-disk source directory). New read code should use IBlueprintCatalog.OpenBlueprintFileAsync(BlueprintId, String, Object, CancellationToken) instead — embedded-resource and remote catalogs cannot return a meaningful filesystem path.
PublishAsync(BlueprintMetaRootDto, String, Boolean, Object, Nullable<CancellationToken>)
Publishes a blueprint to the catalog
Task PublishAsync(BlueprintMetaRootDto blueprintMetaRoot, string blueprintDirectory, bool force, object sourceIdentifier, Nullable<CancellationToken> cancellationToken)
Parameters
blueprintMetaRoot BlueprintMetaRootDto
The validated blueprint
blueprintDirectory String
The directory containing the blueprint files
force Boolean
Forces the operation by replacing blueprint files if they exist.
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
cancellationToken Nullable<CancellationToken>
A cancellation token that can be used to cancel the operation
Returns
UnpublishAsync(BlueprintId, Object, Nullable<CancellationToken>)
Removes a single blueprint version from the catalog. The inverse of IBlueprintCatalog.PublishAsync(BlueprintMetaRootDto, String, Boolean, Object, Nullable<CancellationToken>): it deletes the blueprint's files and prunes the version from the catalog index, cascading up to remove the now-empty major-version and blueprint index entries when this was the last version.
Task UnpublishAsync(BlueprintId blueprintId, object sourceIdentifier, Nullable<CancellationToken> cancellationToken)
Parameters
blueprintId BlueprintId
The blueprint id (name + version) to remove
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
cancellationToken Nullable<CancellationToken>
A cancellation token that can be used to cancel the operation
Returns
Remarks:
Idempotent: a version that does not exist is a successful no-op. Throws BlueprintCatalogException only when the catalog cannot be written to or the underlying store operation fails.
UnpublishAllVersionsAsync(String, Object, Nullable<CancellationToken>)
Removes all versions of a blueprint from the catalog, including every version's files and the blueprint's complete index subtree.
Task UnpublishAllVersionsAsync(string blueprintName, object sourceIdentifier, Nullable<CancellationToken> cancellationToken)
Parameters
blueprintName String
The blueprint name (without version) to remove entirely
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
cancellationToken Nullable<CancellationToken>
A cancellation token that can be used to cancel the operation
Returns
Remarks:
Idempotent: a blueprint name with no published versions is a successful no-op. Throws BlueprintCatalogException only when the catalog cannot be written to or the underlying store operation fails.
ListAsync(Object)
Lists all blueprints in the catalog for the defined source identifier.
IAsyncEnumerable<BlueprintCatalogResultItem> ListAsync(object sourceIdentifier)
Parameters
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
Returns
IAsyncEnumerable<BlueprintCatalogResultItem>
List of blueprints that are available in the catalog
SearchAsync(String, Object)
Searches for blueprints in the catalog for the defined source identifier and search term.
IAsyncEnumerable<BlueprintCatalogResultItem> SearchAsync(string searchTerm, object sourceIdentifier)
Parameters
searchTerm String
Search term to search for in the blueprints
sourceIdentifier Object
An object, which describes the source which the catalog should search,
set it to null to use default
Returns
IAsyncEnumerable<BlueprintCatalogResultItem>
List of blueprints that match the search term