### Umbraco Quickstart Skill Setup Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/agents-skills/backoffice-skills/quickstart.md Use the umbraco-quickstart skill to set up your Umbraco instance and extension project. It handles registration and guides development. ```bash # Full setup with custom credentials /umbraco-quickstart MyUmbracoSite MyExtension --email a@a.co.uk --password Admin123456 ``` ```bash # With default credentials (admin@test.com / SecurePass1234) /umbraco-quickstart MyUmbracoSite MyExtension ``` ```bash # No arguments — detects existing or prompts for names /umbraco-quickstart ``` -------------------------------- ### CreateChatClientAsync Example Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/reference/services/ai-chat-service.md Example of creating a chat client for advanced usage. It demonstrates configuring the client with an alias and profile, then using it to get a response with specific chat options. ```csharp // Create client for advanced usage var client = await _chatService.CreateChatClientAsync( chat => chat.WithAlias("advanced-client").WithProfile("default-chat")); // Use M.E.AI methods directly var response = await client.GetResponseAsync( messages, new ChatOptions { Temperature = 0.5f }); ``` -------------------------------- ### Get Test by ID or Alias using cURL Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/tests/api/get.md Examples demonstrate how to use cURL to fetch a test by its unique GUID or its alias. ```bash # By ID curl -X GET "https://your-site.com/umbraco/ai/management/api/v1/tests/3fa85f64-5717-4562-b3fc-2c963f66afa6" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # By alias curl -X GET "https://your-site.com/umbraco/ai/management/api/v1/tests/test-summarize-quality" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### Start Umbraco Site for Development Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/mcp/base-mcp/create-umbraco-mcp-server/development-workflow.md After initializing your project and setting up a new Umbraco instance, run this command to start the Umbraco site. This is required for the discovery command in the next phase. ```bash npm run start:umbraco ``` -------------------------------- ### Example .mcp.json File for Project Configuration Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/mcp/local-mcp-setup/claude-code.md Configure MCP servers per project using this .mcp.json file. This allows sharing configuration safely and overriding global settings. ```json { "mcpServers": { "umbraco-mcp": { "command": "npx", "args": ["@umbraco-cms/mcp-dev@latest"] } } } ``` -------------------------------- ### cURL Example: Get Context by ID Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/management-api/contexts/get.md Use this cURL command to retrieve a context by its unique identifier (GUID). Ensure to replace YOUR_ACCESS_TOKEN with your actual token. ```bash curl -X GET "https://your-site.com/umbraco/ai/management/api/v1/contexts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### Binding Syntax Examples Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-automate/concepts/bindings.md Illustrates the basic syntax for bindings, including paths and optional filters. ```text ${ } ``` ```text ${ | } ``` ```text ${ | : | : } ``` -------------------------------- ### Get Prompt by ID or Alias - cURL Examples Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/add-ons/prompt/api/get.md Use these cURL commands to retrieve a prompt's details by its unique identifier (GUID) or its alias. Ensure you replace 'YOUR_ACCESS_TOKEN' with your actual authentication token. ```bash # By ID curl -X GET "https://your-site.com/umbraco/ai/management/api/v1/prompts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ```bash # By alias curl -X GET "https://your-site.com/umbraco/ai/management/api/v1/prompts/meta-description" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### Install Endpoints Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/mcp/cms-developer-mcp/excluded-tools.md Provides endpoints for installation configuration, setup, and database validation. ```APIDOC ## GET getInstallSettings ### Description Installation configuration settings (system setup concerns). ### Method GET ### Endpoint /getInstallSettings ## POST postInstallSetup ### Description System installation functionality (system modification risk). ### Method POST ### Endpoint /postInstallSetup ## POST postInstallValidateDatabase ### Description Database validation during installation (system setup concerns). ### Method POST ### Endpoint /postInstallValidateDatabase ``` -------------------------------- ### Add Starter Kit Package Reference in .csproj Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/tutorials/starter-kit/install-the-starter-kit.md Verify the Starter Kit package reference in your project's .csproj file after installation via Visual Studio. ```xml ``` -------------------------------- ### Get Content Type by GUID Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/server-side-extensions/management/using-services/contenttypeservice.md Retrieve a single content type using its GUID identifier. Ensure the GUID is declared before calling the service. ```csharp // Declare the GUID ID Guid guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248"); // Get a reference to the content type by its GUID ID IContentType contentType = _contentTypeService.Get(guid); ``` -------------------------------- ### Prompt Deployment File Example Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/add-ons/deploy/deploying-entities.md When a Prompt is saved, a .uda file is created. If linked to a Profile or Guardrails, these dependencies are deployed first. The prompt content may include placeholders. ```text data/Revision/umbraco-ai-prompt__article-summarizer_abcd1234.uda ``` -------------------------------- ### cURL Example to List All Resource Types Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/management-api/context-resource-types/list.md Use cURL to make a GET request to the endpoint, including an Authorization header with your access token. ```bash curl -X GET "https://your-site.com/umbraco/ai/management/api/v1/context-resource-types" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### Install Project Dependencies Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/backoffice-extensions/development-flow/vite-package-setup.md Navigate into the newly created project directory and install all necessary npm packages. ```bash cd client npm install ``` -------------------------------- ### Get Children Content Types by GUID Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/server-side-extensions/management/using-services/contenttypeservice.md Retrieve all content types that are children of a specified parent content type, identified by its GUID. The GUID must be parsed into a Guid object. ```csharp IEnumerable contentTypes = _contentTypeService.GetChildren(Guid.Parse("4f89dd28-d038-4209-aaa1-06109b7946a7")); ``` -------------------------------- ### Get Content Type Container by GUID Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/server-side-extensions/management/using-services/contenttypeservice.md Retrieves a single content type container using its GUID. ```APIDOC ## Get Content Type Container by GUID ### Description Retrieves a single content type container using its GUID. ### Method `ContentTypeService.GetContainer(Guid)` ### Parameters #### Path Parameters - **guid** (Guid) - Required - The GUID of the container to retrieve. ### Response #### Success Response (200) - **EntityContainer** (EntityContainer) - The container object if found. ### Request Example ```csharp // Declare the GUID ID Guid guid = new Guid("d3b9cc9a-d471-4465-a89a-112c6bc1e5b4"); // Get a container by its GUID ID EntityContainer container = _contentTypeService.GetContainer(guid); ``` ``` -------------------------------- ### Add Starter Kit Package via .NET CLI Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/tutorials/starter-kit/install-the-starter-kit.md Use this command in your project's terminal to add the Starter Kit package. ```bash dotnet add package Umbraco.TheStarterKit ``` -------------------------------- ### Profile Deployment File Example Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/add-ons/deploy/deploying-entities.md Saving a Profile generates a .uda file with its configuration. Dependencies like referenced Connections or Guardrails are automatically deployed first. ```text data/Revision/umbraco-ai-profile__chat-assistant_abcd1234.uda ``` -------------------------------- ### Get Many Content Types by GUIDs Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/server-side-extensions/management/using-services/contenttypeservice.md Retrieves a collection of content types specified by an array of GUIDs. ```APIDOC ## Get Many Content Types by GUIDs ### Description Retrieves a collection of content types specified by an array of GUIDs. ### Method `ContentTypeService.GetMany(Guid[])` ### Parameters #### Path Parameters - **guids** (Guid[]) - Required - An array of GUIDs for the content types to retrieve. ### Response #### Success Response (200) - **IEnumerable** (IEnumerable) - A collection of the specified content types. ### Request Example ```csharp // Get a collection of two specific content types by their GUIDs IDs IEnumerable contentTypes = _contentTypeService.GetMany(new[] { new Guid("2b54088e-d355-4b9e-aa4b-5aec4b3f87eb"), new Guid("859c5916-19d8-4a72-9bd0-5641ad503aa9") }); ``` ``` -------------------------------- ### Install Highlight Extension Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/model-your-content/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions.md Install the Highlight Tiptap extension from the npm registry using npm. ```bash npm install @tiptap/extension-highlight ``` -------------------------------- ### Get Content Type by GUID Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/server-side-extensions/management/using-services/contenttypeservice.md Retrieves a single content type using its unique GUID identifier. ```APIDOC ## Get Content Type by GUID ### Description Retrieves a single content type using its unique GUID identifier. ### Method `ContentTypeService.Get(Guid)` ### Parameters #### Path Parameters - **guid** (Guid) - Required - The GUID of the content type to retrieve. ### Response #### Success Response (200) - **IContentType** (IContentType) - The content type object if found. ### Request Example ```csharp // Declare the GUID ID Guid guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248"); // Get a reference to the content type by its GUID ID IContentType contentType = _contentTypeService.Get(guid); ``` ``` -------------------------------- ### Get Member by Username Example Source: https://github.com/umbraco/umbracodocs/blob/main/umbraco-heartcore/api-documentation/content-management/member/README.md Example of a successful response when retrieving a member's details using their username. ```json { "_failedPasswordAttempts": 0, "_groups": [ "Club Blue Members" ], "_lastLoginDate": "2019-10-10T12:04:24Z", "_lastPasswordChangeDate": "2019-10-10T12:04:24Z", "_createDate": "2019-10-10T12:04:24.203Z", "_id": "153c22ad-2940-4d1c-9253-f62a2a873915", "_updateDate": "2019-10-10T12:04:24.487Z", "_links": { "self": { "href": "https://api.umbraco.io/member/john%40example.com" }, "membertype": { "href": "https://api.umbraco.io/member/type/Member" } }, "comments": "First Club Blue Member", "email": "john@example.com", "isApproved": true, "isLockedOut": false, "memberTypeAlias": "Member", "username": "john@example.com", "name": "John Doe" } ``` -------------------------------- ### Install Opinionated Umbraco Package Starter Template Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/backoffice-extensions/development-flow/umbraco-extension-template.md Use this command to install the starter template for building Umbraco packages. ```bash dotnet new install Umbraco.Community.Templates.PackageStarter ``` -------------------------------- ### Program.cs: Setup and API Consumption Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/headless-and-apis/content-delivery-api/protected-content-in-the-delivery-api/server-to-server-access.md Sets up dependency injection for API services and demonstrates consuming protected content from the Delivery API. Requires Microsoft.Extensions.Hosting and IdentityModel NuGet packages. ```csharp using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using System.Net.Http.Json; using IdentityModel.Client; var builder = Host.CreateApplicationBuilder(args); builder.Services.AddSingleton(); builder.Services.AddTransient(); using IHost host = builder.Build(); var consumer = host.Services.GetRequiredService(); await consumer.ExecuteAsync(); public static class Constants { // the base URL of the Umbraco site - change this to fit your custom setup public static string Host => "https://localhost:44391"; } // This is the API consumer, which will be listing the first few available content items - including protected ones. public class ApiConsumerService { private readonly ApiAccessTokenService _apiAccessTokenService; public ApiConsumerService(ApiAccessTokenService apiAccessTokenService) => _apiAccessTokenService = apiAccessTokenService; public async Task ExecuteAsync() { // get an access token from the access token service. var accessToken = _apiAccessTokenService.GetAccessToken(); if (accessToken is null) { Console.WriteLine("Could not get an access token, aborting."); return; } var client = new HttpClient(); client.SetBearerToken(accessToken); // fetch [pageSize] content items from the "all content" Delivery API endpoint. const int pageSize = 5; var apiResponse = await client.GetAsync($"{Constants.Host}/umbraco/delivery/api/v2/content?take={pageSize}"); var apiContentResponse = await apiResponse .EnsureSuccessStatusCode() .Content .ReadFromJsonAsync(); if (apiContentResponse is null) { Console.WriteLine("Could not parse content from the API response."); return; } Console.WriteLine($"There are {apiContentResponse.Total} items in total - listing the first {pageSize} items."); foreach (var item in apiContentResponse.Items) { Console.WriteLine($"- {item.Name} ({item.Id})"); } } } // This service ensures the reuse of access tokens for the duration of their lifetime. // It must be registered as a singleton service to work properly. public class ApiAccessTokenService { private readonly Lock _lock = new Lock(); private string? _accessToken; private DateTime _accessTokenExpiry = DateTime.MinValue; public string? GetAccessToken() { if (_accessTokenExpiry > DateTime.UtcNow) { // we already have a token, reuse it. return _accessToken; } using (_lock.EnterScope()) { if (_accessTokenExpiry > DateTime.UtcNow) { // another thread fetched a new token before this thread entered the lock, reuse it. return _accessToken; } var client = new HttpClient(); var tokenResponse = client.RequestClientCredentialsTokenAsync( new ClientCredentialsTokenRequest { Address = $"{Constants.Host}/umbraco/delivery/api/v1/security/member/token", ClientId = "umbraco-member-my-client", ClientSecret = "my-client-secret" } ) // cannot await inside a using. .GetAwaiter().GetResult(); if (tokenResponse.IsError || tokenResponse.AccessToken is null) { Console.WriteLine($"Error obtaining a token: {tokenResponse.ErrorDescription}"); return null; } _accessToken = tokenResponse.AccessToken; ``` -------------------------------- ### Get Media by GUID in Razor Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/templating-and-rendering/querying/umbracohelper.md Retrieves a media item by its GUID and accesses its URL and a specific integer property (e.g., 'umbracoHeight'). ```cshtml @{ var media = Umbraco.Media(Guid.Parse("ca4249ed-2b23-4337-b522-63cabe5587d1")); var image = media.Url(); var height = media.Value("umbracoHeight"); } ``` -------------------------------- ### Example Campaign URL with UTM Parameters Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-engage/marketers-and-editors/analytics/campaigns.md This example demonstrates how to construct a URL with multiple UTM parameters to track campaign performance. Ensure each parameter is correctly paired with its assigned value. ```none https://www.umbraco.com/pricing/?utm_source=newsletter-july-2024&utm_medium=newsletter&utm_campaign=more_signups&utm_content=bottom_button ``` -------------------------------- ### Install Specific Languages Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/configuration/installdefaultdatasettings.md Install only the specified languages, overriding the default 'en-US'. The first language listed becomes Umbraco's default for content creation. This example installs 'en-GB' and 'it'. ```json "Umbraco": { "CMS": { "InstallDefaultData": { "Languages": { "InstallData": "Values", "Values": [ "en-GB", "it" ] } } } } ``` -------------------------------- ### StartDate Property Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-commerce/reference/umbraco-commerce-core/umbraco-commerce-core-events-validation/validatediscountdaterangechange.md Gets the changing value for the start date of the discount. This property provides access to the proposed new start date for validation. ```csharp public ChangingValue StartDate { get; } ``` -------------------------------- ### Binding Examples with Filters Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-automate/concepts/bindings.md Demonstrates various ways to use bindings with different root paths and built-in filters like formatDate, truncate, and stripHtml. ```text ${ trigger.contentName } ``` ```text ${ trigger.firedAtUtc | formatDate:yyyy-MM-dd } ``` ```text ${ steps.callApi.responseBody | truncate:200 } ``` ```text ${ trigger.body | stripHtml | truncate:500 } ``` ```text ${ previous.statusCode } ``` -------------------------------- ### Get Content by GUID in Razor Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/templating-and-rendering/querying/umbracohelper.md Retrieves a specific IPublishedContent item using its GUID and displays a property value. Also iterates through its children. ```cshtml @{ var pageFromGui = Umbraco.Content(Guid.Parse("af22cb83-9bd4-454b-ab06-cc19ac8e983d")); }

