Usando WorkflowIdentity e controle de versão

Artigo
05/09/2023

O WorkflowIdentity fornece uma maneira para que os desenvolvedores de aplicativos de fluxo de trabalho associem um nome e uma Version com uma definição de fluxo de trabalho, e para que essas informações sejam associadas a uma instância de fluxo de trabalho persistida. Essas informações de identidade podem ser usadas por desenvolvedores de aplicativos de fluxo de trabalho para habilitar cenários como execução lado a lado de várias versões de uma definição de fluxo de trabalho, e fornece o pilar para outra funcionalidade como a atualização dinâmica. Este tópico fornece uma visão geral de como usar o WorkflowIdentity com hospedagem WorkflowApplication. Para obter informações sobre como executar lado a lado as definições de fluxo de trabalho em um serviço de fluxo de trabalho, confira Side by Side Versioning in WorkflowServiceHost. Para obter informações sobre atualização dinâmica, confira Dynamic Update.

Neste tópico

Usando WorkflowIdentity

Para usar WorkflowIdentity, crie uma instância, configure-a e associe-a a uma instância WorkflowApplication. Uma instância WorkflowIdentity contém três informações de identificação. Name e Version contêm um nome e um Version e são necessários, e Package é opcional e pode ser usado para especificar uma cadeia de caracteres adicional que contém informações como o nome do assembly ou outras informações desejadas. Um WorkflowIdentity é exclusivo se qualquer uma de suas três propriedades for diferente da outra WorkflowIdentity.

Importante

Um WorkflowIdentity não deve conter informações pessoalmente identificáveis (PII). As informações sobre o WorkflowIdentity usadas para criar uma instância são emitidas para todos os serviços de rastreamento configurados em vários pontos diferentes do ciclo de vida da atividade em runtime. O Rastreamento WF não tem nenhum mecanismo para ocultar o PII (dados de usuário confidenciais). Portanto, uma instância WorkflowIdentity não deve conter nenhum dado de PII porque será emitido pelo runtime em registros de rastreamento e pode estar visível para qualquer um com acesso para exibir os registros de rastreamento.

No exemplo a seguir, WorkflowIdentity é criado e associado a uma instância de um trabalho criada usando uma definição de trabalho MortgageWorkflow.

WorkflowIdentity identityV1 = new WorkflowIdentity
{
    Name = "MortgageWorkflow v1",
    Version = new Version(1, 0, 0, 0)
};

WorkflowApplication wfApp = new WorkflowApplication(new MortgageWorkflow(), identity);

// Configure the WorkflowApplication with persistence and desired workflow event handlers.
ConfigureWorkflowApplication(wfApp);

// Run the workflow.
wfApp.Run();

Para recarregar e retomar um fluxo de trabalho, um WorkflowIdentity que está configurado para corresponder o WorkflowIdentity da instância do fluxo de trabalho persistida deve ser usado.

WorkflowApplication wfApp = new WorkflowApplication(new MortgageWorkflow(), identityV1);

// Configure the WorkflowApplication with persistence and desired workflow event handlers.
ConfigureWorkflowApplication(wfApp);

// Load the workflow.
wfApp.Load(instanceId);

// Resume the workflow...

Se o WorkflowIdentity usado ao recarregar a instância de fluxo de trabalho não corresponder ao WorkflowIdentity persistido, uma VersionMismatchException é gerada. No exemplo a seguir, uma tentativa de carregamento é feita na instância MortgageWorkflow que foi persistida no exemplo anterior. Essa tentativa de carregamento é feita usando um WorkflowIdentity configurado para uma versão mais nova do fluxo de trabalho de hipoteca que não corresponde à instância persistida.

WorkflowApplication wfApp = new WorkflowApplication(new MortgageWorkflow_v2(), identityV2);

// Configure the WorkflowApplication with persistence and desired workflow event handlers.
ConfigureWorkflowApplication(wfApp);

