Práca s riešeniami pomocou Dataverse SDK
V rámci vývojového životného cyklu produktov si možno budete chcieť vytvoriť vlastnú automatizáciu na vykonávanie určitých úloh. Napríklad v kanáli projektu DevOps možno budete chcieť spustiť vlastný kód alebo skript, ktorý vytvorí izolované prostredie, importuje nespravované riešenie, exportuje toto nespravované riešenie ako spravované riešenie a nakoniec dané prostredie odstráni. Toto a ešte viac môžete urobiť pomocou rozhraní API, ktoré máte k dispozícii. Nižšie uvádzame niekoľko príkladov toho, čo môžete dosiahnuť pomocou rozhraní Dataverse SDK pre .NET a vlastného kódu..
Poznámka
Rovnaké operácie môžete vykonať aj pomocou webového rozhrania API. Súvisiace akcie sú: ImportSolution, ExportSolution, CloneAsPatch a CloneAsSolution.
Pozrime sa na to, ako možno vykonať niektoré bežné operácie s riešeniami pomocou kódu C#. Ak chcete zobraziť úplnú pracovnú vzorku kódu C#, ktorá demonštruje tieto typy operácií s riešeniami (a ďalšie), pozrite si časť Ukážka: Práca s riešeniami.
Každé riešenie si vyžaduje vydavateľa, ktorého zastupuje Entita vydavateľa. Vydavateľ si vyžaduje nasledovné:
- Predpona prispôsobenia
- Jedinečný názov
- Popisný názov
Poznámka
V záujme správneho prístupu ALM na nasadzovanie prispôsobení vždy používajte vlastného vydavateľa a riešenie, nie predvolené riešenie a vydavateľa.
Nasledujúca vzorka kódu najskôr definuje vydavateľa a na základe jedinečného názvu následne skontroluje, či vydavateľ už existuje. Ak už existuje, predpona prispôsobenia sa mohla zmeniť, takže táto vzorka sa snaží získať aktuálnu predponu prispôsobenia. Získa aj PublisherId
, aby bolo možné záznam vydavateľa odstrániť. Ak sa vydavateľ nenájde, vytvorí sa nový vydavateľ pomocou metódy IOrganizationService.Vytvoriť.
// Define a new publisher
Publisher _myPublisher = new Publisher
{
UniqueName = "contoso-publisher",
FriendlyName = "Contoso publisher",
SupportingWebsiteUrl =
"https://learn.microsoft.com/powerapps/developer/data-platform/overview",
CustomizationPrefix = "contoso",
EMailAddress = "someone@contoso.com",
Description = "This publisher was created from sample code"
};
// Does the publisher already exist?
QueryExpression querySamplePublisher = new QueryExpression
{
EntityName = Publisher.EntityLogicalName,
ColumnSet = new ColumnSet("publisherid", "customizationprefix"),
Criteria = new FilterExpression()
};
querySamplePublisher.Criteria.AddCondition("uniquename", ConditionOperator.Equal,
_myPublisher.UniqueName);
EntityCollection querySamplePublisherResults =
_serviceProxy.RetrieveMultiple(querySamplePublisher);
Publisher SamplePublisherResults = null;
// If the publisher already exists, use it
if (querySamplePublisherResults.Entities.Count > 0)
{
SamplePublisherResults = (Publisher)querySamplePublisherResults.Entities[0];
_publisherId = (Guid)SamplePublisherResults.PublisherId;
_customizationPrefix = SamplePublisherResults.CustomizationPrefix;
}
// If the publisher doesn't exist, create it
if (SamplePublisherResults == null)
{
_publisherId = _serviceProxy.Create(_myPublisher);
Console.WriteLine(String.Format("Created publisher: {0}.",
_myPublisher.FriendlyName));
_customizationPrefix = _myPublisher.CustomizationPrefix;
}
Keď budete mať k dispozícii vlastného vydavateľa, môžete vytvoriť nespravované riešenie. V nasledujúcej tabuľke sú uvedené polia s popismi, ktoré riešenie obsahuje.
Označenie poľa | Opis |
---|---|
Názov zobrazenia | Názov riešenia. |
Meno | Microsoft Dataverse vygeneruje jedinečný názov na základe položky Zobrazovaný názov. Tento jedinečný názov môžete upraviť. Jedinečný názov musí obsahovať iba alfanumerické znaky alebo znak podčiarknutia. |
Vydavateľ | Na priradenie riešenia k vydavateľovi použite vyhľadávanie Vydavateľ. |
Verzia | Zadajte verziu v nasledujúcom formáte: hlavná.vedľajšia.zostava.revízia (napríklad 1.0.0.0. |
Stránka konfigurácie | Ak do svojho riešenia zahrniete webový zdroj HTML, pomocou tohto vyhľadávania ho môžete pridať ako označenú konfiguračnú stránku riešenia. |
Popis | V tomto poli môžete uviesť všetky relevantné podrobnosti o vašom riešení. |
Nižšie je uvedený ukážkový kód na vytvorenie nespravovaného riešenia, ktoré používa vydavateľa, ktorého sme vytvorili v predchádzajúcej sekcii.
// Create a solution
Solution solution = new Solution
{
UniqueName = "sample-solution",
FriendlyName = "Sample solution",
PublisherId = new EntityReference(Publisher.EntityLogicalName, _publisherId),
Description = "This solution was created by sample code.",
Version = "1.0"
};
// Check whether the solution already exists
QueryExpression queryCheckForSampleSolution = new QueryExpression
{
EntityName = Solution.EntityLogicalName,
ColumnSet = new ColumnSet(),
Criteria = new FilterExpression()
};
queryCheckForSampleSolution.Criteria.AddCondition("uniquename",
ConditionOperator.Equal, solution.UniqueName);
// Attempt to retrieve the solution
EntityCollection querySampleSolutionResults =
_serviceProxy.RetrieveMultiple(queryCheckForSampleSolution);
// Create the solution if it doesn't already exist
Solution SampleSolutionResults = null;
if (querySampleSolutionResults.Entities.Count > 0)
{
SampleSolutionResults = (Solution)querySampleSolutionResults.Entities[0];
_solutionsSampleSolutionId = (Guid)SampleSolutionResults.SolutionId;
}
if (SampleSolutionResults == null)
{
_solutionsSampleSolutionId = _serviceProxy.Create(solution);
}
Po vytvorení nespravovaného riešenia môžete súčasti riešenia pridať tak, že ich vytvoríte v kontexte tohto riešenia alebo že pridáte existujúce súčasti z iných riešení. Ďalšie informácie: Pridanie novej súčasti riešenia a Pridanie existujúcej súčasti riešenia
Táto vzorka kódu ukazuje, ako exportovať nespravované riešenie alebo zabaliť spravované riešenie. Tento kód používa triedu ExportSolutionRequest na export komprimovaného súboru, ktoré predstavuje nespravované riešenie. Možnosť vytvorenia spravovaného riešenia sa nastavuje pomocou vlastnosti Spravované. Táto vzorka uloží súbor s názvom samplesolution.zip do výstupného priečinka.
// Export a solution
ExportSolutionRequest exportSolutionRequest = new ExportSolutionRequest();
exportSolutionRequest.Managed = false;
exportSolutionRequest.SolutionName = solution.UniqueName;
ExportSolutionResponse exportSolutionResponse =
(ExportSolutionResponse)_serviceProxy.Execute(exportSolutionRequest);
byte[] exportXml = exportSolutionResponse.ExportSolutionFile;
string filename = solution.UniqueName + ".zip";
File.WriteAllBytes(outputDir + filename, exportXml);
Console.WriteLine("Solution exported to {0}.", outputDir + filename);
Import (alebo inovácia) riešenia pomocou kódu sa uskutoční pomocou položky ImportSolutionRequest.
// Install or upgrade a solution
byte[] fileBytes = File.ReadAllBytes(ManagedSolutionLocation);
ImportSolutionRequest impSolReq = new ImportSolutionRequest()
{
CustomizationFile = fileBytes
};
_serviceProxy.Execute(impSolReq);
Entitu ImportJob môžete použiť na zber údajov o úspechu importu riešenia. Keď zadáte ImportJobId
pre ImportSolutionRequest, môžete použiť túto hodnotu na dotazovanie stavu importu u entity ImportJob. ImportJobId
taktiež možno použiť na stiahnutie súboru denníka importu pomocou správy RetrieveFormattedImportJobResultsRequest.
// Monitor solution import success
byte[] fileBytesWithMonitoring = File.ReadAllBytes(ManagedSolutionLocation);
ImportSolutionRequest impSolReqWithMonitoring = new ImportSolutionRequest()
{
CustomizationFile = fileBytes,
ImportJobId = Guid.NewGuid()
};
_serviceProxy.Execute(impSolReqWithMonitoring);
ImportJob job = (ImportJob)_serviceProxy.Retrieve(ImportJob.EntityLogicalName,
impSolReqWithMonitoring.ImportJobId, new ColumnSet(new System.String[] { "data",
"solutionname" }));
System.Xml.XmlDocument doc = new System.Xml.XmlDocument();
doc.LoadXml(job.Data);
String ImportedSolutionName =
doc.SelectSingleNode("//solutionManifest/UniqueName").InnerText;
String SolutionImportResult =
doc.SelectSingleNode("//solutionManifest/result/\@result").Value;
Console.WriteLine("Report from the ImportJob data");
Console.WriteLine("Solution Unique name: {0}", ImportedSolutionName);
Console.WriteLine("Solution Import Result: {0}", SolutionImportResult);
Console.WriteLine("");
// This code displays the results for Global Option sets installed as part of a
// solution.
System.Xml.XmlNodeList optionSets = doc.SelectNodes("//optionSets/optionSet");
foreach (System.Xml.XmlNode node in optionSets)
{
string OptionSetName = node.Attributes["LocalizedName"].Value;
string result = node.FirstChild.Attributes["result"].Value;
if (result == "success")
{
Console.WriteLine("{0} result: {1}",OptionSetName, result);
}
else
{
string errorCode = node.FirstChild.Attributes["errorcode"].Value;
string errorText = node.FirstChild.Attributes["errortext"].Value;
Console.WriteLine("{0} result: {1} Code: {2} Description: {3}",OptionSetName,
result, errorCode, errorText);
}
}
Obsah vlastnosti Data
predstavuje reťazec, ktorý reprezentuje súbor XML riešenia.
Naučte sa, ako pridávať a odstraňovať súčasti riešenia pomocou kódu.
Tento príklad ukazuje, ako si môžete vytvoriť súčasť riešenia, ktorá je spojená s konkrétnym riešením. Ak súčasť riešenia nepriradíte ku konkrétnemu riešeniu, ktoré sa vytvorí, pridá sa iba k predvolenému riešeniu a budete ho musieť pridať do riešenia manuálne alebo pomocou kódu v sekcii Pridať existujúcu súčasť riešenia.
Tento kód vytvorí novú globálnu množinu možností a pridá ju do riešenia s jedinečným názvom, ktorý bude rovnaký ako _primarySolutionName
.
OptionSetMetadata optionSetMetadata = new OptionSetMetadata()
{
Name = _globalOptionSetName,
DisplayName = new Label("Example Option Set", _languageCode),
IsGlobal = true,
OptionSetType = OptionSetType.Picklist,
Options =
{
new OptionMetadata(new Label("Option 1", _languageCode), 1),
new OptionMetadata(new Label("Option 2", _languageCode), 2)
}
};
CreateOptionSetRequest createOptionSetRequest = new CreateOptionSetRequest
{
OptionSet = optionSetMetadata
};
createOptionSetRequest.SolutionUniqueName = _primarySolutionName;
_serviceProxy.Execute(createOptionSetRequest);
Tento príklad ukazuje, ako môžete pridať existujúcu súčasť riešenia do riešenia.
Nasledujúci kód používa AddSolutionComponentRequest na pridanie entity Account
ako súčasť riešenia pre nespravované riešenie.
// Add an existing Solution Component
// Add the Account entity to the solution
RetrieveEntityRequest retrieveForAddAccountRequest = new RetrieveEntityRequest()
{
LogicalName = Account.EntityLogicalName
};
RetrieveEntityResponse retrieveForAddAccountResponse = (RetrieveEntityResponse)_serviceProxy.Execute(retrieveForAddAccountRequest);
AddSolutionComponentRequest addReq = new AddSolutionComponentRequest()
{
ComponentType = (int)componenttype.Entity,
ComponentId = (Guid)retrieveForAddAccountResponse.EntityMetadata.MetadataId,
SolutionUniqueName = solution.UniqueName
};
_serviceProxy.Execute(addReq);
Tento príklad ukazuje, ako môžete odstrániť súčasť riešenia z nespravovaného riešenia. Nasledujúci kód používa RemoveSolutionComponentRequest na odstránenie súčasti riešenia entity z nespravovaného riešenia. solution.UniqueName
odkazuje na riešenie vytvorené v časti Vytvoriť nespravované riešenie.
// Remove a Solution Component
// Remove the Account entity from the solution
RetrieveEntityRequest retrieveForRemoveAccountRequest = new RetrieveEntityRequest()
{
LogicalName = Account.EntityLogicalName
};
RetrieveEntityResponse retrieveForRemoveAccountResponse = (RetrieveEntityResponse)_serviceProxy.Execute(retrieveForRemoveAccountRequest);
RemoveSolutionComponentRequest removeReq = new RemoveSolutionComponentRequest()
{
ComponentId = (Guid)retrieveForRemoveAccountResponse.EntityMetadata.MetadataId,
ComponentType = (int)componenttype.Entity,
SolutionUniqueName = solution.UniqueName
};
_serviceProxy.Execute(removeReq);
Nasledujúci príklad ukazuje, ako môžete načítať riešenie pomocou riešenia uniquename
a následne z výsledkov extrahovať solutionid
. V rámci príkladu sa potom použije solutionid
s IOrganizationService. Delete spôsob vymazania riešenia.
// Delete a solution
QueryExpression queryImportedSolution = new QueryExpression
{
EntityName = Solution.EntityLogicalName,
ColumnSet = new ColumnSet(new string[] { "solutionid", "friendlyname" }),
Criteria = new FilterExpression()
};
queryImportedSolution.Criteria.AddCondition("uniquename", ConditionOperator.Equal, ImportedSolutionName);
Solution ImportedSolution = (Solution)_serviceProxy.RetrieveMultiple(queryImportedSolution).Entities[0];
_serviceProxy.Delete(Solution.EntityLogicalName, (Guid)ImportedSolution.SolutionId);
Console.WriteLine("Deleted the {0} solution.", ImportedSolution.FriendlyName);
Pomocou dostupných rozhraní API môžete vykonať ďalšie operácie s riešením. Pre klonovacie a opravné riešenia použite CloneAsPatchRequest a CloneAsSolutionRequest. Informácie o klonovaní a opravovaní nájdete v časti Vytvorenie opráv riešení.
Pri vykonávaní aktualizácií riešení použite StageAndUpgradeRequest a DeleteAndPromoteRequest. Ďalšie informácie o procese fázovania a inováciách nájdete v sekcii Inovácia alebo aktualizácia riešenia.
Tento príklad ukazuje, ako si môžete vytvoriť zostavu, ktorá vám ukáže závislosti medzi súčasťami riešenia.
Tento kód:
Načíta všetky súčasti riešenia.
Načíta všetky závislosti jednotlivých súčastí.
Zobrazí zostavu s opisom závislosti pre každú nájdenú závislosť.
// Grab all Solution Components for a solution.
QueryByAttribute componentQuery = new QueryByAttribute
{
EntityName = SolutionComponent.EntityLogicalName,
ColumnSet = new ColumnSet("componenttype", "objectid", "solutioncomponentid", "solutionid"),
Attributes = { "solutionid" },
// In your code, this value would probably come from another query.
Values = { _primarySolutionId }
};
IEnumerable<SolutionComponent> allComponents =
_serviceProxy.RetrieveMultiple(componentQuery).Entities.Cast<SolutionComponent>();
foreach (SolutionComponent component in allComponents)
{
// For each solution component, retrieve all dependencies for the component.
RetrieveDependentComponentsRequest dependentComponentsRequest =
new RetrieveDependentComponentsRequest
{
ComponentType = component.ComponentType.Value,
ObjectId = component.ObjectId.Value
};
RetrieveDependentComponentsResponse dependentComponentsResponse =
(RetrieveDependentComponentsResponse)_serviceProxy.Execute(dependentComponentsRequest);
// If there are no dependent components, we can ignore this component.
if (dependentComponentsResponse.EntityCollection.Entities.Any() == false)
continue;
// If there are dependencies upon this solution component, and the solution
// itself is managed, then you will be unable to delete the solution.
Console.WriteLine("Found {0} dependencies for Component {1} of type {2}",
dependentComponentsResponse.EntityCollection.Entities.Count,
component.ObjectId.Value,
component.ComponentType.Value
);
//A more complete report requires more code
foreach (Dependency d in dependentComponentsResponse.EntityCollection.Entities)
{
DependencyReport(d);
}
}
Metóda DependencyReport
je v nasledujúcom príklade kódu.
Metóda DependencyReport
poskytuje priateľskejšie hlásenie na základe informácií nájdených v rámci závislosti.
Poznámka
V rámci tohto príkladu je metóda implementovaná iba čiastočne. Môže zobraziť hlásenia iba pre súčasti riešení, akými sú atribúty a množiny možností.
/// <summary>
/// Shows how to get a more friendly message based on information within the dependency
/// <param name="dependency">A Dependency returned from the RetrieveDependentComponents message</param>
/// </summary>
public void DependencyReport(Dependency dependency)
{
// These strings represent parameters for the message.
String dependentComponentName = "";
String dependentComponentTypeName = "";
String dependentComponentSolutionName = "";
String requiredComponentName = "";
String requiredComponentTypeName = "";
String requiredComponentSolutionName = "";
// The ComponentType global Option Set contains options for each possible component.
RetrieveOptionSetRequest componentTypeRequest = new RetrieveOptionSetRequest
{
Name = "componenttype"
};
RetrieveOptionSetResponse componentTypeResponse = (RetrieveOptionSetResponse)_serviceProxy.Execute(componentTypeRequest);
OptionSetMetadata componentTypeOptionSet = (OptionSetMetadata)componentTypeResponse.OptionSetMetadata;
// Match the Component type with the option value and get the label value of the option.
foreach (OptionMetadata opt in componentTypeOptionSet.Options)
{
if (dependency.DependentComponentType.Value == opt.Value)
{
dependentComponentTypeName = opt.Label.UserLocalizedLabel.Label;
}
if (dependency.RequiredComponentType.Value == opt.Value)
{
requiredComponentTypeName = opt.Label.UserLocalizedLabel.Label;
}
}
// The name or display name of the component is retrieved in different ways depending on the component type
dependentComponentName = getComponentName(dependency.DependentComponentType.Value, (Guid)dependency.DependentComponentObjectId);
requiredComponentName = getComponentName(dependency.RequiredComponentType.Value, (Guid)dependency.RequiredComponentObjectId);
// Retrieve the friendly name for the dependent solution.
Solution dependentSolution = (Solution)_serviceProxy.Retrieve
(
Solution.EntityLogicalName,
(Guid)dependency.DependentComponentBaseSolutionId,
new ColumnSet("friendlyname")
);
dependentComponentSolutionName = dependentSolution.FriendlyName;
// Retrieve the friendly name for the required solution.
Solution requiredSolution = (Solution)_serviceProxy.Retrieve
(
Solution.EntityLogicalName,
(Guid)dependency.RequiredComponentBaseSolutionId,
new ColumnSet("friendlyname")
);
requiredComponentSolutionName = requiredSolution.FriendlyName;
// Display the message
Console.WriteLine("The {0} {1} in the {2} depends on the {3} {4} in the {5} solution.",
dependentComponentName,
dependentComponentTypeName,
dependentComponentSolutionName,
requiredComponentName,
requiredComponentTypeName,
requiredComponentSolutionName);
}
Pomocou hlásenia RetrieveDependenciesForDeleteRequest identifikujte všetky ostatné súčasti riešenia, ktoré by bránili odstráneniu danej súčasti riešenia. Nasledujúci príklad kódu hľadá všetky atribúty pomocou známej globálnej množiny možností. Akýkoľvek atribút, ktorý využíva globálnu množinu možností, by zabránil odstráneniu globálnej množiny možností.
// Use the RetrieveOptionSetRequest message to retrieve
// a global option set by it's name.
RetrieveOptionSetRequest retrieveOptionSetRequest =
new RetrieveOptionSetRequest
{
Name = _globalOptionSetName
};
// Execute the request.
RetrieveOptionSetResponse retrieveOptionSetResponse =
(RetrieveOptionSetResponse)_serviceProxy.Execute(
retrieveOptionSetRequest);
_globalOptionSetId = retrieveOptionSetResponse.OptionSetMetadata.MetadataId;
if (_globalOptionSetId != null)
{
// Use the global OptionSet MetadataId with the appropriate componenttype
// to call RetrieveDependenciesForDeleteRequest
RetrieveDependenciesForDeleteRequest retrieveDependenciesForDeleteRequest = new RetrieveDependenciesForDeleteRequest
{
ComponentType = (int)componenttype.OptionSet,
ObjectId = (Guid)_globalOptionSetId
};
RetrieveDependenciesForDeleteResponse retrieveDependenciesForDeleteResponse =
(RetrieveDependenciesForDeleteResponse)_serviceProxy.Execute(retrieveDependenciesForDeleteRequest);
Console.WriteLine("");
foreach (Dependency d in retrieveDependenciesForDeleteResponse.EntityCollection.Entities)
{
if (d.DependentComponentType.Value == 2)//Just testing for Attributes
{
String attributeLabel = "";
RetrieveAttributeRequest retrieveAttributeRequest = new RetrieveAttributeRequest
{
MetadataId = (Guid)d.DependentComponentObjectId
};
RetrieveAttributeResponse retrieveAttributeResponse = (RetrieveAttributeResponse)_serviceProxy.Execute(retrieveAttributeRequest);
AttributeMetadata attmet = retrieveAttributeResponse.AttributeMetadata;
attributeLabel = attmet.DisplayName.UserLocalizedLabel.Label;
Console.WriteLine("An {0} named {1} will prevent deleting the {2} global option set.",
(componenttype)d.DependentComponentType.Value,
attributeLabel,
_globalOptionSetName);
}
}
}