@pageFromGui.Value("propertyAlias")

@foreach (var child in pageFromGui.Children()) { @child.Name } ``` -------------------------------- ### Example .env File for Project Configuration Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/mcp/local-mcp-setup/claude-code.md Use this example .env file to store local connection details for your Umbraco MCP server. Never commit live credentials to source control. ```bash UMBRACO_CLIENT_ID=umbraco-back-office-mcp UMBRACO_CLIENT_SECRET=1234567890 UMBRACO_BASE_URL=http://localhost:123456 UMBRACO_INCLUDE_TOOL_COLLECTIONS=document,media,document-type,data-type ``` -------------------------------- ### Chat Completion Example Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/using-the-api/README.md This example demonstrates how to get a chat completion response using the IAIChatService. You can specify chat configurations using `WithAlias`. ```APIDOC ## Chat Completion ```csharp var messages = new List { new(ChatRole.User, "What is Umbraco CMS?") }; var response = await _chatService.GetChatResponseAsync( chat => chat.WithAlias("content-chat"), messages); var answer = response.Message.Text; ``` ``` -------------------------------- ### Initialize Umbraco MCP Server Project Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/mcp/base-mcp/create-umbraco-mcp-server/development-workflow.md Run this command to configure your project, including setting up an Umbraco instance and choosing optional features. ```bash npx @umbraco-cms/create-umbraco-mcp-server init ``` -------------------------------- ### Get Children Content Types by Parent GUID Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/server-side-extensions/management/using-services/contenttypeservice.md Retrieves all direct child content types of a specified parent content type using its GUID. ```APIDOC ## Get Children Content Types by Parent GUID ### Description Retrieves all direct child content types of a specified parent content type using its GUID. ### Method `ContentTypeService.GetChildren(Guid)` ### Parameters #### Path Parameters - **parentGuid** (Guid) - Required - The GUID of the parent content type. ### Response #### Success Response (200) - **IEnumerable** (IEnumerable) - A collection of child content types. ### Request Example ```csharp IEnumerable contentTypes = _contentTypeService.GetChildren(Guid.Parse("4f89dd28-d038-4209-aaa1-06109b7946a7")); ``` ``` -------------------------------- ### Example Setting Customization Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-workflow/getting-started/configuration.md Demonstrates the structure for customizing individual settings within appSettings.json, allowing them to be hidden or made read-only. ```json { … "MySettingKey": { "IsHidden": false, "IsReadOnly": false, "Value": 42 } … } ``` -------------------------------- ### Amounts Property Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-commerce/reference/umbraco-commerce-core/umbraco-commerce-core-discounts-rules/orderlineamountdiscountruleprovidersettings.md Gets or sets a dictionary of GUIDs and decimal amounts. ```csharp public IDictionary Amounts { get; set; } ``` -------------------------------- ### Implement a Tool With Arguments Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/extending/tools/README.md Example of a tool that looks up inventory using SKU. It defines input arguments and uses dependency injection. ```csharp using System.ComponentModel; using Umbraco.AI.Core.Tools; public record InventoryArgs( [property: Description("The product SKU to look up")] string Sku); [AITool("lookup_inventory", "Lookup Inventory", ScopeId = "products")] public class InventoryTool : AIToolBase { private readonly IProductService _productService; public InventoryTool(IProductService productService) { _productService = productService; } public override string Description => "Looks up current inventory levels for a product by SKU."; protected override async Task ExecuteAsync( InventoryArgs args, CancellationToken cancellationToken = default) { var product = await _productService.GetBySkuAsync(args.Sku, cancellationToken); if (product == null) return new { Error = $ ``` -------------------------------- ### Example Shipping Provider Implementation Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-commerce/key-concepts/shipping-providers.md Demonstrates a basic structure for a custom Shipping Provider, including the provider class and its settings class. ```csharp [ShippingProvider("my-shipping-provider-alias")] public class MyShippingProvider : ShippingProviderBase { public MyShippingProvider(UmbracoCommerceContext umbracoCommerce) : base(umbracoCommerce) { } ... } public class MyShippingProviderSettings { [ShippingProviderSetting] public string ApiKey { get; set; } ... } ``` -------------------------------- ### GuidProvider Property Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-commerce/reference/umbraco-commerce-common/umbraco-commerce-common/guidfactory.md Gets or sets the IGuidProvider used for generating GUIDs. ```csharp public static IGuidProvider GuidProvider { get; set; } ``` -------------------------------- ### Example AIContext Creation Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/reference/models/ai-context.md Demonstrates how to create and populate an AIContext object with resources, including tone of voice and product terminology. ```csharp var context = new AIContext { Alias = "brand-guidelines", Name = "Brand Guidelines", Resources = new List { new AIContextResource { ResourceTypeId = "text", Name = "Tone of Voice", Description = "Writing style guidelines", SortOrder = 0, Settings = "Always use a friendly, professional tone...", InjectionMode = AIContextResourceInjectionMode.Always }, new AIContextResource { ResourceTypeId = "text", Name = "Product Terminology", SortOrder = 1, Settings = "Use these terms when discussing products..." } } }; ``` -------------------------------- ### Get Content Types by Multiple GUIDs Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/server-side-extensions/management/using-services/contenttypeservice.md Retrieve a collection of specific content types using an array of their GUID identifiers. This is efficient for fetching several types at once. ```csharp // Get a collection of two specific content types by their GUIDs IDs IEnumerable contentTypes = _contentTypeService.GetMany(new[] { new Guid("2b54088e-d355-4b9e-aa4b-5aec4b3f87eb"), new Guid("859c5916-19d8-4a72-9bd0-5641ad503aa9") }); ``` -------------------------------- ### Path Examples for Root Property Value Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/headless-and-apis/management-api/patching/document-endpoint-spec.md Illustrates different ways to construct paths for root-level property values. ```text /values[alias=title,culture=null,segment=null]/value ``` ```text /values[alias=title,culture=en-US,segment=null]/value ``` ```text /values[alias=description,culture=en-US,segment=desktop]/value ``` -------------------------------- ### GetChatResponseAsync Example Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/reference/services/ai-chat-service.md Example of how to use the GetChatResponseAsync method to get a chat completion. It sets up system and user messages and then prints the response message and token count. ```csharp var messages = new[] { new ChatMessage(ChatRole.System, "You are a helpful assistant."), new ChatMessage(ChatRole.User, "What is Umbraco?") }; var response = await _chatService.GetChatResponseAsync( chat => chat.WithAlias("my-assistant"), messages); Console.WriteLine(response.Message.Text); Console.WriteLine($"Tokens: {response.Usage?.TotalTokenCount}"); ``` -------------------------------- ### OrderId Property Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-commerce/reference/umbraco-commerce-core/umbraco-commerce-core-events-validation/validategiftcardorderchange.md Gets the ChangingValue representing the order ID being changed. ```csharp public ChangingValue OrderId { get; } ``` -------------------------------- ### Create and Initialize Umbraco MCP Server Project Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/mcp/base-mcp/create-umbraco-mcp-server/README.md Use these commands to create a new Umbraco MCP server project, navigate into it, install dependencies, and run the initialization wizard. ```bash npx @umbraco-cms/create-umbraco-mcp-server my-mcp-server cd my-mcp-server npm install npx @umbraco-cms/create-umbraco-mcp-server init ``` -------------------------------- ### Get Single Content Type Container by GUID Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/server-side-extensions/management/using-services/contenttypeservice.md Retrieve a specific content type container using its GUID identifier. Containers are used for organizing content types. ```csharp // Declare the GUID ID Guid guid = new Guid("d3b9cc9a-d471-4465-a89a-112c6bc1e5b4"); // Get a container by its GUID ID EntityContainer container = _contentTypeService.GetContainer(guid); ``` -------------------------------- ### Example --list-tools Output Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/mcp/base-mcp/sdk/cli.md This ASCII table shows the output of the `--list-tools` command, detailing available tools and their basic properties. ```text Name | Collection | Slices | RO | Destr | Description -----------------+------------+--------+----+-------+--------------------------------------------- get-example | example | read | Y | N | Gets an example item by ID. list-examples | example | list | Y | N | Lists all example items with pagination. create-example | example | create | N | N | Creates a new example item. delete-example | example | delete | N | Y | Deletes an example item by ID. ``` -------------------------------- ### Add Umbraco UI Builder Startup Package Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-ui-builder/getting-started/installation.md Install the Umbraco UI Builder startup package for class libraries without UI elements using the .NET CLI. ```bash dotnet add package Umbraco.UIBuilder.Startup ``` -------------------------------- ### Amounts Property Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-commerce/reference/umbraco-commerce-core/umbraco-commerce-core-discounts-rewards/orderlineamountdiscountrewardprovidersettingsbase.md Gets or sets a dictionary of amounts, keyed by GUID, for the discount reward. ```csharp public IDictionary Amounts { get; set; } ``` -------------------------------- ### UaiAudioRecorder Example Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/frontend/speech-to-text-controller.md Demonstrates a basic example of how to use the UaiAudioRecorder within a Lit element. ```APIDOC ### Example {% code title="BasicRecording.ts" %} ```typescript // Inside a Lit element #recorder = new UaiAudioRecorder(this); connectedCallback() { super.connectedCallback(); // React to state changes via Umbraco's observe helper this.observe(this.#recorder.state$, (state) => { this._recorderState = state; // "idle" | "recording" }); } async record() { await this.#recorder.start(); const audioBlob = await this.#recorder.stop(); } ``` {% endcode %} ``` -------------------------------- ### OrderLinePriceAdjustments OrderLines Property Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-commerce/reference/umbraco-commerce-core/umbraco-commerce-core-adjusters/orderlinepriceadjustments.md Gets a dictionary accessor for order lines, keyed by their GUID. ```csharp public DictionaryAccessor OrderLines { get; } ``` -------------------------------- ### Initialize NPM Package Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/extend-your-project/backoffice-extensions/development-flow/README.md Run this command to set up a package.json file in your project if one does not already exist. This is necessary for managing NPM dependencies. ```bash npm init -y ``` -------------------------------- ### Create and Configure AIPrompt Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/add-ons/prompt/reference/ai-prompt.md Example of creating and configuring an AIPrompt for generating meta descriptions. This includes setting instructions, profile, context, and scope. ```csharp var prompt = new AIPrompt { Alias = "meta-description", Name = "Generate Meta Description", Description = "Creates SEO-friendly meta descriptions", Instructions = @"Write a meta description for this web page. Title: {{pageTitle}} Content: {{bodyText}} Requirements: - Maximum 155 characters - Include the main topic - Be compelling and action-oriented", ProfileId = chatProfileId, ContextIds = [brandVoiceContextId], Tags = ["seo", "content"], IsActive = true, IncludeEntityContext = true, OptionCount = 1, DisplayMode = AIPromptDisplayMode.PropertyAction, Scope = new AIPromptScope { AllowRules = [ new AIPromptScopeRule { ContentTypeAliases = ["article", "blogPost"] } ] } }; var saved = await _promptService.SavePromptAsync(prompt); ``` -------------------------------- ### Install Compiled Package Data Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/testing-and-debugging/integration-testing.md Use this setup method to install a compiled package's data manifest before running tests. Ensure the package XML has a build action of 'EmbeddedResource'. ```csharp [SetUp] public void MySetup() { var xml = PackageMigrationResource.GetEmbeddedPackageDataManifest(this.GetType()); var packagingService = GetRequiredService(); packagingService.InstallCompiledPackageData(xml); } ``` -------------------------------- ### Get Relations by Child ID Source: https://github.com/umbraco/umbracodocs/blob/main/umbraco-heartcore/api-documentation/content-management/relation/README.md Retrieves a list of relations where the specified GUID is the child ID. ```APIDOC ## GET /relation/child/{id} ### Description Get a list of relations by their childs GUID ID. ### Method GET ### Endpoint /relation/child/{id} ### Success Response (200) - **_embedded.relations** (array) - An array of relation objects. - Each relation object contains: - **_id** (integer) - The unique identifier for the relation. - **parentId** (string) - The GUID ID of the parent item. - **childId** (string) - The GUID ID of the child item. - **relationTypeAlias** (string) - The alias of the relation type. - **comment** (string) - An optional comment about the relation. ### Response Example ```json { "_links": { "self": { "href": "https://api.umbraco.io/relation/child/e0c5f0e5-c1f0-4422-9ac0-6dbb536e8eb5" }, "relations": { "href": "https://api.umbraco.io/relation/4" } }, "_embedded": { "relations": [ { "_id": 4, "parentId": "af3e08fc-fb90-4c78-b11c-c1a0cf43bd31", "childId": "e0c5f0e5-c1f0-4422-9ac0-6dbb536e8eb5", "relationTypeAlias": "relateDocumentOnCopy", "comment": "Testing relations for relateDocumentOnCopy", "_links": { "self": { "href": "https://api.umbraco.io/relation/4" } } } ] } } ``` ``` -------------------------------- ### JavaScript Example Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/management-api/connections/create.md Example of how to create an AI provider connection using JavaScript's fetch API. ```APIDOC ## JavaScript Example ```javascript async function createConnection(connection) { const response = await fetch("/umbraco/ai/management/api/v1/connections", { method: "POST", headers: { "Content-Type": "application/json", }, credentials: "include", body: JSON.stringify(connection), }); if (!response.ok) { const error = await response.json(); throw new Error(error.detail); } return await response.json(); } // Usage const connection = await createConnection({ alias: "openai-prod", name: "OpenAI Production", providerId: "openai", settings: { apiKey: "$Umbraco:AI:Secrets:OpenAIApiKey", }, }); ``` ``` -------------------------------- ### Get Relations by Parent ID Source: https://github.com/umbraco/umbracodocs/blob/main/umbraco-heartcore/api-documentation/content-management/relation/README.md Retrieves a list of relations where the specified GUID is the parent ID. ```APIDOC ## GET /relation/parent/{id} ### Description Get a list of relations by their parents GUID ID. ### Method GET ### Endpoint /relation/parent/{id} ### Success Response (200) - **_embedded.relations** (array) - An array of relation objects. - Each relation object contains: - **_id** (integer) - The unique identifier for the relation. - **parentId** (string) - The GUID ID of the parent item. - **childId** (string) - The GUID ID of the child item. - **relationTypeAlias** (string) - The alias of the relation type. - **comment** (string) - An optional comment about the relation. ### Response Example ```json { "_links": { "self": { "href": "https://api.umbraco.io/relation/parent/af3e08fc-fb90-4c78-b11c-c1a0cf43bd31" }, "relations": { "href": "https://api.umbraco.io/relation/4" } }, "_embedded": { "relations": [ { "_id": 4, "parentId": "af3e08fc-fb90-4c78-b11c-c1a0cf43bd31", "childId": "e0c5f0e5-c1f0-4422-9ac0-6dbb536e8eb5", "relationTypeAlias": "relateDocumentOnCopy", "comment": "Testing relations for relateDocumentOnCopy", "_links": { "self": { "href": "https://api.umbraco.io/relation/4" } } } ] } } ``` ``` -------------------------------- ### Implement Custom Import on Startup Provider Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-deploy/deployment-workflow/import-on-startup.md Example of an import on startup provider that imports from a physical directory instead of a ZIP archive. It registers the custom provider using builder.DeployArtifactImportOnStartupProviders().Append(). ```csharp using Umbraco.Cms.Core; using Umbraco.Cms.Core.Composing; using Umbraco.Cms.Core.Extensions; using Umbraco.Deploy.Core; using Umbraco.Deploy.Core.OperationStatus; using Umbraco.Deploy.Infrastructure.Extensions; internal sealed class DeployImportOnStartupComposer : IComposer { public void Compose(IUmbracoBuilder builder) => builder.DeployArtifactImportOnStartupProviders() .Append(); private sealed class PhysicalDirectoryArtifactImportOnStartupProvider : IArtifactImportOnStartupProvider { private readonly IArtifactImportExportService _artifactImportExportService; private readonly ILogger _logger; private readonly string _artifactsPath; public PhysicalDirectoryArtifactImportOnStartupProvider(IArtifactImportExportService artifactImportExportService, ILogger logger, IHostEnvironment hostEnvironment) { _artifactImportExportService = artifactImportExportService; _logger = logger; _artifactsPath = hostEnvironment.MapPathContentRoot("~/umbraco/Deploy/ImportOnStartup"); } public Task CanImportAsync(CancellationToken cancellationToken = default) => Task.FromResult(Directory.Exists(_artifactsPath)); public async Task> ImportAsync(CancellationToken cancellationToken = default) { _logger.LogInformation("Importing Umbraco content and/or schema import at startup from directory {FilePath}.", _artifactsPath); Attempt attempt = await _artifactImportExportService.ImportArtifactsAsync(_artifactsPath, default, null, cancellationToken); _logger.LogInformation("Imported Umbraco content and/or schema import at startup from directory {FilePath} with status: {OperationStatus}.", _artifactsPath, attempt.Result); if (attempt.Success) { Directory.Delete(_artifactsPath, true); _logger.LogInformation("Deleted physical directory after successful import on startup {FilePath}.", _artifactsPath); } return attempt; } } } ``` -------------------------------- ### Get Media Items by IDs Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/headless-and-apis/content-delivery-api/media-delivery-api.md Retrieves one or more media items using their GUID identifiers. ```APIDOC ## GET /media/items ### Description Returns single or multiple media items by their GUIDs. ### Method GET ### Endpoint /umbraco/delivery/api/v2/media/items ### Parameters #### Query Parameters - **id** (String Array) - Required - GUIDs of the media items - **expand** (String) - Optional - Which properties to expand in the response - **fields** (String) - Optional - Which properties to include in the response (by default all properties are included) #### Headers - **Api-Key** (String) - Optional - Access token ### Response #### Success Response (200 OK) - **List of media items** - Description of the array of media item objects #### Error Responses - **401 Unauthorized** - Missing permissions after protection is set up ``` -------------------------------- ### Install Google Authentication Package Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/run-in-production/tutorials/add-google-authentication.md Use this command to add the Google authentication package to your project. ```cli dotnet add package Microsoft.AspNetCore.Authentication.Google ``` -------------------------------- ### Setting Color Value Programmatically (GUID) Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/model-your-content/property-editors/built-in-umbraco-property-editors/eye-dropper-color-picker.md This example shows how to programmatically set the value of the 'color' property on a content item using its GUID. It utilizes the IContentService and requires injecting it into your service or controller. ```csharp @using Umbraco.Cms.Core.Services @inject IContentService ContentService @{ // Create a variable for the GUID of the page you want to update var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef"); // Get the page using the GUID you've defined var content = ContentService.GetById(guid); // ID of your page // Set the value of the property with alias 'color'. content.SetValue("color", "#6fa8dc"); // Save the change ContentService.Save(content); } ``` -------------------------------- ### Example --describe-tool Output Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-in-ai/mcp/base-mcp/sdk/cli.md This JSON output represents the schema and metadata for the `get-example` tool, as generated by the `--describe-tool` command. ```json { "name": "get-example", "collection": "example", "description": "Gets an example item by ID.", "slices": ["read"], "annotations": { "readOnlyHint": true }, "inputSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "The example item ID (UUID)" } }, "required": ["id"] } } ``` -------------------------------- ### Example Data Service Implementation Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-deploy/extending/extending.md This C# code demonstrates a basic implementation of a service connector for Umbraco Deploy, handling the retrieval and processing of custom 'Example' artifacts. ```csharp public class ExampleServiceConnector : ServiceConnectorBase { private readonly IExampleDataService _exampleDataService; public ExampleServiceConnector(IExampleDataService exampleDataService) { _exampleDataService = exampleDataService ?? throw new ArgumentNullException(nameof(exampleDataService)); } public override string UdiType => "mypackage-example"; public override async Task GetRangeAsync( GuidUdi sid, string selector, CancellationToken cancellationToken = default) { if (sid.IsRoot) { return new NamedUdiRange(sid, OpenUdiName, selector); } throw new ArgumentException("Invalid identifier.", nameof(sid)); } var entity = await _exampleDataService.GetExampleByIdAsync(id, cancellationToken); if (entity == null) { throw new ArgumentException("Could not find an entity with the specified identifier.", nameof(sid)); } return new NamedUdiRange(entity.GetUdi(), entity.Name, selector); } public override async Task GetRangeAsync( GuidUdi udi, string selector, CancellationToken cancellationToken = default) { if (udi.IsRoot) { return new NamedUdiRange(udi, OpenUdiName, selector); } var entity = await _exampleDataService.GetExampleByIdAsync(udi.Guid, cancellationToken); if (entity == null) { throw new ArgumentException("Could not find an entity with the specified identifier.", nameof(udi)); } return new NamedUdiRange(udi, entity.Name, selector); } public override async Task> ProcessInitAsync( ExampleArtifact artifact, IDeployContext context, CancellationToken cancellationToken = default) { var entity = await _exampleDataService.GetExampleByIdAsync(artifact.Udi.Guid, cancellationToken); return CreateInitState(artifact, entity); } public override async Task ProcessAsync( ArtifactDeployState state, IDeployContext context, int pass, CancellationToken cancellationToken = default) { state.NextPass = GetNextPass(pass); var artifact = state.Artifact; var isNew = state.Entity == null; var entity = state.Entity ?? new Example { Id = artifact.Udi.Guid }; entity.Name = artifact.Name; entity.Description = artifact.Description; if (isNew) { await _exampleDataService.AddExampleAsync(entity, cancellationToken); } else { await _exampleDataService.UpdateExampleAsync(entity, cancellationToken); } } } ``` -------------------------------- ### Customize Default Data Installation Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/configuration/installdefaultdatasettings.md Configure which default data types (Languages, DataTypes, MediaTypes, MemberTypes) are installed. Use 'All', 'Values', 'ExceptValues', or 'None' to control installation. For DataTypes, MediaTypes, and MemberTypes, specify GUIDs in 'Values'. For Languages, use ISO codes. ```json "Umbraco": { "CMS": { "InstallDefaultData": { "Languages": { "InstallData": "Values", "Values": [ "en-US" ] }, "DataTypes": { "InstallData": "ExceptValues", "Values": [ "0225af17-b302-49cb-9176-b9f35cab9c17" ] }, "MediaTypes": { "InstallData": "All" }, "MemberTypes": { "InstallData": "None" } } } } ``` -------------------------------- ### Update Decimal Value Programmatically (GUID) Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/model-your-content/property-editors/built-in-umbraco-property-editors/decimal.md This example demonstrates how to update a decimal property value using the Content Service and a page's GUID. Note: This method is for illustrative purposes and not recommended for production. ```cshtml @using Umbraco.Cms.Core.Services @inject IContentService ContentService @{ // Create a variable for the GUID of the page you want to update var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef"); // Get the page using the GUID you've defined var content = ContentService.GetById(guid); // ID of your page // Set the value of the property with alias 'myDecimal'. content.SetValue("myDecimal", 3); // Save the change ContentService.Save(content); } ``` -------------------------------- ### Run Project via .NET CLI Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/tutorials/starter-kit/install-the-starter-kit.md Run your Umbraco project to access the installed Starter Kit. ```bash dotnet run ``` -------------------------------- ### Install TypeScript Types for Umbraco Search Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-search/extending/backoffice-extensions.md Install the `@umbraco-cms/search` package as a development dependency to get IntelliSense for Umbraco Search contexts, manifests, and shared models. Use the `next` dist-tag for prerelease versions. ```bash npm install --save-dev @umbraco-cms/search ``` ```bash npm install --save-dev @umbraco-cms/search@next ``` -------------------------------- ### Start a New Deployment Source: https://github.com/umbraco/umbracodocs/blob/main/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/umbraco-cloud-api.md Initiates a new deployment to a specified environment. Optional parameters allow control over commit messages, build processes, version checks, and schema extraction. ```http @projectId = Get this value from the portal @apiKey = Get this value from the portal @targetEnvironmentAlias = left-most or flexible environment alias @artifactId = Use artifact id from recent upload @commitMessage = My awesome commit message for cloud @noBuildAndRestore = false @skipVersionCheck = false @skipPreserveUmbracoCloudJson = false @runSchemaExtraction = true POST https://api.cloud.umbraco.com/v2/projects/{{projectId}}/deployments Umbraco-Cloud-Api-Key: {{apiKey}} Content-Type: application/json { "commitMessage": {{commitMessage}}, "artifactId": {{artifactId}}, "targetEnvironmentAlias": {{targetEnvironmentAlias}}, "noBuildAndRestore": {{noBuildAndRestore}}, "skipVersionCheck": {{skipVersionCheck}}, "skipPreserveUmbracoCloudJson": {{skipPreserveUmbracoCloudJson}}, "runSchemaExtraction": {{runSchemaExtraction}} } ``` -------------------------------- ### OrderLineAdjustments Property Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-commerce/reference/umbraco-commerce-core/umbraco-commerce-core-discounts-rewards/discountrewardcalculation.md Gets a dictionary containing order line adjustments, keyed by order line GUID. ```csharp public Dictionary OrderLineAdjustments { get; } ``` -------------------------------- ### Service Lifetime Registration Examples Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/application-code/backend-and-custom-logic/using-ioc.md Demonstrates the syntax for registering services with different lifetimes: Transient, Scoped, and Singleton. ```csharp IServiceCollection.AddTransient(); IServiceCollection.AddScoped(); IServiceCollection.AddSingleton(); ``` -------------------------------- ### Create .NET Class Library Project Source: https://github.com/umbraco/umbracodocs/blob/main/18/ai-in-umbraco/extending/providers/creating-a-provider.md Sets up a new .NET class library project and adds the necessary Umbraco AI Core package. ```bash dotnet new classlib -n MyCompany.Umbraco.AI.MyProvider -f net10.0 cd MyCompany.Umbraco.AI.MyProvider dotnet add package Umbraco.AI.Core ``` -------------------------------- ### Get Media Item by ID Source: https://github.com/umbraco/umbracodocs/blob/main/18/umbraco-cms/develop-with-umbraco/headless-and-apis/content-delivery-api/media-delivery-api.md Retrieves a single media item using its unique GUID identifier. ```APIDOC ## GET /media/item/{id} ### Description Returns a single media item by its GUID. ### Method GET ### Endpoint /umbraco/delivery/api/v2/media/item/{id} ### Parameters #### Path Parameters - **id** (String) - Required - GUID of the media item #### Query Parameters - **expand** (String) - Optional - Which properties to expand in the response - **fields** (String) - Optional - Which properties to include in the response (by default all properties are included) #### Headers - **Api-Key** (String) - Optional - Access token ### Response #### Success Response (200 OK) - **Media item** - Description of the media item object #### Error Responses - **401 Unauthorized** - Missing permissions after protection is set up - **404 Not Found** - Media item not found ```