// Attempt to load the workflow instance.
wfApp.Load(instanceId);

// Resume the workflow...

Quando o código anterior for executado, o VersionMismatchException a seguir será gerado.

The WorkflowIdentity ('MortgageWorkflow v1; Version=1.0.0.0') of the loaded instance does not match the WorkflowIdentity ('MortgageWorkflow v2; Version=2.0.0.0') of the provided workflow definition. The instance can be loaded using a different definition, or updated using Dynamic Update.

Execução lado a lado com WorkflowIdentity

O WorkflowIdentity pode ser usado para facilitar a execução de várias versões de um fluxo de trabalho lado a lado. Um cenário comum é a mudança de requisitos comerciais em um fluxo de trabalho de execução longa. Muitas instâncias de um fluxo de trabalho podem ser executadas quando uma versão atualizada é implantada. O aplicativo de host pode ser configurado para usar a definição atualizada do fluxo de trabalho ao iniciar novas instâncias e é responsabilidade do aplicativo host fornecer a definição correta do fluxo de trabalho ao retomar instâncias. O WorkflowIdentity pode ser usado para identificar e fornecer a definição de fluxo de trabalho correspondente ao retomar instâncias de fluxo de trabalho.

Para recuperar o WorkflowIdentity de uma instância do fluxo de trabalho persistida, o método GetInstance é usado. O método GetInstance usa a Id da instância do fluxo de trabalho persistida e o SqlWorkflowInstanceStore que contém a instância persistida e retorna um WorkflowApplicationInstance. Um WorkflowApplicationInstance contém informações sobre uma instância do fluxo de trabalho persistida, incluindo o WorkflowIdentity associado. Esse WorkflowIdentity associado pode ser usado pelo host para fornecer a definição correta de fluxo de trabalho ao carregar e retomar a instância de fluxo de trabalho.

Observação

Um WorkflowIdentity nulo é válido e pode ser usado pelo host para mapear as instâncias que foram persistidas sem WorkflowIdentity associado para a definição adequada de fluxo de trabalho. Este cenário poderá ocorrer quando um aplicativo de fluxo de trabalho não tiver sido inicialmente escrito com controle de versão de fluxo de trabalho ou quando um aplicativo for atualizado do .NET Framework 4. Para obter mais informações, confira Atualização dos bancos de dados de persistência do .NET Framework 4 para oferecer suporte ao controle de versão de fluxo de trabalho.

No exemplo a seguir, oDictionary<WorkflowIdentity, Activity> é usado para associar instâncias WorkflowIdentity a suas definições de fluxo de trabalho correspondentes, e um fluxo de trabalho é iniciado usando a definição de fluxo de trabalho MortgageWorkflow, que está associada ao identityV1WorkflowIdentity.

WorkflowIdentity identityV1 = new WorkflowIdentity
{
    Name = "MortgageWorkflow v1",
    Version = new Version(1, 0, 0, 0)
};

WorkflowIdentity identityV2 = new WorkflowIdentity
{
    Name = "MortgageWorkflow v2",
    Version = new Version(2, 0, 0, 0)
};

Dictionary<WorkflowIdentity, Activity> WorkflowVersionMap = new Dictionary<WorkflowIdentity, Activity>();
WorkflowVersionMap.Add(identityV1, new MortgageWorkflow());
WorkflowVersionMap.Add(identityV2, new MortgageWorkflow_v2());

WorkflowApplication wfApp = new WorkflowApplication(new MortgageWorkflow(), identityV1);

// Configure the WorkflowApplication with persistence and desired workflow event handlers.
ConfigureWorkflowApplication(wfApp);

// Run the workflow.
wfApp.Run();

No exemplo a seguir, as informações sobre a instância do fluxo de trabalho persistida do exemplo anterior são recuperadas chamando GetInstance, e as informações persistidas do WorkflowIdentity são usadas para recuperar a definição de fluxo de trabalho correspondente. Essas informações são usadas para configurar o WorkflowApplication e, em seguida, o fluxo de trabalho é carregado. Observe que, como a sobrecarga do Load que usa o WorkflowApplicationInstance é usada, o SqlWorkflowInstanceStore que foi configurado no WorkflowApplicationInstance é usado pelo WorkflowApplication e, portanto, a propriedade de InstanceStore não precisa ser configurada.

Observação

Se a propriedade InstanceStore for definida, ela deverá ser definida com a mesma instância SqlWorkflowInstanceStore usada pelo WorkflowApplicationInstance ou um ArgumentException será gerado com a seguinte mensagem: The instance is configured with a different InstanceStore than this WorkflowApplication.

// Get the WorkflowApplicationInstance of the desired workflow from the specified
// SqlWorkflowInstanceStore.
WorkflowApplicationInstance instance = WorkflowApplication.GetInstance(instanceId, store);

// Use the persisted WorkflowIdentity to retrieve the correct workflow
// definition from the dictionary.
Activity definition = WorkflowVersionMap[instance.DefinitionIdentity];

WorkflowApplication wfApp = new WorkflowApplication(definition, instance.DefinitionIdentity);

// Configure the WorkflowApplication with persistence and desired workflow event handlers.
ConfigureWorkflowApplication(wfApp);

// Load the persisted workflow instance.
wfApp.Load(instance);

// Resume the workflow...

Atualização dos bancos de dados de persistência do .NET Framework 4 para oferecer suporte ao controle de versão de fluxo de trabalho

Um script de banco de dados SqlWorkflowInstanceStoreSchemaUpgrade.sql é fornecido para atualizar bancos de dados de persistência criados usando os scripts de banco de dados do ;NET Framework 4. Esse script atualiza os bancos de dados para dar suporte aos novos recursos de controle de versão introduzidos no .NET Framework 4.5. As instâncias de fluxo de trabalho persistidas nos bancos de dados recebem valores padrão do controle de versão e podem participar da execução lado a lado e da atualização dinâmica.

Se um aplicativo de fluxo de trabalho do .NET Framework 4.5 tentar qualquer operação de persistência que use os novos recursos de controle de versão em um banco de dados de persistência que não seja atualizado usando o script fornecido, um InstancePersistenceCommandException será gerado com uma mensagem semelhante à seguinte.

The SqlWorkflowInstanceStore has a database version of '4.0.0.0'. InstancePersistenceCommand 'System.Activities.DurableInstancing.CreateWorkflowOwnerWithIdentityCommand' cannot be run against this database version.  Please upgrade the database to '4.5.0.0'.

Para atualizar o esquema de banco de dados

Abra o SQL Server Management Studio e conecte-se ao servidor de banco de dados de persistência, por exemplo .\SQLEXPRESS.
Selecione Abrir, Arquivo no menu Arquivo. Navegue até a seguinte pasta: C:\Windows\Microsoft.NET\Framework\v4.0.30319\sql\en
Selecione SqlWorkflowInstanceStoreSchemaUpgrade.sql e clique em Abrir.
Selecione o nome do banco de dados de persistência no menu suspenso Bancos de Dados Disponíveis.
Escolha Executar no menu Consulta.

Quando a consulta tiver sido concluída, o esquema de banco de dados é atualizado e, se desejar, você poderá exibir a identidade padrão de fluxo de trabalho que foi atribuída a instâncias de fluxo de trabalho persistidas. Expanda seus bancos de dados de persistência no nó do Banco de dados do Gerenciador de objetos e expanda o nó de Exibições. Clique com o botão direito do mouse em System.Activities.DurableInstancing.Instances e escolha Selecionar as primeiras 1000 linhas. Role até o final das colunas e observe que há seis colunas adicionadas à exibição: IdentityName, IdentityPackage, Build, Major, Minor e Revision. Todos os fluxos de trabalho persistidos terão um valor NULL para esses campos, representando uma identidade do fluxo de trabalho nula.